@retinue/agentkit 0.2.0 → 0.3.1

package/dist/connections/vault-cipher.d.ts

@@ -0,0 +1,95 @@
+/**
+ * A `SecretCipher` over Supabase Vault — REQ-063 (#259), task #268.
+ *
+ * #261 shipped the seam with an app-side AES-256-GCM implementation and deliberately left this one out: there
+ * was no Vault to run it against, and an untested crypto implementation behind a seam that *looks* tested is
+ * worse than none. There is one now, and everything below has been run against it.
+ *
+ * ## The mapping, and the property it changes — AC-3
+ *
+ * Vault owns the ciphertext and hands back an **id**. The seam expects the caller to hold
+ * `{ keyId, algorithm, nonce, ciphertext }`. So:
+ *
+ * | Field | Holds |
+ * |---|---|
+ * | `algorithm` | `supabase-vault` — a sentinel, not a cipher name. The algorithm is Vault's business. |
+ * | `keyId` | `supabase-vault` — see the rotation note. Vault's own `key_id` column comes back **null**: the root key is held outside the database and Supabase does not expose an identity for it. |
+ * | `nonce` | A random **binding token**, not a nonce. See the tamper note. |
+ * | `ciphertext` | The Vault secret's **uuid**. Not ciphertext. |
+ *
+ * **A Vault-sealed row contains no secret material at all.** That is the property worth stating rather than
+ * discovering, and it cuts both ways:
+ *
+ * - A backup of the application's own tables carries no credentials — strictly better than app-side sealing,
+ *   where the backup carries ciphertext that a leaked key would open.
+ * - The secret lives in `vault.secrets`, so **restoring the application tables without the `vault` schema
+ *   leaves every connection pointing at nothing.** With app-side sealing the ciphertext travels with the row;
+ *   here it does not, and a backup strategy that covers `public` and not `vault` silently loses every
+ *   credential. That is a deployment fact, not a code one, and it belongs in a runbook.
+ *
+ * ## Deletion — AC-3, and a gap this found
+ *
+ * Deleting a connection row does **not** delete the Vault secret: the row held a pointer, and dropping a
+ * pointer leaves what it pointed at. `docs/18`'s deletion promises are therefore *not* satisfied by deleting
+ * the row alone, which is a difference from app-side sealing that nobody would notice until an audit.
+ *
+ * So `SecretCipher` gained an optional `forget`. App-side sealing has nothing to implement — the ciphertext
+ * dies with the row — and this implementation removes the Vault secret. A deployment on Vault that never calls
+ * it accumulates orphaned secrets that outlive the connections they belonged to.
+ *
+ * ## Tampering — AC-2, and where the guarantee genuinely differs
+ *
+ * AES-GCM authenticates: a flipped byte fails rather than decrypting to something else. A pointer cannot be
+ * authenticated by the thing it points at, so an attacker able to *write* the connections table could repoint
+ * one connection at another secret in the same Vault and read a credential they were not entitled to. That is
+ * a real weakening and it is not hypothetical — it is exactly the shape of a tenant-isolation bypass.
+ *
+ * Closed here with a **binding token**: `seal` stores a fresh 32-byte random value in the Vault secret's
+ * `description` and keeps it in the sealed value's `nonce` field; `open` compares them in constant time and
+ * refuses on mismatch. Repointing at another secret now fails, because that secret carries a different token.
+ * No application-side key is involved, so the "database cannot decrypt on its own" property is untouched.
+ *
+ * It is not equivalent to AEAD. An attacker who can write *both* the connections table and `vault.secrets`
+ * defeats it, where GCM would still fail. Stated rather than implied.
+ */
+import type { SecretCipher } from "./cipher.js";
+import type { SqlExecutor } from "../adapters/postgres/sql.js";
+/**
+ * The sentinel in `algorithm`, and the reason it is not a cipher name.
+ *
+ * A reader of a stored row needs to know *which implementation* sealed it, not which primitive. `aes-256-gcm`
+ * tells the app-side cipher how to open the value; `supabase-vault` tells this one that the value is a pointer.
+ * Putting libsodium's actual construction here would be a claim about Vault's internals that could stop being
+ * true without this package noticing.
+ */
+export declare const SUPABASE_VAULT: "supabase-vault";
+export type VaultCipherOptions = {
+    /**
+     * Runs the `vault.*` calls. A **service-role** executor: `vault.decrypted_secrets` is not readable by
+     * `anon` or `authenticated`, which is most of what makes Vault worth using.
+     */
+    readonly sql: SqlExecutor;
+    /**
+     * Prefix for the Vault secret's `name`.
+     *
+     * Named at all because `vault.secrets.name` is unique and a deployment sharing a database with anything else
+     * that writes to Vault would otherwise collide. The name carries no secret and is not used for integrity —
+     * that is the token's job.
+     */
+    readonly namePrefix?: string;
+    /** Injectable so a test can assert the token is fresh per seal rather than trusting that it is. */
+    readonly randomToken?: () => string;
+};
+export declare const createSupabaseVaultCipher: (options: VaultCipherOptions) => SecretCipher;
+/**
+ * Rotation is Vault's, not ours — AC-4, stated as a value so a test can assert it.
+ *
+ * `resealConnections` walks `sealed.keyId`; this cipher's is constant, so that walk finds nothing forever.
+ * Correct, and indistinguishable from a misconfigured rotation job unless somebody wrote it down.
+ */
+export declare const vaultRotationIsExternal: {
+    readonly cipher: "supabase-vault";
+    readonly resealFinds: "nothing, by design";
+    readonly why: string;
+};
+//# sourceMappingURL=vault-cipher.d.ts.map

package/dist/connections/vault-cipher.js

@@ -0,0 +1,206 @@
+/**
+ * A `SecretCipher` over Supabase Vault — REQ-063 (#259), task #268.
+ *
+ * #261 shipped the seam with an app-side AES-256-GCM implementation and deliberately left this one out: there
+ * was no Vault to run it against, and an untested crypto implementation behind a seam that *looks* tested is
+ * worse than none. There is one now, and everything below has been run against it.
+ *
+ * ## The mapping, and the property it changes — AC-3
+ *
+ * Vault owns the ciphertext and hands back an **id**. The seam expects the caller to hold
+ * `{ keyId, algorithm, nonce, ciphertext }`. So:
+ *
+ * | Field | Holds |
+ * |---|---|
+ * | `algorithm` | `supabase-vault` — a sentinel, not a cipher name. The algorithm is Vault's business. |
+ * | `keyId` | `supabase-vault` — see the rotation note. Vault's own `key_id` column comes back **null**: the root key is held outside the database and Supabase does not expose an identity for it. |
+ * | `nonce` | A random **binding token**, not a nonce. See the tamper note. |
+ * | `ciphertext` | The Vault secret's **uuid**. Not ciphertext. |
+ *
+ * **A Vault-sealed row contains no secret material at all.** That is the property worth stating rather than
+ * discovering, and it cuts both ways:
+ *
+ * - A backup of the application's own tables carries no credentials — strictly better than app-side sealing,
+ *   where the backup carries ciphertext that a leaked key would open.
+ * - The secret lives in `vault.secrets`, so **restoring the application tables without the `vault` schema
+ *   leaves every connection pointing at nothing.** With app-side sealing the ciphertext travels with the row;
+ *   here it does not, and a backup strategy that covers `public` and not `vault` silently loses every
+ *   credential. That is a deployment fact, not a code one, and it belongs in a runbook.
+ *
+ * ## Deletion — AC-3, and a gap this found
+ *
+ * Deleting a connection row does **not** delete the Vault secret: the row held a pointer, and dropping a
+ * pointer leaves what it pointed at. `docs/18`'s deletion promises are therefore *not* satisfied by deleting
+ * the row alone, which is a difference from app-side sealing that nobody would notice until an audit.
+ *
+ * So `SecretCipher` gained an optional `forget`. App-side sealing has nothing to implement — the ciphertext
+ * dies with the row — and this implementation removes the Vault secret. A deployment on Vault that never calls
+ * it accumulates orphaned secrets that outlive the connections they belonged to.
+ *
+ * ## Tampering — AC-2, and where the guarantee genuinely differs
+ *
+ * AES-GCM authenticates: a flipped byte fails rather than decrypting to something else. A pointer cannot be
+ * authenticated by the thing it points at, so an attacker able to *write* the connections table could repoint
+ * one connection at another secret in the same Vault and read a credential they were not entitled to. That is
+ * a real weakening and it is not hypothetical — it is exactly the shape of a tenant-isolation bypass.
+ *
+ * Closed here with a **binding token**: `seal` stores a fresh 32-byte random value in the Vault secret's
+ * `description` and keeps it in the sealed value's `nonce` field; `open` compares them in constant time and
+ * refuses on mismatch. Repointing at another secret now fails, because that secret carries a different token.
+ * No application-side key is involved, so the "database cannot decrypt on its own" property is untouched.
+ *
+ * It is not equivalent to AEAD. An attacker who can write *both* the connections table and `vault.secrets`
+ * defeats it, where GCM would still fail. Stated rather than implied.
+ */
+import { timingSafeEqual } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * The sentinel in `algorithm`, and the reason it is not a cipher name.
+ *
+ * A reader of a stored row needs to know *which implementation* sealed it, not which primitive. `aes-256-gcm`
+ * tells the app-side cipher how to open the value; `supabase-vault` tells this one that the value is a pointer.
+ * Putting libsodium's actual construction here would be a claim about Vault's internals that could stop being
+ * true without this package noticing.
+ */
+export const SUPABASE_VAULT = "supabase-vault";
+/** 32 bytes of binding token. Long enough that guessing it is not a strategy. */
+const TOKEN_BYTES = 32;
+const failed = (message, code = "invalid_input") => {
+    throw new AgentPlatformError({ code, message, retryable: false });
+};
+/** Constant-time compare that does not leak *which* byte differed, and tolerates unequal lengths. */
+const tokensMatch = (a, b) => {
+    const left = Buffer.from(a, "utf8");
+    const right = Buffer.from(b, "utf8");
+    // `timingSafeEqual` throws on a length mismatch, which would itself be a length oracle. Compared against a
+    // padded copy so the answer is false rather than an exception.
+    if (left.length !== right.length) {
+        const padded = Buffer.alloc(Math.max(left.length, right.length));
+        const other = Buffer.alloc(padded.length);
+        left.copy(padded);
+        right.copy(other);
+        timingSafeEqual(padded, other);
+        return false;
+    }
+    return timingSafeEqual(left, right);
+};
+export const createSupabaseVaultCipher = (options) => {
+    const prefix = options.namePrefix ?? "retinue";
+    const newToken = options.randomToken ?? (() => randomBytes(TOKEN_BYTES).toString("base64"));
+    return {
+        /**
+         * `keyId` is a constant, and that is Vault's answer to rotation — AC-4.
+         *
+         * `resealConnections` walks `sealed.keyId` looking for rows sealed under a retired key. Under Vault that
+         * loop finds **nothing, forever**, because there is one key identity and it never changes.
+         *
+         * That is correct rather than broken, and the distinction matters: Supabase rotates the Vault root key
+         * outside the database, and re-sealing through this cipher would mean decrypting and re-encrypting with
+         * the *same* key — work that changes nothing. But a rotation job that silently does nothing looks
+         * identical to a rotation job that is wired wrong, so a deployment on Vault should not run one and expect
+         * output. `vaultRotationIsExternal` exists to be asserted in a test rather than remembered.
+         */
+        currentKeyId() {
+            return SUPABASE_VAULT;
+        },
+        async seal(plaintext) {
+            const token = newToken();
+            /**
+             * The name is unique per secret, so two seals of the same plaintext are two Vault rows.
+             *
+             * Vault's `create_secret` raises on a duplicate name, and a cipher that reused one would make the
+             * second seal of a value fail — which would look like an intermittent credential bug.
+             */
+            const name = `${prefix}:${randomBytes(16).toString("hex")}`;
+            const rows = await options.sql.query("select vault.create_secret($1, $2, $3) as id", [plaintext, name, token]);
+            const id = rows[0]?.id;
+            if (typeof id !== "string" || id === "") {
+                return failed("Supabase Vault did not return an id for the secret it was asked to store.", "internal");
+            }
+            return {
+                keyId: SUPABASE_VAULT,
+                algorithm: SUPABASE_VAULT,
+                // The binding token, not a nonce — see the header. Kept in this field so the shape of a stored row is
+                // unchanged and no migration is needed to select this implementation.
+                nonce: token,
+                // The pointer. **Not ciphertext**; see the backup note in the header.
+                ciphertext: id,
+            };
+        },
+        async open(sealed) {
+            if (sealed.algorithm !== SUPABASE_VAULT) {
+                // Refused rather than guessed: a row sealed by the app-side cipher must not be handed to this one, and
+                // the mistake is a misconfiguration worth naming rather than a decryption failure to debug.
+                return failed(`This secret was sealed with "${sealed.algorithm}", not ${SUPABASE_VAULT}. A deployment that has ` +
+                    "switched ciphers must re-seal its existing rows; opening one with the wrong implementation " +
+                    "cannot work and is not attempted.");
+            }
+            if (sealed.ciphertext === "")
+                return failed("This Vault-sealed secret carries no id.");
+            const rows = await options.sql.query("select decrypted_secret, description from vault.decrypted_secrets where id = $1::uuid", [sealed.ciphertext]);
+            const row = rows[0];
+            if (row === undefined) {
+                /**
+                 * A pointer with nothing behind it.
+                 *
+                 * The likeliest cause is the one named in the header: application tables restored without the `vault`
+                 * schema. Said explicitly, because "secret not found" against a row that plainly has an id sends an
+                 * operator looking for a code bug.
+                 */
+                return failed(`Supabase Vault has no secret ${sealed.ciphertext}. Either it was deleted, or these rows were ` +
+                    "restored from a backup that did not include the vault schema — a Vault-sealed row holds a " +
+                    "pointer, not the ciphertext.");
+            }
+            /**
+             * The binding check — AC-2.
+             *
+             * Without it, an attacker who can write the connections table repoints a row at another secret in the
+             * same Vault and reads a credential they were not entitled to. A pointer cannot be authenticated by
+             * what it points at, so the token is what makes the pair inseparable.
+             */
+            if (!tokensMatch(sealed.nonce, row.description ?? "")) {
+                return failed("This Vault secret does not belong to this row. The binding token does not match, which means the " +
+                    "stored id was changed — refused rather than returning a credential from somewhere else.");
+            }
+            const plaintext = row.decrypted_secret;
+            if (plaintext === null) {
+                return failed("Supabase Vault returned no plaintext for this secret.", "internal");
+            }
+            return plaintext;
+        },
+        /**
+         * Removes the Vault secret — the deletion half of AC-3.
+         *
+         * Deleting a connection row drops a pointer and leaves the secret. A deployment on Vault that never calls
+         * this accumulates credentials that outlive the connections they belonged to, which is the opposite of
+         * what `docs/18` promises.
+         */
+        async forget(sealed) {
+            if (sealed.algorithm !== SUPABASE_VAULT || sealed.ciphertext === "")
+                return;
+            /**
+             * Guarded by the binding token, like `open`.
+             *
+             * A `forget` that deleted whatever the id pointed at would be a way to destroy *another* connection's
+             * credential by writing an id into a row — a smaller blast radius than reading it, and the same class of
+             * bug. The delete is scoped to a row whose description matches.
+             */
+            await options.sql.query("delete from vault.secrets where id = $1::uuid and description = $2", [sealed.ciphertext, sealed.nonce]);
+        },
+    };
+};
+/**
+ * Rotation is Vault's, not ours — AC-4, stated as a value so a test can assert it.
+ *
+ * `resealConnections` walks `sealed.keyId`; this cipher's is constant, so that walk finds nothing forever.
+ * Correct, and indistinguishable from a misconfigured rotation job unless somebody wrote it down.
+ */
+export const vaultRotationIsExternal = {
+    cipher: SUPABASE_VAULT,
+    resealFinds: "nothing, by design",
+    why: "Supabase rotates the Vault root key outside the database. Re-sealing through this cipher would decrypt " +
+        "and re-encrypt under the same key identity, which changes nothing. A deployment on Vault should not run " +
+        "a re-seal job and expect it to report work.",
+};
+//# sourceMappingURL=vault-cipher.js.map

package/dist/core/content-parts.d.ts

@@ -7,7 +7,7 @@
  */
 import type { ArtifactId, ArtifactVersionId, BlobRef, ConversationId, FileId, InteractionId, MessageId, MessagePartId, RunId, ToolCallId } from "./ids.js";
 import type { PlatformError } from "./errors.js";
-export declare const MESSAGE_PART_TYPES: readonly ["text", "reasoning", "tool-call", "tool-result", "question", "approval", "file", "image", "citation", "source", "artifact", "status", "error"];
+export declare const MESSAGE_PART_TYPES: readonly ["text", "reasoning", "tool-call", "tool-result", "question", "approval", "file", "image", "citation", "source", "artifact", "status", "error", "structured"];
 export type MessagePartType = (typeof MESSAGE_PART_TYPES)[number];
 type PartBase<T extends MessagePartType> = {
     readonly id: MessagePartId;
@@ -21,6 +21,22 @@ type PartBase<T extends MessagePartType> = {
 export type TextPart = PartBase<"text"> & {
     readonly text: string;
 };
+/**
+ * The validated answer of a structured agent — task #243.
+ *
+ * Its own part rather than a `TextPart` holding JSON, for the reason the whole task exists: a consumer that
+ * asked for structured output wants the object, and handing back text would leave every reader re-parsing it
+ * and deciding for itself whether the parse succeeded. The part carries the value **after** validation, so its
+ * presence is the guarantee — an agent whose model produced nothing conforming fails the run instead of
+ * emitting this with something unchecked in it.
+ *
+ * There is no partial form. A half-built object does not satisfy the schema the caller asked for, so streaming
+ * one would mean emitting values that violate the contract; the part is added once, complete, at the end of the
+ * turn. Tool calls still stream normally around it.
+ */
+export type StructuredPart = PartBase<"structured"> & {
+    readonly value: unknown;
+};
 export type ReasoningPart = PartBase<"reasoning"> & {
     readonly text: string;
     /** Reasoning is pruned before recent semantic turns when the budget is tight. */
@@ -188,7 +204,7 @@ export type StatusPart = PartBase<"status"> & {
 export type ErrorPart = PartBase<"error"> & {
     readonly error: PlatformError;
 };
-export type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart | QuestionPart | ApprovalPart | FilePart | ImagePart | CitationPart | SourcePart | ArtifactPart | StatusPart | ErrorPart;
+export type MessagePart = TextPart | ReasoningPart | ToolCallPart | ToolResultPart | QuestionPart | ApprovalPart | FilePart | ImagePart | CitationPart | SourcePart | ArtifactPart | StatusPart | StructuredPart | ErrorPart;
 export type MessageRole = "system" | "user" | "assistant" | "tool";
 export type Message = {
     readonly id: MessageId;

package/dist/core/content-parts.js

@@ -19,5 +19,6 @@ export const MESSAGE_PART_TYPES = [
     "artifact",
     "status",
     "error",
+    "structured",
 ];
 //# sourceMappingURL=content-parts.js.map

package/dist/core/context.d.ts

@@ -31,6 +31,31 @@ export type ExecutionContext = {
      * it is shadow and has nowhere to record the suppression is refused, not performed.
      */
     readonly shadow?: boolean;
+    /**
+     * The running agent's tool policy — task #244.
+     *
+     * On the context for the same reason `shadow` is, and the argument is the one at the top of this file: context
+     * identity is constructed by the host, and **nothing originating in a tool argument, a skill body or an MCP
+     * tool description may reach these fields.** A model must never be able to widen `excluded`, and the only way
+     * to guarantee that is for the policy to travel on the one object a model cannot write to.
+     *
+     * The engine sets it from `AgentManifest.toolPolicy` before it builds tools, so every path that reaches the
+     * registry — a direct call, `execute_tool`, a delegating tool — sees the same policy. That breadth is the
+     * point: `toolPolicy.excluded` reads as a security control, and a control enforced only where the catalogue is
+     * built is bypassed by the first caller who already knows the tool's name.
+     *
+     * Structural (three name lists) rather than importing `ToolPolicyView`, because `core` must not depend on
+     * `tools`. The same choice `ApprovalCheck` makes to avoid a tools→hitl dependency.
+     *
+     * Absent means no agent-level policy — every authorized tool is available. That is the right default here, and
+     * it is the *safe* direction unlike `shadow`: a missing policy grants nothing that authorization has not
+     * already granted, whereas a missing `shadow` flag publishes.
+     */
+    readonly agentToolPolicy?: {
+        readonly preloaded: readonly string[];
+        readonly categories: readonly string[];
+        readonly excluded: readonly string[];
+    };
 };
 /**
  * The tenant scope every store method receives explicitly. Governing principle 1:

package/dist/core/errors.d.ts

@@ -5,7 +5,7 @@
  * is shown to a model and a user: no credentials, no connection strings, no internal
  * hostnames, no raw provider stack traces.
  */
-export declare const ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "invalid_input", "conflict", "rate_limited", "provider_unavailable", "provider_error", "timeout", "cancelled", "budget_exceeded", "context_overflow", "approval_required", "approval_denied", "approval_expired", "question_pending", "idempotency_conflict", "capability_unavailable", "internal"];
+export declare const ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "invalid_input", "conflict", "rate_limited", "provider_unavailable", "provider_error", "timeout", "cancelled", "budget_exceeded", "context_overflow", "approval_required", "approval_denied", "approval_expired", "question_pending", "admission_rate_limited", "idempotency_conflict", "capability_unavailable", "internal"];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 export type PlatformError = {
     readonly code: ErrorCode;

package/dist/core/errors.js

@@ -33,6 +33,21 @@ export const ERROR_CODES = [
      * Carries `details.interactionId`.
      */
     "question_pending",
+    /**
+     * A tenant asked for more runs than their rate allows — task #248.
+     *
+     * **Its own code, not `rate_limited`.** That one means *a provider* throttled us, and `decideRetry` treats it
+     * as retryable inside the run — which is right there and wrong here: this refusal happens at admission, before
+     * a run exists, so there is nothing to retry and no run event to carry it. Conflating the two would let a
+     * platform-level capacity refusal be handled by the engine's provider-backoff loop, which is the wrong
+     * mechanism for the wrong problem.
+     *
+     * Distinct from `budget_exceeded` too: that is about *spend over a period* and this is about *capacity right
+     * now*. A tenant can be well inside budget and still asking too fast.
+     *
+     * Carries `details.retryAfter` and `details.retryAfterMs`, so a client can wait rather than guess.
+     */
+    "admission_rate_limited",
     "idempotency_conflict",
     "capability_unavailable",
     "internal",

package/dist/core/events.d.ts

@@ -8,7 +8,7 @@
 import type { MessagePart } from "./content-parts.js";
 import type { PlatformError } from "./errors.js";
 import type { InteractionId, MessageId, RunId, TenantId, ToolCallId } from "./ids.js";
-export declare const RUN_EVENT_TYPES: readonly ["run.queued", "run.started", "run.checkpointed", "run.completed", "run.failed", "run.cancelled", "run.retry-pending", "part.added", "part.updated", "tool.started", "tool.completed", "tool.failed", "question.requested", "question.answered", "approval.requested", "approval.decided", "usage.updated", "context.compacted", "guardrail.verdict", "catalog.truncated"];
+export declare const RUN_EVENT_TYPES: readonly ["run.queued", "run.started", "run.checkpointed", "run.completed", "run.failed", "run.cancelled", "run.retry-pending", "part.added", "part.updated", "tool.started", "tool.completed", "tool.failed", "question.requested", "question.answered", "approval.requested", "approval.decided", "connection.requested", "connection.completed", "usage.updated", "context.compacted", "guardrail.verdict", "catalog.truncated"];
 export type RunEventType = (typeof RUN_EVENT_TYPES)[number];
 type EventBase<T extends RunEventType> = {
     readonly type: T;
@@ -53,6 +53,31 @@ export type ToolEvent = EventBase<"tool.started" | "tool.completed" | "tool.fail
 export type InteractionEvent = EventBase<"question.requested" | "question.answered" | "approval.requested" | "approval.decided"> & {
     readonly interactionId: InteractionId;
 };
+/**
+ * The run needs a connection, and here is where to get one — task #264.
+ *
+ * Its own event rather than an `InteractionEvent`, because it carries different things: an interaction id names
+ * a stored question or approval, and this names a *provider*, the scopes being asked for, and a URL. Folding it
+ * in would mean an `interactionId` for something that is not one.
+ *
+ * **It carries no secret.** Not the client secret, not a token, not the PKCE verifier. This is rendered in a UI
+ * and clicked by a person, so it goes wherever a screenshot goes.
+ */
+export type ConnectionRequestedEvent = EventBase<"connection.requested"> & {
+    readonly provider: string;
+    /** Where to send the person. Single-use and TTL-bounded — see the OAuth flow's `state`. */
+    readonly loginUrl: string;
+    /** What the consent will ask for, so a UI can say what is being granted. */
+    readonly scopes: readonly string[];
+    /** Which tool stalled, so a transcript reads coherently. */
+    readonly toolName?: string;
+    /** When the login URL stops working, so a client can offer a fresh one rather than a dead link. */
+    readonly expiresAt: string;
+};
+export type ConnectionCompletedEvent = EventBase<"connection.completed"> & {
+    readonly provider: string;
+    readonly connectionId: string;
+};
 export type UsageUpdatedEvent = EventBase<"usage.updated"> & {
     readonly inputTokens: number;
     readonly outputTokens: number;
@@ -60,6 +85,8 @@ export type UsageUpdatedEvent = EventBase<"usage.updated"> & {
     /** When present, the worker records a durable `UsageEvent` for this realized step. */
     readonly modelId?: string;
     readonly cachedInputTokens?: number;
+    /** Tokens written into a prompt cache — task #247. Absent means the provider reported no breakdown. */
+    readonly cacheWriteTokens?: number;
     readonly reasoningTokens?: number;
     /**
      * Non-text input this step carried — #185 AC-4.
@@ -136,7 +163,7 @@ export type CatalogTruncatedEvent = EventBase<"catalog.truncated"> & {
      */
     readonly overBudget?: boolean;
 };
-export type RunEvent = RunLifecycleEvent | RunFailedEvent | RunRetryPendingEvent | PartEvent | ToolEvent | InteractionEvent | UsageUpdatedEvent | ContextCompactedEvent | GuardrailVerdictEvent | CatalogTruncatedEvent;
+export type RunEvent = RunLifecycleEvent | RunFailedEvent | RunRetryPendingEvent | PartEvent | ToolEvent | InteractionEvent | ConnectionRequestedEvent | ConnectionCompletedEvent | UsageUpdatedEvent | ContextCompactedEvent | GuardrailVerdictEvent | CatalogTruncatedEvent;
 /** Fan-out port. Adapters: Supabase Realtime, Redis pub/sub, in-memory for tests. */
 export interface RealtimePublisher {
     publish(channel: string, event: RunEvent): Promise<void>;
@@ -194,6 +221,21 @@ export type RunStreamState = {
         readonly nextAttemptAt: string;
     };
     readonly error?: PlatformError;
+    /**
+     * Present while the run is waiting for somebody to connect a provider — task #264.
+     *
+     * On the stream state rather than as a message part, because it is not a thing the model said: it is the
+     * platform telling a client *this run is stopped and here is the way to unstick it*. Cleared by
+     * `connection.completed`, so a client that reconnects mid-consent still sees the button and one that
+     * reconnects after it does not.
+     */
+    readonly connectionRequest?: {
+        readonly provider: string;
+        readonly loginUrl: string;
+        readonly scopes: readonly string[];
+        readonly toolName?: string;
+        readonly expiresAt: string;
+    };
     readonly terminal: boolean;
 };
 export declare const EMPTY_RUN_STREAM_STATE: RunStreamState;

package/dist/core/events.js

@@ -22,6 +22,14 @@ export const RUN_EVENT_TYPES = [
     "question.answered",
     "approval.requested",
     "approval.decided",
+    /**
+     * The run needs a connection, and here is where to go and get one — task #264.
+     *
+     * Carries the provider, the scopes being asked for and a login URL. It carries **no secret**: not the client
+     * secret, not a token, not the PKCE verifier. This is an event a client renders and a person clicks.
+     */
+    "connection.requested",
+    "connection.completed",
     "usage.updated",
     "context.compacted",
     "guardrail.verdict",
@@ -82,11 +90,32 @@ export const reduceRunEvent = (state, event) => {
                 ...base,
                 retry: { attempt: event.attempt, maxAttempts: event.maxAttempts, nextAttemptAt: event.nextAttemptAt },
             };
+        /**
+         * The connection request, held until consent completes — task #264.
+         *
+         * Set and cleared here rather than derived by each client, so a reconnecting client sees the button exactly
+         * when the run is actually waiting: the durable log replays both events in order, and the fold gives the
+         * same answer as if it had been watching live.
+         */
+        case "connection.requested":
+            return {
+                ...base,
+                connectionRequest: {
+                    provider: event.provider,
+                    loginUrl: event.loginUrl,
+                    scopes: event.scopes,
+                    ...(event.toolName === undefined ? {} : { toolName: event.toolName }),
+                    expiresAt: event.expiresAt,
+                },
+            };
+        case "connection.completed":
+            return { ...base, connectionRequest: undefined };
         case "run.failed":
-            return { ...base, error: event.error, terminal: true };
+            // Cleared: a failed run's login URL is a button that leads nowhere.
+            return { ...base, connectionRequest: undefined, error: event.error, terminal: true };
         case "run.completed":
         case "run.cancelled":
-            return { ...base, terminal: true };
+            return { ...base, connectionRequest: undefined, terminal: true };
         default:
             return base;
     }

package/dist/core/validation.js

@@ -133,6 +133,25 @@ const messagePartSchema = z.discriminatedUnion("type", [
     z.object({ ...base, type: z.literal("artifact"), artifactId: idString, versionId: idString, title: z.string() }),
     z.object({ ...base, type: z.literal("status"), status: z.string(), detail: z.string().optional() }),
     z.object({ ...base, type: z.literal("error"), error: platformErrorSchema }),
+    /**
+     * A structured agent's validated answer — #243.
+     *
+     * `value` is `unknown` on purpose. The schema that constrains it belongs to the *agent*, is chosen by whoever
+     * wrote the manifest, and has already been enforced before the part was emitted — so re-describing it here is
+     * impossible (there is no one shape) and re-validating it would be validating against the wrong schema.
+     *
+     * What this layer does check is that `value` is **present**. `z.unknown()` accepts `undefined`, which would let
+     * a part claiming to be a structured answer round-trip carrying nothing — the empty version of the exact defect
+     * #243 fixed. `z.unknown().refine(v => v !== undefined)` is the narrowest thing that closes it, and `null`
+     * stays legal because `null` is a valid JSON value a schema may well permit.
+     */
+    z.object({
+        ...base,
+        type: z.literal("structured"),
+        value: z.unknown().refine((v) => v !== undefined, {
+            message: "a structured part must carry a value; an absent one is an answer that was never validated",
+        }),
+    }),
 ]);
 const executionContextSchema = z.object({
     tenantId: idString,

package/dist/entries/connections.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@retinue/agentkit/connections` — a tenant's links to third-party providers, and the cipher that protects
+ * them (#261).
+ *
+ * Its own subpath rather than part of `./tools`, because the two have different readers: a toolkit author needs
+ * `credentialRef` and `Credential`, and a *deployment* needs the store, the cipher and the resolver that
+ * connects them. Nothing here is needed to write a tool.
+ */
+export * from "../connections/index.js";
+//# sourceMappingURL=connections.d.ts.map

package/dist/entries/connections.js

@@ -0,0 +1,10 @@
+/**
+ * `@retinue/agentkit/connections` — a tenant's links to third-party providers, and the cipher that protects
+ * them (#261).
+ *
+ * Its own subpath rather than part of `./tools`, because the two have different readers: a toolkit author needs
+ * `credentialRef` and `Credential`, and a *deployment* needs the store, the cipher and the resolver that
+ * connects them. Nothing here is needed to write a tool.
+ */
+export * from "../connections/index.js";
+//# sourceMappingURL=connections.js.map

package/dist/entries/knowledge.d.ts

@@ -24,4 +24,12 @@ export * from "../export/markdown.js";
  */
 export { DEFAULT_EMBEDDING_BATCH, DEFAULT_EMBEDDING_MODEL, createOpenAiEmbeddings } from "../adapters/embeddings/openai.js";
 export type { OpenAiEmbeddingsConfig } from "../adapters/embeddings/openai.js";
+/**
+ * The extraction prompt, exported so a harness can use the same one the runtime does — task #275.
+ *
+ * `extractGraph` itself is not exported here: it takes a `LanguageModel` from the AI SDK, and a consumer that
+ * wanted it would be pulling a provider package through the knowledge entrypoint. The prompt is the part worth
+ * sharing — a measurement run against a *different* prompt is measuring a different system.
+ */
+export { DEFAULT_EXTRACTION_PROMPT } from "../models/extraction.js";
 //# sourceMappingURL=knowledge.d.ts.map

package/dist/entries/knowledge.js

@@ -24,4 +24,12 @@ export * from "../export/markdown.js";
  * own subpaths because they each pull a client library in.
  */
 export { DEFAULT_EMBEDDING_BATCH, DEFAULT_EMBEDDING_MODEL, createOpenAiEmbeddings } from "../adapters/embeddings/openai.js";
+/**
+ * The extraction prompt, exported so a harness can use the same one the runtime does — task #275.
+ *
+ * `extractGraph` itself is not exported here: it takes a `LanguageModel` from the AI SDK, and a consumer that
+ * wanted it would be pulling a provider package through the knowledge entrypoint. The prompt is the part worth
+ * sharing — a measurement run against a *different* prompt is measuring a different system.
+ */
+export { DEFAULT_EXTRACTION_PROMPT } from "../models/extraction.js";
 //# sourceMappingURL=knowledge.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * `@retinue/agentkit/mcp-server` — expose this deployment's tools to MCP clients (#250).
+ *
+ * Its own subpath, and separate from `./mcp`, because the two are opposite directions: `./mcp` consumes a
+ * tenant's MCP servers, and this **is** one. Sharing an entry would put the SDK's server half in the way of
+ * every consumer who only wanted the client half.
+ */
+export * from "../mcp-server/index.js";
+//# sourceMappingURL=mcp-server.d.ts.map