@retinue/agentkit 0.2.0 → 0.3.1

package/dist/mcp-server/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * An inbound MCP server — REQ-059 (#249), task #250.
+ *
+ * `backend/src/mcp/` is the **outbound** direction: a tenant registers their MCP server and this platform
+ * consumes it. Its own header says so, and points at an inbound server that lives in the *old Chorus
+ * repository* — not in this package. So `@retinue/agentkit` could consume an MCP server and could not be one,
+ * and a deployment's tools were unreachable from Claude Code, Claude Desktop, Cursor and every other MCP client.
+ *
+ * Nothing here re-implements a capability. The registry already does authorization, the tenant's toolset, the
+ * approval gate, validation, idempotency and audit attribution; this is a protocol surface in front of it, and
+ * every call goes through `registry.execute` exactly as an agent's would.
+ *
+ * ## The trust direction inverts, and that is the thing to get right
+ *
+ * Outbound, `mcp/index.ts` establishes the rule: a remote server's `readOnlyHint`/`destructiveHint` are
+ * *advisory and untrusted*, and "a remote server cannot talk its way down to" a weaker effect. Inbound, **this
+ * package is the remote server**. Two consequences, and both are enforced rather than intended:
+ *
+ * 1. What it advertises must be what it enforces. The annotations are derived from `ToolEffect` by one
+ *    function, so they cannot drift from the effect the registry acts on.
+ * 2. Nothing the client sends is trusted — not an effect, not a hint, not a claim about a prior approval. The
+ *    client supplies a tool name and arguments; everything else comes from the context the *host* built.
+ *
+ * ## Authentication is structural
+ *
+ * `createMcpToolServer` takes a resolved `ExecutionContext`. There is no `authenticate` callback to forget and
+ * no default: a host that has not authenticated has nothing to pass, so it cannot construct a server. That is
+ * the same decision `server/main.ts` makes — "a permissive default would serve an open API to anyone who forgot
+ * to set it" — expressed in the type instead of in a runtime check, because this surface gets exposed to the
+ * internet and a runtime check can be skipped.
+ *
+ * One server per authenticated session: a stdio server is launched per client and carries that client's
+ * identity for its lifetime; an HTTP mount builds one per authenticated request.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { ToolDescriptor, ToolEffect, ToolRegistry } from "../tools/index.js";
+/**
+ * The MCP SDK, imported for its types only where possible.
+ *
+ * An **optional peer dependency**, following `vitest` on `./testing`: a consumer who never mounts an MCP server
+ * never installs it, and the only path to this module is its own subpath.
+ */
+export type McpServerLike = {
+    /**
+     * `any`, and it is the correct choice rather than a shortcut.
+     *
+     * The SDK's real signature is generic —
+     * `<T extends AnyObjectSchema>(schema: T, handler: (request: SchemaOutput<T>, extra: RequestHandlerExtra) => …)`
+     * — and this package cannot restate those generics without importing the SDK, which would stop it being an
+     * optional peer. A structural type with `unknown`/`never` parameters looks stricter and is **not assignable
+     * from** the SDK's `Server`, so the first version of this failed to typecheck at the only call site anybody
+     * will write. `check:consumer` caught it by compiling the documented sample against the packed tarball:
+     *
+     *     Argument of type 'Server<…>' is not assignable to parameter of type 'McpServerLike'
+     *       Type 'any' is not assignable to type 'never'
+     *
+     * A type nothing real satisfies is worse than a permissive one.
+     */
+    setRequestHandler(schema: any, 
+    /**
+     * The result is an object, not `unknown` — the second half of the same lesson.
+     *
+     * The SDK's handler must return a `ServerResult`, and `Promise<unknown>` is *wider* than that, so a `Server`
+     * was still not assignable even after the parameters were relaxed. A permissive object shape satisfies it
+     * in both directions.
+     */
+    handler: (request: any, extra?: any) => Promise<Record<string, unknown>>): void;
+    connect(transport: any): Promise<void>;
+};
+export type McpToolAnnotations = {
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint: boolean;
+    readonly idempotentHint: boolean;
+    /** True when the tool reaches something outside this deployment. */
+    readonly openWorldHint: boolean;
+};
+/**
+ * `ToolEffect` → MCP annotations, in **one** place — AC-7.
+ *
+ * One function, so the advertised hint and the enforced effect cannot drift: a test asserts this mapping over
+ * every effect, and the exposed set is checked against it. Two tables would be two chances to disagree, and the
+ * disagreement would be a client told a tool is read-only calling something that writes.
+ *
+ * `destructive` is the only `destructiveHint`, and `read` the only `readOnlyHint` — deliberately narrow.
+ * Over-claiming read-only is the dangerous direction: a client may skip a confirmation on it.
+ */
+export declare const annotationsFor: (effect: ToolEffect) => McpToolAnnotations;
+/**
+ * A tool's input schema, in the shape MCP requires — found by a real client.
+ *
+ * MCP's `tools/list` demands `inputSchema.type === "object"`, and the SDK's *client* validates it: a tool whose
+ * descriptor holds a Zod schema made the whole listing fail with `expected "object"` at one index. So the
+ * failure was not "one tool looks odd", it was **no tools at all**, from one non-conforming entry.
+ *
+ * Three cases, in order of fidelity:
+ *
+ * 1. Already a JSON-Schema object — pass it through unchanged. It is what execution validates against, so
+ *    advertising anything else would advertise a contract nothing enforces.
+ * 2. A Zod schema — convert it. `defineTool` documents `inputSchema` as "Zod schema or JSON-schema object", so
+ *    both are legitimate and a client deserves the real one either way.
+ * 3. Anything else — `{ type: "object" }`, permissive. Deliberately the *weaker* advertisement rather than a
+ *    refusal to list: the registry still validates the real schema on execution, so the failure direction is a
+ *    rejected call rather than an accepted bad one.
+ */
+export declare const toMcpInputSchema: (schema: unknown) => Record<string, unknown>;
+/** What a client is shown for one tool. */
+export declare const describeForMcp: (descriptor: ToolDescriptor) => {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations: McpToolAnnotations;
+};
+export type McpToolServerDeps = {
+    readonly registry: ToolRegistry;
+    /**
+     * The authenticated caller. **Required, and there is no default.**
+     *
+     * A host that has not authenticated cannot construct a server, which is the guarantee expressed in the type
+     * rather than in a check somebody can skip.
+     */
+    readonly context: ExecutionContext;
+    readonly serverInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+};
+/**
+ * The result of a `tools/call`, in MCP's shape.
+ *
+ * A refusal is `isError: true` with the reason as text — **not** a protocol error. That distinction matters: a
+ * protocol error tells the client the server is broken, and a tool refusal is a normal outcome the model should
+ * see and respond to. It is the same decision `streamModelTurn` makes for `tool-error`.
+ */
+export declare const toMcpResult: (outcome: {
+    readonly ok: true;
+    readonly data: unknown;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/**
+ * Registers the two handlers on an SDK `Server`.
+ *
+ * Takes the server rather than constructing it, so the SDK stays an optional peer of this package: the host
+ * imports `@modelcontextprotocol/sdk`, builds a `Server`, and hands it here. That also leaves the host in
+ * charge of the transport, which is where the authentication story differs between stdio and HTTP.
+ */
+export declare const registerRetinueTools: (server: McpServerLike, schemas: {
+    readonly listTools: unknown;
+    readonly callTool: unknown;
+}, deps: McpToolServerDeps) => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/index.js

@@ -0,0 +1,175 @@
+/**
+ * An inbound MCP server — REQ-059 (#249), task #250.
+ *
+ * `backend/src/mcp/` is the **outbound** direction: a tenant registers their MCP server and this platform
+ * consumes it. Its own header says so, and points at an inbound server that lives in the *old Chorus
+ * repository* — not in this package. So `@retinue/agentkit` could consume an MCP server and could not be one,
+ * and a deployment's tools were unreachable from Claude Code, Claude Desktop, Cursor and every other MCP client.
+ *
+ * Nothing here re-implements a capability. The registry already does authorization, the tenant's toolset, the
+ * approval gate, validation, idempotency and audit attribution; this is a protocol surface in front of it, and
+ * every call goes through `registry.execute` exactly as an agent's would.
+ *
+ * ## The trust direction inverts, and that is the thing to get right
+ *
+ * Outbound, `mcp/index.ts` establishes the rule: a remote server's `readOnlyHint`/`destructiveHint` are
+ * *advisory and untrusted*, and "a remote server cannot talk its way down to" a weaker effect. Inbound, **this
+ * package is the remote server**. Two consequences, and both are enforced rather than intended:
+ *
+ * 1. What it advertises must be what it enforces. The annotations are derived from `ToolEffect` by one
+ *    function, so they cannot drift from the effect the registry acts on.
+ * 2. Nothing the client sends is trusted — not an effect, not a hint, not a claim about a prior approval. The
+ *    client supplies a tool name and arguments; everything else comes from the context the *host* built.
+ *
+ * ## Authentication is structural
+ *
+ * `createMcpToolServer` takes a resolved `ExecutionContext`. There is no `authenticate` callback to forget and
+ * no default: a host that has not authenticated has nothing to pass, so it cannot construct a server. That is
+ * the same decision `server/main.ts` makes — "a permissive default would serve an open API to anyone who forgot
+ * to set it" — expressed in the type instead of in a runtime check, because this surface gets exposed to the
+ * internet and a runtime check can be skipped.
+ *
+ * One server per authenticated session: a stdio server is launched per client and carries that client's
+ * identity for its lifetime; an HTTP mount builds one per authenticated request.
+ */
+/**
+ * `zod/v4`'s converter. A static import, and it costs nothing: `zod` is already a hard dependency of this
+ * package, and the only path to this module is its own optional subpath.
+ */
+import { toJSONSchema } from "zod/v4/core";
+/**
+ * `ToolEffect` → MCP annotations, in **one** place — AC-7.
+ *
+ * One function, so the advertised hint and the enforced effect cannot drift: a test asserts this mapping over
+ * every effect, and the exposed set is checked against it. Two tables would be two chances to disagree, and the
+ * disagreement would be a client told a tool is read-only calling something that writes.
+ *
+ * `destructive` is the only `destructiveHint`, and `read` the only `readOnlyHint` — deliberately narrow.
+ * Over-claiming read-only is the dangerous direction: a client may skip a confirmation on it.
+ */
+export const annotationsFor = (effect) => ({
+    readOnlyHint: effect === "read",
+    destructiveHint: effect === "destructive",
+    // Only a read is safely repeatable without a key. Everything else declares itself non-idempotent, which is
+    // what makes a client ask before retrying.
+    idempotentHint: effect === "read",
+    openWorldHint: effect === "external-write" || effect === "destructive",
+});
+/**
+ * A tool's input schema, in the shape MCP requires — found by a real client.
+ *
+ * MCP's `tools/list` demands `inputSchema.type === "object"`, and the SDK's *client* validates it: a tool whose
+ * descriptor holds a Zod schema made the whole listing fail with `expected "object"` at one index. So the
+ * failure was not "one tool looks odd", it was **no tools at all**, from one non-conforming entry.
+ *
+ * Three cases, in order of fidelity:
+ *
+ * 1. Already a JSON-Schema object — pass it through unchanged. It is what execution validates against, so
+ *    advertising anything else would advertise a contract nothing enforces.
+ * 2. A Zod schema — convert it. `defineTool` documents `inputSchema` as "Zod schema or JSON-schema object", so
+ *    both are legitimate and a client deserves the real one either way.
+ * 3. Anything else — `{ type: "object" }`, permissive. Deliberately the *weaker* advertisement rather than a
+ *    refusal to list: the registry still validates the real schema on execution, so the failure direction is a
+ *    rejected call rather than an accepted bad one.
+ */
+export const toMcpInputSchema = (schema) => {
+    if (schema !== null && typeof schema === "object") {
+        const asJson = schema;
+        if (asJson.type === "object")
+            return schema;
+        const zodLike = schema;
+        if (typeof zodLike.safeParse === "function" || zodLike["~standard"] !== undefined) {
+            try {
+                const converted = toJSONSchema(schema);
+                if (converted.type === "object")
+                    return converted;
+            }
+            catch {
+                // A schema the converter cannot express — fall through to the permissive object rather than failing the
+                // whole listing for one tool.
+            }
+        }
+    }
+    return { type: "object" };
+};
+/** What a client is shown for one tool. */
+export const describeForMcp = (descriptor) => ({
+    name: descriptor.name,
+    title: descriptor.label,
+    description: descriptor.description,
+    inputSchema: toMcpInputSchema(descriptor.inputSchema),
+    annotations: annotationsFor(descriptor.effect),
+});
+/**
+ * The result of a `tools/call`, in MCP's shape.
+ *
+ * A refusal is `isError: true` with the reason as text — **not** a protocol error. That distinction matters: a
+ * protocol error tells the client the server is broken, and a tool refusal is a normal outcome the model should
+ * see and respond to. It is the same decision `streamModelTurn` makes for `tool-error`.
+ */
+export const toMcpResult = (outcome) => outcome.ok
+    ? { content: [{ type: "text", text: JSON.stringify(outcome.data) }] }
+    : {
+        content: [{ type: "text", text: `${outcome.error.code}: ${outcome.error.message}` }],
+        isError: true,
+    };
+/**
+ * Registers the two handlers on an SDK `Server`.
+ *
+ * Takes the server rather than constructing it, so the SDK stays an optional peer of this package: the host
+ * imports `@modelcontextprotocol/sdk`, builds a `Server`, and hands it here. That also leaves the host in
+ * charge of the transport, which is where the authentication story differs between stdio and HTTP.
+ */
+export const registerRetinueTools = (server, schemas, deps) => {
+    server.setRequestHandler(schemas.listTools, async () => {
+        /**
+         * The caller's **authorized** tools — never the whole registry.
+         *
+         * `listAuthorized` applies the tenant's toolset and the agent policy before authorization, so a tool this
+         * principal may not use is absent rather than present-and-refused. A client that cannot see a tool cannot
+         * be tempted by it, and the list is also the only place this platform states what it can do.
+         */
+        const descriptors = await deps.registry.listAuthorized(deps.context);
+        return { tools: descriptors.map(describeForMcp) };
+    });
+    server.setRequestHandler(schemas.callTool, async (request) => {
+        const params = request.params ?? {};
+        const name = typeof params.name === "string" ? params.name : "";
+        /**
+         * Straight through `registry.execute` — AC-3.
+         *
+         * Everything the registry does for an agent's call happens here for the same reason: authorization is
+         * re-checked, the tenant's toolset applies, the approval gate refuses a gated tool, arguments are validated
+         * against the advertised schema, idempotency is enforced and the audit row is written. A branch that called
+         * a tool directly would be a way around all of it, reachable by name from a client.
+         */
+        try {
+            const outcome = await deps.registry.execute(deps.context, { name, input: params.arguments ?? {} });
+            return toMcpResult(outcome);
+        }
+        catch (thrown) {
+            /**
+             * A refusal that **throws** is still a tool refusal — found by a real client, not by a fake.
+             *
+             * `registry.execute` returns `{ ok: false }` for most failures and *throws* for an unauthorized tool
+             * (`assertToolAuthorized`). Without this catch the SDK turned that into JSON-RPC `-32603`, so a client
+             * asking for a tool it may not have was told **the server is broken** rather than that it was refused.
+             * The distinction is the whole reason `isError` exists: a protocol error is not something a model can
+             * respond to, and it invites a retry against a server that is working correctly.
+             *
+             * The message only, never the thrown object — a stack or a cause chain routinely carries a URL with a
+             * token in it, and this crosses a process boundary to a client we do not control. Same rule as #143's
+             * `recordError` and `streamModelTurn`'s `tool-error`.
+             */
+            const error = thrown;
+            return toMcpResult({
+                ok: false,
+                error: {
+                    code: typeof error.code === "string" ? error.code : "internal",
+                    message: typeof error.message === "string" ? error.message : "the call was refused",
+                },
+            });
+        }
+    });
+};
+//# sourceMappingURL=index.js.map

package/dist/models/extraction.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Entity and relationship extraction through a language model — REQ-064 (#270), task #271.
+ *
+ * Lives in `models/` for the reason `vision.ts` does: boundary rule R3 keeps the Vercel AI SDK here, so the
+ * knowledge layer calls `extractGraph` and never sees `generateText`.
+ *
+ * ## Why the output is parsed leniently rather than schema-constrained
+ *
+ * The obvious approach is structured output with a JSON schema. Two measured facts in this repository say
+ * otherwise: `experimental_output` is silently ignored by `ai@7` (the option is `output`), and
+ * `jsonSchema().validate` is `undefined`, so a JSON schema is refused for structured output outright. Both were
+ * found by live calls after typechecking cleanly — the exact failure mode where a wrong option name does
+ * nothing at all.
+ *
+ * So the prompt asks for JSON, and `parseExtraction` is deliberately forgiving: it finds the JSON in whatever
+ * the model wrapped it in. That is not a workaround for a broken schema mechanism, it is the honest shape for
+ * a call whose output cannot be constrained — and it is *safe* because `sanitiseExtraction` downstream treats
+ * everything here as untrusted anyway. A chunk whose extraction is unusable contributes nothing; it never
+ * corrupts the graph.
+ */
+import { type LanguageModel } from "ai";
+/**
+ * What the model is asked for.
+ *
+ * Three things in this prompt are load-bearing and should not be trimmed:
+ *
+ * - **"only what this text states"** — extraction's characteristic failure is inventing plausible relationships
+ *   between things that merely co-occur, and those are the edges a traversal follows most confidently.
+ * - **"use exactly the names you listed"** — an edge naming an endpoint that was not extracted is dropped by
+ *   `sanitiseExtraction`, because repairing it would invent a provenance nobody asserted. Asking for
+ *   consistency up front is much cheaper than losing the edge.
+ * - **"JSON and nothing else"** — it does not always work, which is why `parseExtraction` exists, but it works
+ *   often enough to matter at one call per chunk.
+ */
+export declare const DEFAULT_EXTRACTION_PROMPT: string;
+export type ExtractGraphRequest = {
+    readonly model: LanguageModel;
+    readonly text: string;
+    readonly prompt?: string;
+    readonly maxOutputTokens?: number;
+    readonly abortSignal?: AbortSignal;
+};
+export type ExtractGraphResult = {
+    /** Whatever the model produced, already parsed but **not** validated. `sanitiseExtraction` does that. */
+    readonly extraction: {
+        readonly entities?: readonly unknown[];
+        readonly relationships?: readonly unknown[];
+    };
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+};
+/**
+ * The JSON inside whatever the model said.
+ *
+ * Three attempts, cheapest first: the whole string, a fenced block, then the outermost braces. Returns an empty
+ * extraction rather than throwing, because a chunk that produced prose is a chunk that contributes nothing —
+ * not an error that should fail an index of a document that embedded perfectly well.
+ *
+ * Exported for its own test: this is the function that decides whether a real model's output is usable, and
+ * "the model wrapped it in a fence" is not a hypothetical.
+ */
+export declare const parseExtraction: (text: string) => ExtractGraphResult["extraction"];
+/**
+ * One extraction call.
+ *
+ * The usage comes back rather than being recorded here, exactly as in `describeImage`: this module has no
+ * `ExecutionContext` and no `UsageRecorder`, and reaching for either would put a billing decision inside a
+ * provider call. AC-9 needs the number, and the caller is what has the context to attribute it to.
+ */
+export declare const extractGraph: (req: ExtractGraphRequest) => Promise<ExtractGraphResult>;
+//# sourceMappingURL=extraction.d.ts.map

package/dist/models/extraction.js

@@ -0,0 +1,118 @@
+/**
+ * Entity and relationship extraction through a language model — REQ-064 (#270), task #271.
+ *
+ * Lives in `models/` for the reason `vision.ts` does: boundary rule R3 keeps the Vercel AI SDK here, so the
+ * knowledge layer calls `extractGraph` and never sees `generateText`.
+ *
+ * ## Why the output is parsed leniently rather than schema-constrained
+ *
+ * The obvious approach is structured output with a JSON schema. Two measured facts in this repository say
+ * otherwise: `experimental_output` is silently ignored by `ai@7` (the option is `output`), and
+ * `jsonSchema().validate` is `undefined`, so a JSON schema is refused for structured output outright. Both were
+ * found by live calls after typechecking cleanly — the exact failure mode where a wrong option name does
+ * nothing at all.
+ *
+ * So the prompt asks for JSON, and `parseExtraction` is deliberately forgiving: it finds the JSON in whatever
+ * the model wrapped it in. That is not a workaround for a broken schema mechanism, it is the honest shape for
+ * a call whose output cannot be constrained — and it is *safe* because `sanitiseExtraction` downstream treats
+ * everything here as untrusted anyway. A chunk whose extraction is unusable contributes nothing; it never
+ * corrupts the graph.
+ */
+import { generateText } from "ai";
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * What the model is asked for.
+ *
+ * Three things in this prompt are load-bearing and should not be trimmed:
+ *
+ * - **"only what this text states"** — extraction's characteristic failure is inventing plausible relationships
+ *   between things that merely co-occur, and those are the edges a traversal follows most confidently.
+ * - **"use exactly the names you listed"** — an edge naming an endpoint that was not extracted is dropped by
+ *   `sanitiseExtraction`, because repairing it would invent a provenance nobody asserted. Asking for
+ *   consistency up front is much cheaper than losing the edge.
+ * - **"JSON and nothing else"** — it does not always work, which is why `parseExtraction` exists, but it works
+ *   often enough to matter at one call per chunk.
+ */
+export const DEFAULT_EXTRACTION_PROMPT = [
+    "Extract the named entities and the relationships between them from the text below.",
+    "",
+    "Report only what this text states. Do not infer a relationship from two things merely appearing together,",
+    "and do not add anything you know from elsewhere.",
+    "",
+    "For each entity give a short name, a lowercase type such as person, organisation, system, concept or place,",
+    "and a one-sentence description drawn from this text.",
+    "For each relationship give the two entity names, a short lowercase type such as depends-on, owns, part-of or",
+    "reports-to, and a one-sentence description. Use exactly the names you listed as entities.",
+    "",
+    'Answer with JSON and nothing else, in this shape:',
+    '{"entities":[{"name":"","type":"","description":""}],',
+    ' "relationships":[{"from":"","to":"","type":"","description":""}]}',
+].join("\n");
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+/**
+ * The JSON inside whatever the model said.
+ *
+ * Three attempts, cheapest first: the whole string, a fenced block, then the outermost braces. Returns an empty
+ * extraction rather than throwing, because a chunk that produced prose is a chunk that contributes nothing —
+ * not an error that should fail an index of a document that embedded perfectly well.
+ *
+ * Exported for its own test: this is the function that decides whether a real model's output is usable, and
+ * "the model wrapped it in a fence" is not a hypothetical.
+ */
+export const parseExtraction = (text) => {
+    const attempts = [text.trim()];
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+    if (fenced?.[1] !== undefined)
+        attempts.push(fenced[1].trim());
+    const first = text.indexOf("{");
+    const last = text.lastIndexOf("}");
+    if (first !== -1 && last > first)
+        attempts.push(text.slice(first, last + 1));
+    for (const attempt of attempts) {
+        if (attempt === "")
+            continue;
+        try {
+            const parsed = JSON.parse(attempt);
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // Next attempt. A parse failure here is expected often enough that logging each one would be noise.
+        }
+    }
+    return {};
+};
+/**
+ * One extraction call.
+ *
+ * The usage comes back rather than being recorded here, exactly as in `describeImage`: this module has no
+ * `ExecutionContext` and no `UsageRecorder`, and reaching for either would put a billing decision inside a
+ * provider call. AC-9 needs the number, and the caller is what has the context to attribute it to.
+ */
+export const extractGraph = async (req) => {
+    try {
+        const result = await generateText({
+            model: req.model,
+            messages: [{ role: "user", content: `${req.prompt ?? DEFAULT_EXTRACTION_PROMPT}\n\n---\n\n${req.text}` }],
+            ...(req.maxOutputTokens === undefined ? {} : { maxOutputTokens: req.maxOutputTokens }),
+            ...(req.abortSignal ? { abortSignal: req.abortSignal } : {}),
+        });
+        const usage = result.usage;
+        return {
+            extraction: parseExtraction(result.text),
+            usage: { inputTokens: num(usage?.inputTokens), outputTokens: num(usage?.outputTokens) },
+        };
+    }
+    catch (error) {
+        // Wrapped so a provider's error shape does not reach the knowledge layer, which would then have to know
+        // about three SDKs to decide whether a failure is retryable. The graph indexer catches this and the chunk
+        // contributes nothing — see AC-7.
+        throw new AgentPlatformError({
+            code: "provider_unavailable",
+            message: "The model could not extract entities from that text.",
+            retryable: true,
+        }, { cause: error });
+    }
+};
+//# sourceMappingURL=extraction.js.map

package/dist/models/index.d.ts

@@ -3,7 +3,29 @@
  *
  * Provider-neutral. Agents state a policy and a role; they never hardcode model IDs.
  */
-export declare const MODEL_PROVIDERS: readonly ["openai", "anthropic", "google", "mistral", "azure-openai", "bedrock", "openai-compatible"];
+/**
+ * The providers that actually resolve — REQ-061 (#255), task #256.
+ *
+ * `"bedrock"` was here and threw `capability_unavailable` when selected. It is gone, and removing it rather
+ * than wiring it is the decision:
+ *
+ * - **A declared provider that throws is worse than an absent one.** It typechecks, satisfies the exhaustive
+ *   `switch`, and fails at runtime for whoever selects it first — and it survived precisely because a closed
+ *   union reads as complete coverage. The type system guarantees every member is *mentioned*; only a call
+ *   finds out whether it is *served*.
+ * - **Wiring it could not be verified.** #256's AC-5 requires one real turn as evidence, and constructing a
+ *   Bedrock model needs no network — so an unverified wiring would satisfy "resolves" while leaving its first
+ *   user as its first tester. #268 settled that precedent.
+ *
+ * Nothing is lost today: nothing could select it and get a model. Adding it back is a one-line change plus a
+ * `provider-coverage.test.ts` case, and that test is what will force the verification then rather than allow
+ * the same gap again.
+ *
+ * Vertex is absent for a different reason, argued in `docs/03`: it serves the same Gemini models the `google`
+ * provider does, differing in credentials rather than model family, so a second member would make every
+ * `allowedProviders` policy name both to mean "Gemini".
+ */
+export declare const MODEL_PROVIDERS: readonly ["openai", "anthropic", "google", "mistral", "azure-openai", "openai-compatible"];
 export type ModelProvider = (typeof MODEL_PROVIDERS)[number];
 export type ModelLifecycle = "preview" | "generally-available" | "deprecated" | "retired";
 export type InputModality = "text" | "image" | "audio" | "video" | "pdf";
@@ -12,6 +34,23 @@ export type ModelCapabilities = {
     readonly structuredOutput: boolean;
     readonly reasoning: boolean;
     readonly nativeSearch: boolean;
+    /**
+     * How this model caches a repeated prompt prefix — task #247.
+     *
+     * Three values because the providers genuinely differ in a way that changes what this platform must *send*,
+     * not merely what it can expect back:
+     *
+     * - `"automatic"` — the provider caches a matching prefix on its own, with no directive. OpenAI. Nothing to
+     *   emit; the only thing that matters is that the prefix is byte-stable.
+     * - `"explicit"` — the provider caches only what is marked. Anthropic, via `cache_control` breakpoints. A
+     *   platform that emits nothing gets no caching at all here, which is how this was losing the discount.
+     * - `"none"` — no prompt caching. Emitting a directive would be an unknown field at best and an error at worst.
+     *
+     * Optional, and absent means `"none"`: an existing catalogue entry keeps behaving exactly as it did, and a
+     * provider that does cache has to be declared rather than assumed. Assuming the other way would send
+     * breakpoints to providers that reject them.
+     */
+    readonly promptCaching?: "automatic" | "explicit" | "none";
 };
 export type ModelLimits = {
     readonly contextTokens: number;

package/dist/models/index.js

@@ -4,13 +4,34 @@
  * Provider-neutral. Agents state a policy and a role; they never hardcode model IDs.
  */
 import { AgentPlatformError } from "../core/errors.js";
+/**
+ * The providers that actually resolve — REQ-061 (#255), task #256.
+ *
+ * `"bedrock"` was here and threw `capability_unavailable` when selected. It is gone, and removing it rather
+ * than wiring it is the decision:
+ *
+ * - **A declared provider that throws is worse than an absent one.** It typechecks, satisfies the exhaustive
+ *   `switch`, and fails at runtime for whoever selects it first — and it survived precisely because a closed
+ *   union reads as complete coverage. The type system guarantees every member is *mentioned*; only a call
+ *   finds out whether it is *served*.
+ * - **Wiring it could not be verified.** #256's AC-5 requires one real turn as evidence, and constructing a
+ *   Bedrock model needs no network — so an unverified wiring would satisfy "resolves" while leaving its first
+ *   user as its first tester. #268 settled that precedent.
+ *
+ * Nothing is lost today: nothing could select it and get a model. Adding it back is a one-line change plus a
+ * `provider-coverage.test.ts` case, and that test is what will force the verification then rather than allow
+ * the same gap again.
+ *
+ * Vertex is absent for a different reason, argued in `docs/03`: it serves the same Gemini models the `google`
+ * provider does, differing in credentials rather than model family, so a second member would make every
+ * `allowedProviders` policy name both to mean "Gemini".
+ */
 export const MODEL_PROVIDERS = [
     "openai",
     "anthropic",
     "google",
     "mistral",
     "azure-openai",
-    "bedrock",
     "openai-compatible",
 ];
 const covers = (have, need) => need.every((n) => have.includes(n));

package/dist/models/pricing.d.ts

@@ -17,6 +17,8 @@ export declare const computeModelCostMinorUnits: (pricing: ModelPricing, usage:
     readonly inputTokens: number;
     readonly outputTokens: number;
     readonly cachedInputTokens?: number;
+    /** Tokens written into the cache — a subset of `inputTokens`, priced separately. See below. */
+    readonly cacheWriteTokens?: number;
     /** Images sent with the turn — counted from the parts, not from the provider. See `NeutralUsage`. */
     readonly imageCount?: number;
     readonly audioSeconds?: number;