@retinue/agentkit 0.1.0 → 0.3.0

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/budget.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A token ceiling on a catalogue, and the rule that truncation is never quiet — REQ-045 (#204), task #210.
+ *
+ * The tool catalogue and the skill catalogue have the same problem: a compact entry per item, resident on every
+ * turn, linear in how many exist. #221 measured ~35 tokens per tool entry, so 200 tools is ~7,000 tokens before
+ * a word of the conversation. Two-tier loading bounded the *schemas* and left the entries.
+ *
+ * ## Truncation must be loud, and this is the whole guarantee
+ *
+ * A silently shortened catalogue is **indistinguishable from correct behaviour**. The model is not told an item
+ * was withheld; it simply never uses it, and the transcript reads as a run where the model chose not to. Nobody
+ * reviewing that run has anything to notice. So dropping is never quiet: the outcome names every dropped item,
+ * the engine turns that into a run event, and #210's AC-7 is a test that removing the event fails the build.
+ *
+ * In `core/` because both callers need it and neither owns it — and because a second copy for skills would drift
+ * from the first, which is the shape this repository keeps finding defects in.
+ */
+export type TokenBudget = {
+    /** The ceiling. A catalogue at or under it is untouched and no event is emitted. */
+    readonly maxTokens: number;
+};
+export type BudgetOutcome<T> = {
+    readonly resident: readonly T[];
+    /** Names, in the order they were dropped. Named rather than counted: a count is not actionable. */
+    readonly dropped: readonly string[];
+    readonly residentTokens: number;
+    readonly budgetTokens: number;
+    /**
+     * True when the budget could not be met even after dropping everything droppable.
+     *
+     * Distinct from "it bound", because the two need different responses: a bound budget is the mechanism working,
+     * while an unmeetable one is a misconfiguration — the protected set alone does not fit, and a deployment that
+     * believes it capped its context has not.
+     */
+    readonly overBudget: boolean;
+};
+/**
+ * Keep what fits, in the order given, and name what did not.
+ *
+ * **Order is the caller's priority**, not a ranking invented here. For tools that is the order the host's
+ * providers were registered in, which is a deployment's own statement about what matters; inventing a relevance
+ * order would mean guessing at the model's next need, and `find_tools` is the honest answer to that.
+ *
+ * `protect` names what may never be dropped. Meta-tools are the reason it exists: dropping `find_tools` or
+ * `learn_tools` to save 35 tokens would remove the model's only route back to everything else, turning a budget
+ * into a permanent amputation.
+ */
+export declare const applyTokenBudget: <T>(input: {
+    readonly items: readonly T[];
+    readonly budget: TokenBudget;
+    readonly tokensOf: (item: T) => number;
+    readonly nameOf: (item: T) => string;
+    readonly protect?: (item: T) => boolean;
+}) => BudgetOutcome<T>;
+//# sourceMappingURL=budget.d.ts.map

package/dist/core/budget.js

@@ -0,0 +1,56 @@
+/**
+ * A token ceiling on a catalogue, and the rule that truncation is never quiet — REQ-045 (#204), task #210.
+ *
+ * The tool catalogue and the skill catalogue have the same problem: a compact entry per item, resident on every
+ * turn, linear in how many exist. #221 measured ~35 tokens per tool entry, so 200 tools is ~7,000 tokens before
+ * a word of the conversation. Two-tier loading bounded the *schemas* and left the entries.
+ *
+ * ## Truncation must be loud, and this is the whole guarantee
+ *
+ * A silently shortened catalogue is **indistinguishable from correct behaviour**. The model is not told an item
+ * was withheld; it simply never uses it, and the transcript reads as a run where the model chose not to. Nobody
+ * reviewing that run has anything to notice. So dropping is never quiet: the outcome names every dropped item,
+ * the engine turns that into a run event, and #210's AC-7 is a test that removing the event fails the build.
+ *
+ * In `core/` because both callers need it and neither owns it — and because a second copy for skills would drift
+ * from the first, which is the shape this repository keeps finding defects in.
+ */
+/**
+ * Keep what fits, in the order given, and name what did not.
+ *
+ * **Order is the caller's priority**, not a ranking invented here. For tools that is the order the host's
+ * providers were registered in, which is a deployment's own statement about what matters; inventing a relevance
+ * order would mean guessing at the model's next need, and `find_tools` is the honest answer to that.
+ *
+ * `protect` names what may never be dropped. Meta-tools are the reason it exists: dropping `find_tools` or
+ * `learn_tools` to save 35 tokens would remove the model's only route back to everything else, turning a budget
+ * into a permanent amputation.
+ */
+export const applyTokenBudget = (input) => {
+    const protectedItems = [];
+    const droppable = [];
+    for (const item of input.items)
+        (input.protect?.(item) === true ? protectedItems : droppable).push(item);
+    // Protected first, and counted even when they overrun: a report that omitted them would understate the
+    // resident cost and hide precisely the misconfiguration `overBudget` exists to name.
+    let spent = protectedItems.reduce((total, item) => total + input.tokensOf(item), 0);
+    const resident = [...protectedItems];
+    const dropped = [];
+    for (const item of droppable) {
+        const cost = input.tokensOf(item);
+        if (spent + cost <= input.budget.maxTokens) {
+            resident.push(item);
+            spent += cost;
+        }
+        else
+            dropped.push(input.nameOf(item));
+    }
+    return {
+        resident,
+        dropped,
+        residentTokens: spent,
+        budgetTokens: input.budget.maxTokens,
+        overBudget: spent > input.budget.maxTokens,
+    };
+};
+//# sourceMappingURL=budget.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. */
@@ -34,6 +50,14 @@ export type ToolCallPart = PartBase<"tool-call"> & {
 export type ToolResultPart = PartBase<"tool-result"> & {
     readonly toolCallId: ToolCallId;
     readonly toolName: string;
+    /**
+     * What actually ran, when it differs from `toolName` — task #210.
+     *
+     * `execute_tool` names its target, so the call the model made and the action performed are two different
+     * things. Both are recorded: the first is what the model's own history says it did, and the second is what a
+     * reader needs.
+     */
+    readonly ranToolName?: string;
     /** Populated for inline results. Large results are spilled and referenced instead. */
     readonly output?: unknown;
     /** Authorized reference to an offloaded result, read back via `read_tool_output`. */
@@ -180,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"];
+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;
@@ -41,10 +41,43 @@ export type PartEvent = EventBase<"part.added" | "part.updated"> & {
 export type ToolEvent = EventBase<"tool.started" | "tool.completed" | "tool.failed"> & {
     readonly toolCallId: ToolCallId;
     readonly toolName: string;
+    /**
+     * The tool that actually ran, when the model called `execute_tool` — task #210.
+     *
+     * Absent on `tool.started`, because at that point nothing has resolved the target yet. Present on completion
+     * and failure, where it is the difference between an audit trail that names an action and one that names a
+     * mechanism.
+     */
+    readonly ranToolName?: string;
 };
 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;
@@ -52,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.
@@ -70,7 +105,65 @@ export type ContextCompactedEvent = EventBase<"context.compacted"> & {
     readonly droppedParts: number;
     readonly tokensReclaimed: number;
 };
-export type RunEvent = RunLifecycleEvent | RunFailedEvent | RunRetryPendingEvent | PartEvent | ToolEvent | InteractionEvent | UsageUpdatedEvent | ContextCompactedEvent;
+/**
+ * What a guardrail concluded — REQ-046 (#205).
+ *
+ * Emitted for every verdict, including a pass, because "no guardrail ran" and "a guardrail ran and allowed it"
+ * are different facts and an incident review needs to tell them apart.
+ *
+ * **Carries no inspected value, ever.** `what` names fields or entity types; the content that was redacted is
+ * precisely what must not travel into an event log, a trace, or a support ticket — otherwise the audit trail
+ * becomes the leak it exists to record.
+ */
+export type GuardrailVerdictEvent = EventBase<"guardrail.verdict"> & {
+    readonly guardrail: string;
+    readonly subject: "input" | "message" | "tool-call" | "tool-result";
+    readonly outcome: "pass" | "redacted" | "refused";
+    /** For a redaction: the fields or entity types touched. Never their contents. */
+    readonly what?: readonly string[];
+    /** For a refusal. */
+    readonly code?: string;
+    /** True when the guardrail threw and was therefore treated as a refusal. */
+    readonly threw?: boolean;
+};
+/**
+ * A catalogue did not fit its budget, and what was left out — REQ-045 (#204), task #210, AC-3 and AC-5.
+ *
+ * This event *is* the guarantee. A truncated tool list is invisible from inside a run: the model is not told a
+ * tool was withheld, so it never calls it, and the transcript reads exactly like a run where the model chose
+ * not to. Every other failure at least looks like a failure; this one looks like a decision. So the names go in
+ * the log, in full, and #210's AC-7 is a test that deleting this event fails the build.
+ *
+ * Names, not a count. "14 tools were dropped" tells a reader that something happened and nothing about whether
+ * it mattered; `github_merge_pull_request` tells them immediately.
+ */
+export type CatalogTruncatedEvent = EventBase<"catalog.truncated"> & {
+    /**
+     * Which catalogue. One event rather than two, because the fact is the same fact and a reader asking "what was
+     * withheld from this turn" should not have to know there are two mechanisms.
+     */
+    readonly catalog: "tools" | "skills";
+    readonly budgetTokens: number;
+    readonly residentTokens: number;
+    /** Every dropped tool, by name. */
+    readonly dropped: readonly string[];
+    /**
+     * Whether the model can still get to what was dropped.
+     *
+     * `find_tools` makes a truncated tool catalogue a *deferral*; without it the same event describes a permanent
+     * removal, and a reader cannot tell which from the names alone. There is no `find_skills`, so a truncated
+     * skill catalogue is always `false` today — which is a fact worth having in the log rather than a field to
+     * leave off.
+     */
+    readonly findable: boolean;
+    /**
+     * Set when the protected set alone exceeds the budget — a misconfiguration, not the mechanism working.
+     *
+     * A deployment in this state believes it capped its context and has not.
+     */
+    readonly overBudget?: boolean;
+};
+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>;
@@ -128,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,8 +22,18 @@ 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",
+    "catalog.truncated",
 ];
 export const EMPTY_RUN_STREAM_STATE = {
     parts: [],
@@ -80,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;
     }