Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/core/capabilities/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ A manifest describes a capability. It does not grant itself authority.
- Execution is one runtime: `executeCapability`. Each run is a vault record with an idempotency key. The same key and the same request replays; a different request under that key conflicts. The request is compared by its digest (the one a write confirms), and the broker's server ledger compares the method and URL it sends, taken before the credential is added. A write that leaves the process and then throws, or is still `running` after its deadline, is `EFFECT_UNCERTAIN` and is not retryable. Inference runs use the same words in Postgres, including `uncertain` after a stream breaks.
- Triggers are `manual`, `on_create` (once per block), `on_input_change`, and `interval`. Write and destructive stay manual. Mounting a view is not a trigger.
- HTTP capabilities are `browser_direct` or `server_broker`. A provider cannot choose: admission sets `browser_direct` unless the host's `AdmissionPolicy.brokerOrigins` names the origin, and then only for read and compute. The broker rebuilds the URL from the manifest, refuses private and metadata addresses, and refuses write and destructive effects.
- A base URL is https, carries no query or fragment, and an IP literal in it must be public. Loopback (http or https) is allowed only when the host itself built the manifest (`validateManifest(..., { hostCreated: true })`). Unsupported OpenAPI constructs fail compilation instead of becoming `any`.
- A base URL is https, carries no query or fragment, and an IP literal in it must be public. Loopback (http or https) is allowed only when the host itself built the manifest (`validateManifest(..., { hostCreated: true })`). Unsupported OpenAPI constructs fail compilation instead of becoming `any`, with one exception: a response field below the top level that declares no type is typed `any` (`ConvertOptions` in `jsonSchema.ts`), because the API does return it and an `any` source is never assignable to a typed input. A response that is untyped as a whole, or a result list of untyped items, still fails, and so does an untyped input. Admission applies the same line (`untypedResult` in `admission.ts`).
- MCP tools compile from schemas and run through `mcpClient.ts`, a thin adapter over the official TypeScript SDK v2 (`@modelcontextprotocol/client`). The SDK negotiates the protocol era (`auto`: probe 2026-07-28, fall back to the 2025 handshake) and forwards cancellation. An MCP transport carries the server's URL `origin` beside its `serverId` label. Its id hashes `origin`, `serverId` and `toolName`, so two servers that share a label are two capabilities that coexist, and its credential slot is `credentialSlot(origin, auth)`, the http rule, so they never share a secret; execution resolves the slot and passes it as per-call headers, so revoking the slot stops the next call, and refuses a bound transport whose origin is not the manifest's (`TRANSPORT_NOT_BOUND`). `createMcpHttpTransport` applies the base URL rule above (`destinationUrlErrors` in `egress.ts`) to the server URL when it is created, before any session opens: https, no embedded credentials, query or fragment, no private or metadata address, loopback only with `hostCreated: true`. Every request is sent with `redirect: 'manual'`, so a 3xx fails the request and a credentialed request is never replayed to another host. A sync MCP call is bounded by the same 15 s request timeout as HTTP. The capability store is persist version 2: `migrateCapabilityStore` moves an MCP manifest persisted before `origin` existed (it names no server URL, so none can be derived) into `stale`, kept with its stored body and named in the install panel as needing re-install, instead of letting restore reject it and the next write drop it.
- Long work uses the `async_poll` profile, never a longer request timeout. The transport is `{ kind: 'async', runtimeId, operation }`: the host binds the runtime (`asyncRuntime.ts`) and its endpoint, and a proposal cannot name one. `start` returns an external run id, which the vault ledger records before polling. Each start and each poll is still one request of at most 15 s, and the whole run is bounded by the profile's `maxDurationMs` (at most one hour): no sleep or poll request extends past that deadline, except the single observation recovery makes of a run that already outlived it. A run this session is still polling is not expired underneath it by another admission; it settles its own row. Omni never repeats a start. A write that was started and not observed to finish (deadline, repeated poll failures, or cancel) is `uncertain`. `reconcileAsyncExecution` and `recoverAsyncExecutions` read the ledger after a reload and poll the external run id; an uncertain run closes only when the destination reports a terminal status. Async capabilities run manually only. An untrusted async runtime lands at `write`, like an untrusted MCP server. The server ledger carries the same fields (`db/migrations/005_capability_async.sql`).
- Speech has a session id, a source (`unknown` until a local adapter proves otherwise), and cancel. A denied microphone is `Permission denied`, not the browser error code.
Expand Down
16 changes: 9 additions & 7 deletions src/core/capabilities/admission.ts
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@ function shapeErrors(input: unknown): string[] {
errors.push('proposal.output is required');
} else {
closed(input.output, OUTPUT_KEYS, 'proposal.output', errors);
if (containsAny(input.output.schema)) {
if (untypedResult(input.output.schema)) {
errors.push('proposal.output.schema must be typed; an untyped result is not admitted as any');
}
}
Expand Down Expand Up @@ -375,13 +375,15 @@ function closed(
}
}

function containsAny(schema: unknown, depth = 0): boolean {
if (!isRecord(schema) || depth > 32) return false;
/**
* The result, or each item of a result list, must be typed. A field inside a
* typed result may be `any`: the API does return it and its type is unknown
* (jsonSchema.ts), and an `any` source is never assignable to a typed input.
*/
function untypedResult(schema: unknown): boolean {
if (!isRecord(schema)) return false;
if (schema.kind === 'any') return true;
if (containsAny(schema.items, depth + 1)) return true;
if (isRecord(schema.additionalProperties) && containsAny(schema.additionalProperties, depth + 1)) return true;
return isRecord(schema.properties)
&& Object.values(schema.properties).some(child => containsAny(child, depth + 1));
return schema.kind === 'array' && isRecord(schema.items) && schema.items.kind === 'any';
}

function originOf(baseUrl: unknown): string | undefined {
Expand Down
50 changes: 34 additions & 16 deletions src/core/capabilities/jsonSchema.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
// JSON Schema (the subset OpenAPI and MCP actually share) → ValueType.
// Schemas we cannot represent honestly come back as an error so callers
// can fail the operation instead of pretending the contract is `any`.
// One exception, for responses only (ConvertOptions): a field below the top
// that declares no type is typed `any`. The API does return it; saying so is
// honest, and an `any` source is never assignable to a typed input, so it
// cannot carry an unknown value into a typed wire.

import { isRecord, type ValueType } from './valueType';

Expand All @@ -10,11 +14,19 @@ export type SchemaConversion =
| { ok: true; schema: ValueType }
| { ok: false; error: string };

export interface ConvertOptions {
/** 'any': an untyped schema below the top level is `any` (responses). Default: refused. */
untypedBelowTop?: 'any';
/** Internal: whether this schema is a property, item, or map value of another. */
nested?: boolean;
}

export function fromJsonSchema(
schema: unknown,
root: unknown = schema,
seen: string[] = [],
depth = 0
depth = 0,
options: ConvertOptions = {}
): SchemaConversion {
if (depth > MAX_DEPTH) return { ok: false, error: 'schema exceeds max depth' };
if (!isRecord(schema)) return { ok: false, error: 'schema must be an object' };
Expand All @@ -25,15 +37,15 @@ export function fromJsonSchema(
}
const resolved = resolveRef(root, schema.$ref);
if (!resolved) return { ok: false, error: `unresolved $ref ${schema.$ref}` };
return fromJsonSchema(resolved, root, [...seen, schema.$ref], depth + 1);
return fromJsonSchema(resolved, root, [...seen, schema.$ref], depth + 1, options);
}

if (Array.isArray(schema.allOf)) {
return mergeAllOf(schema.allOf, root, seen, depth);
return mergeAllOf(schema.allOf, root, seen, depth, options);
}
if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) {
const branches = (schema.oneOf ?? schema.anyOf) as unknown[];
if (branches.length === 1) return fromJsonSchema(branches[0], root, seen, depth + 1);
if (branches.length === 1) return fromJsonSchema(branches[0], root, seen, depth + 1, options);
return { ok: false, error: 'oneOf/anyOf with several branches is not a single ValueType' };
}
if (schema.not !== undefined) return { ok: false, error: 'not is unsupported' };
Expand All @@ -44,10 +56,10 @@ export function fromJsonSchema(
: schema.type;

if (schema.properties && rawType === undefined) {
return objectSchema(schema, nullable, root, seen, depth);
return objectSchema(schema, nullable, root, seen, depth, options);
}
if (schema.items && rawType === undefined) {
return arraySchema(schema, nullable, root, seen, depth);
return arraySchema(schema, nullable, root, seen, depth, options);
}
if (rawType === undefined && schema.enum) {
const sample = (schema.enum as unknown[])[0];
Expand All @@ -60,6 +72,7 @@ export function fromJsonSchema(
return finish({ kind, nullable: nullable || (schema.enum as unknown[]).includes(null) }, schema);
}
if (rawType === undefined) {
if (options.untypedBelowTop === 'any' && options.nested) return finish({ kind: 'any' }, schema);
return { ok: false, error: 'schema does not declare a type' };
}
if (typeof rawType !== 'string') return { ok: false, error: 'schema type is invalid' };
Expand All @@ -72,9 +85,9 @@ export function fromJsonSchema(
case 'null':
return finish({ kind: rawType, nullable: nullable && rawType !== 'null' }, schema);
case 'object':
return objectSchema(schema, nullable, root, seen, depth);
return objectSchema(schema, nullable, root, seen, depth, options);
case 'array':
return arraySchema(schema, nullable, root, seen, depth);
return arraySchema(schema, nullable, root, seen, depth, options);
default:
return { ok: false, error: `unsupported schema type ${rawType}` };
}
Expand All @@ -100,13 +113,15 @@ function objectSchema(
nullable: boolean,
root: unknown,
seen: string[],
depth: number
depth: number,
options: ConvertOptions
): SchemaConversion {
const child = { ...options, nested: true };
const properties: Record<string, ValueType> = {};
if (schema.properties !== undefined) {
if (!isRecord(schema.properties)) return { ok: false, error: 'properties must be an object' };
for (const [name, child] of Object.entries(schema.properties)) {
const converted = fromJsonSchema(child, root, seen, depth + 1);
for (const [name, property] of Object.entries(schema.properties)) {
const converted = fromJsonSchema(property, root, seen, depth + 1, child);
if (!converted.ok) return converted;
properties[name] = converted.schema;
}
Expand All @@ -117,7 +132,7 @@ function objectSchema(
let additional: ValueType['additionalProperties'];
if (schema.additionalProperties === false) additional = false;
else if (isRecord(schema.additionalProperties)) {
const converted = fromJsonSchema(schema.additionalProperties, root, seen, depth + 1);
const converted = fromJsonSchema(schema.additionalProperties, root, seen, depth + 1, child);
if (!converted.ok) return converted;
additional = converted.schema;
}
Expand All @@ -135,18 +150,21 @@ function arraySchema(
nullable: boolean,
root: unknown,
seen: string[],
depth: number
depth: number,
options: ConvertOptions
): SchemaConversion {
if (schema.items === undefined) {
return finish({ kind: 'array', nullable }, schema);
}
const converted = fromJsonSchema(schema.items, root, seen, depth + 1);
// The items of a result list are the result: they stay as nested as the list is.
const converted = fromJsonSchema(schema.items, root, seen, depth + 1, options);
if (!converted.ok) return converted;
return finish({ kind: 'array', nullable, items: converted.schema }, schema);
}

function mergeAllOf(branches: unknown[], root: unknown, seen: string[], depth: number): SchemaConversion {
const converted = branches.map(branch => fromJsonSchema(branch, root, seen, depth + 1));
function mergeAllOf(branches: unknown[], root: unknown, seen: string[], depth: number, options: ConvertOptions): SchemaConversion {
// A branch is the object itself, not a field of it.
const converted = branches.map(branch => fromJsonSchema(branch, root, seen, depth + 1, options));
const failed = converted.find(entry => !entry.ok);
if (failed && !failed.ok) return failed;
const schemas = converted.map(entry => (entry as { ok: true; schema: ValueType }).schema);
Expand Down
3 changes: 2 additions & 1 deletion src/core/capabilities/openapi.ts
Original file line number Diff line number Diff line change
Expand Up @@ -565,7 +565,8 @@ function collectOutput(
const json = jsonContent(response.content);
if (!json) return { error: 'only application/json responses are in the supported subset' };
if (json.schema === undefined) return { error: 'response schema is required' };
const converted = fromJsonSchema(json.schema, spec);
// A field the spec leaves untyped is `any`; an untyped response as a whole is still refused.
const converted = fromJsonSchema(json.schema, spec, [], 0, { untypedBelowTop: 'any' });
if (!converted.ok) return { error: converted.error };
return { output: presentationFor(converted.schema) };
}
Expand Down
79 changes: 79 additions & 0 deletions src/core/capabilities/untypedOutputFields.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
import { describe, expect, it } from 'vitest';
import { admitProposal } from './admission';
import { openapiProvider } from './providers/openapiProvider';
import { isAssignable } from './valueType';
import { fromJsonSchema } from './jsonSchema';
import { compileOpenApi } from './openapi';

/** Google Calendar's shape: one nested response field declares no type. */
function spec(response: Record<string, unknown>, parameter?: Record<string, unknown>) {
return {
openapi: '3.0.3',
info: { title: 'Events', version: '1' },
servers: [{ url: 'https://events.example.test' }],
paths: {
'/events': {
get: {
operationId: 'events.list',
...(parameter ? { parameters: [parameter] } : {}),
responses: { '200': { description: 'ok', content: { 'application/json': { schema: response } } } }
}
}
}
};
}

const EVENTS = {
type: 'object',
properties: {
items: {
type: 'array',
items: {
type: 'object',
properties: {
summary: { type: 'string' },
workingLocation: { type: 'object', properties: { homeOffice: { description: 'If present, the user is working at home.' } } }
}
}
}
}
};

describe('untyped fields in a response', () => {
it('types a nested field the spec leaves untyped as any, and keeps the operation', () => {
const { manifests, errors } = compileOpenApi(spec(EVENTS));
expect(errors).toEqual([]);
const event = manifests[0].output.schema.properties!.items.items!;
expect(event.properties!.summary.kind).toBe('string');
expect(event.properties!.workingLocation.properties!.homeOffice).toEqual({ kind: 'any', description: 'If present, the user is working at home.' });
});

it('still refuses a response that is untyped as a whole, or a list of untyped items', () => {
expect(compileOpenApi(spec({ description: 'anything' })).errors[0].message).toBe('schema does not declare a type');
expect(compileOpenApi(spec({ type: 'array', items: { description: 'anything' } })).errors[0].message).toBe('schema does not declare a type');
});

it('still refuses an untyped input', () => {
const { errors } = compileOpenApi(spec(EVENTS, { name: 'filter', in: 'query', schema: { description: 'anything' } }));
expect(errors[0].message).toBe('filter: schema does not declare a type');
});

it('is refused by default outside a response', () => {
expect(fromJsonSchema({ type: 'object', properties: { a: {} } })).toEqual({ ok: false, error: 'schema does not declare a type' });
});

it('cannot feed a typed input: an any source is not assignable to a string', () => {
expect(isAssignable({ kind: 'any' }, { kind: 'string' })).toBe(false);
});
});

describe('admitting a provider proposal with an untyped field', () => {
it('admits a typed result with a nested any field, through the same rule as the install dialog', async () => {
const request = { document: spec(EVENTS), sourceLocator: 'fixture://events', discoveredAtMs: 1 };
const { candidates } = await openapiProvider.discover(request);
const proposal = await openapiProvider.materialize(candidates[0], { request });
const admitted = admitProposal(proposal, { nowMs: 1 });
expect(admitted.errors).toEqual([]);
expect(admitted.ok).toBe(true);
});
});
Loading