@adonis-agora/agent 0.30.2 → 0.33.0

package/dist/src/spi/agent-store.d.ts

@@ -59,6 +59,14 @@ export interface RecordRunStartInput {
     actor: Actor;
     /** The agent that handled the run; `null`/omitted for the default agent. */
     agentName?: string;
+    /**
+     * The run that started this one, for a delegation's child run. The parent->child edge exists in
+     * the durable runtime's own journal, but only there: a governance surface reading run rows alone
+     * cannot roll a delegation's cost up to the turn that asked for it.
+     *
+     * Optional, and a store that persists nothing for it still works — it loses the tree, not the run.
+     */
+    parentRunId?: string;
     /** True when the run executes as a replay-safe durable workflow, false for the inline runner. */
     durable?: boolean;
 }
@@ -79,6 +87,40 @@ export interface RecordRunEndInput {
     costUsd?: number;
     error?: string;
 }
+/** Which thread, and how many of its newest messages, {@link ThreadTurnReader.loadThreadForTurn} reads. */
+export interface ThreadTurnQuery {
+    threadId: string;
+    /** Omitted reads every message; `0` reads none. */
+    messageLimit?: number;
+}
+/** What a turn reads off a thread — a bounded window, not the transcript. */
+export interface ThreadTurnPage {
+    title: string;
+    /** Whether the THREAD has ever been answered, not whether {@link messages} holds an answer. */
+    hasAssistantMessage: boolean;
+    /** Oldest first, carrying only the fields a model turn reads. */
+    messages: StoredMessage[];
+}
+/**
+ * A store that can hand a turn the WINDOW it is about to send, instead of the thread's transcript.
+ *
+ * {@link AgentStore.getThread} materializes every message row, every attachment and every tool
+ * output a thread ever recorded, and `load:thread` then journals what it loaded — so a long thread
+ * pays for its whole history on every turn and again on every replay, to send a prompt bounded to
+ * its last few messages. This read is bounded by the database (`order by created_at desc limit ?`),
+ * projected to the columns a model turn actually reads.
+ *
+ * `hasAssistantMessage` is answered over the WHOLE thread, never the page: it answers "has this
+ * conversation been answered before?" — what a `thread-start` intake asks — and a thread whose
+ * window happens to hold only the user's last questions has still been answered. `null` for a thread
+ * that is unknown or soft-deleted, matching `getThread`.
+ *
+ * Probed STRUCTURALLY rather than declared on {@link AgentStore}: it is an optimization a store
+ * either offers or does not, and one that offers none still answers correctly through the full read.
+ */
+export interface ThreadTurnReader {
+    loadThreadForTurn(query: ThreadTurnQuery): Promise<ThreadTurnPage | null>;
+}
 /** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
 export interface AgentStore {
     createThread(input: CreateThreadInput): Promise<ThreadSummary>;
@@ -95,6 +137,17 @@ export interface AgentStore {
     setTitle(threadId: string, title: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
     appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
+    /**
+     * Attach a turn's settled tool RESULTS to a message already appended, replacing whatever it held.
+     * A message's tool calls are known when it is written and their outputs are not, but a thread
+     * reader pairs the two off THAT MESSAGE — so an output that only ever reaches the tool-call table
+     * leaves every call on a reopened thread looking like a tool still running.
+     *
+     * Required rather than optional: a store that silently declines this renders a finished turn as a
+     * permanently in-flight one, with nothing logged and nothing to notice. A missing method should
+     * fail to compile instead.
+     */
+    setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;

package/dist/src/spi/agent-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-store.d.ts","sourceRoot":"","sources":["../../../src/spi/agent-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,EACV,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,wGAAwG;IACxG,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9E,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,2GAA2G;IAC3G,KAAK,EAAE,KAAK,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/D,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC1D;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACxE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE3E,2FAA2F;IAC3F,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,yGAAyG;IACzG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD"}
+{"version":3,"file":"agent-store.d.ts","sourceRoot":"","sources":["../../../src/spi/agent-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,EACV,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,wGAAwG;IACxG,WAAW,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9E,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,2GAA2G;IAC3G,KAAK,EAAE,KAAK,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iGAAiG;IACjG,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IAC3C,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2GAA2G;AAC3G,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC3E;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/D,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC1D;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACxE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjE;;;;;;;;;OASG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE3E,2FAA2F;IAC3F,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACtD,yGAAyG;IACzG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD"}

package/dist/src/spi/governance-queries.d.ts

@@ -11,6 +11,7 @@
  * — that comes off the `aviary:agent:*` diagnostics channel. This interface is the durable, restart-
  * surviving history.
  */
+import type { CursorPage, CursorParams } from '../pagination.js';
 /** Inclusive UTC day range, each `YYYY-MM-DD`. */
 export interface GovernanceRange {
     fromDay: string;
@@ -61,8 +62,13 @@ export interface ThreadActivityRow {
 }
 /** A run's lifecycle status as the read-model surfaces it. */
 export type RunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
-/** Filters + cursor for {@link AgentGovernanceQueries.listRuns}. All optional; absent = no constraint. */
-export interface ListRunsFilter {
+/**
+ * Filters + cursor for {@link AgentGovernanceQueries.listRuns}. All optional; absent = no constraint.
+ *
+ * The pagination half is {@link CursorParams} — the ecosystem-wide `{ after, first }` shape mirroring
+ * `@adonis-agora/filter`'s `CursorParams`. Forward-only: no `before`/`last`.
+ */
+export interface ListRunsFilter extends CursorParams {
     /** Exact `actor_ref`. */
     actor?: string;
     /** Exact `agent_name`. */
@@ -72,10 +78,13 @@ export interface ListRunsFilter {
     from?: string;
     /** Inclusive UTC-day upper bound on `started_at`, `YYYY-MM-DD`. */
     to?: string;
-    /** Opaque cursor from a prior page's {@link ListRunsResult.nextCursor}; omit for the first page. */
-    cursor?: string;
-    /** Page size; defaults to 50, clamped to 200 by the adapter. */
-    limit?: number;
+    /**
+     * Opaque cursor from a prior page's {@link ListRunsResult.nextCursor}; omit for the first page.
+     * (Inherited from {@link CursorParams}, restated for the doc site.)
+     */
+    after?: string;
+    /** Page size; defaults to 50, clamped to 200 by the adapter. (Inherited from {@link CursorParams}.) */
+    first?: number;
 }
 /** A run row for the governance list + detail. Newest-first in {@link ListRunsResult}. */
 export interface RunSummaryRow {
@@ -86,6 +95,11 @@ export interface RunSummaryRow {
     actorLabel?: string;
     tenantRef: string | null;
     agentName: string | null;
+    /**
+     * The run that delegated this one, or `null` for a turn a person started. Without it a delegation's
+     * spend reads as an orphan turn on every surface built over these rows.
+     */
+    parentRunId: string | null;
     status: string;
     /** ISO timestamp. */
     startedAt: string;
@@ -100,12 +114,14 @@ export interface RunSummaryRow {
     error: string | null;
     durable: boolean;
 }
-/** One page of {@link AgentGovernanceQueries.listRuns}, newest-first, with an opaque forward cursor. */
-export interface ListRunsResult {
-    runs: RunSummaryRow[];
-    /** Pass back as {@link ListRunsFilter.cursor} for the next page; `null` when the last page was returned. */
-    nextCursor: string | null;
-}
+/**
+ * One page of {@link AgentGovernanceQueries.listRuns}, newest-first, with an opaque forward cursor.
+ *
+ * This is exactly {@link CursorPage} of {@link RunSummaryRow}: the rows are under `items` (not
+ * `runs`), `nextCursor` goes back as {@link ListRunsFilter.after}, and — the read-model being
+ * forward-only — `prevCursor` is always `null` and `hasPrev` always `false`.
+ */
+export type ListRunsResult = CursorPage<RunSummaryRow>;
 /** A message belonging to a run, for {@link RunDetail}. */
 export interface RunMessageRow {
     id: string;
@@ -266,7 +282,11 @@ export interface AgentGovernanceQueries {
     usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
-    /** Filterable, cursor-paginated run list, newest-first. */
+    /**
+     * Filterable, cursor-paginated run list, newest-first. Pagination is the ecosystem's forward-only
+     * cursor interface: `{ after, first }` in, {@link CursorPage} out (`items` / `nextCursor`, with
+     * `prevCursor: null` and `hasPrev: false`).
+     */
     listRuns(filter?: ListRunsFilter): Promise<ListRunsResult>;
     /** The full trace of one run (run + messages + tool calls + approvals + usage), or `null` if unknown. */
     runDetail(runId: string): Promise<RunDetail | null>;

package/dist/src/spi/governance-queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"governance-queries.d.ts","sourceRoot":"","sources":["../../../src/spi/governance-queries.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"governance-queries.d.ts","sourceRoot":"","sources":["../../../src/spi/governance-queries.ts"],"names":[],"mappings":"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"}

package/dist/src/spi/history-window.d.ts

@@ -1,24 +1,78 @@
-import type { Actor, ModelMessage } from '../types.js';
+import type { Actor, MessageUsage, ModelMessage } from '../types.js';
 /** What a {@link HistoryWindow} needs to know about the run it's compacting history for. */
 export interface HistoryWindowContext {
     actor: Actor;
     threadId: string;
 }
+/** How a window split the thread: what rides into the turn, and what the ceiling left out. */
+export interface HistorySelection {
+    /** Sent to the model, oldest-first. */
+    keep: ModelMessage[];
+    /** Left out, oldest-first. Folded into a leading summary when the window implements `summarize`. */
+    drop: ModelMessage[];
+}
+/** A stand-in for the messages a window left out, plus what producing it cost. */
+export interface HistorySummary {
+    /** Prose the loop folds into the window as a leading `system` message. */
+    text: string;
+    /**
+     * What the summarizer spent, when it called a model. Recorded as a `summary` usage row, so a
+     * ceiling on context cost cannot itself become spend nothing accounts for — the quota sums the
+     * whole ledger without filtering purpose, so this also counts against the daily cap. Omit for a
+     * summarizer that calls no model (a rollup of tool names, a digest the app already stored).
+     */
+    usage?: MessageUsage;
+    /** Accounting label for the model that produced it; falls back to `AgentLoopDeps.modelId`. */
+    modelId?: string;
+}
 /**
  * Compaction seam for long-lived threads. The loop maps the ENTIRE persisted thread into
  * `ModelMessage[]` before every turn (see `runAgentLoop` in `agent-loop.ts`); with no window
  * configured that whole history rides every turn, so input tokens (cost + latency, and eventually
- * the model's context limit) grow without bound as a thread accumulates messages. A `HistoryWindow`
- * is a black box like {@link import('./retriever.js').Retriever} — the loop hands it the full
- * mapped history and uses whatever it returns, whether that's a plain truncation (this package
- * ships {@link import('../history-window.js').SlidingWindowHistory}) or a summarizing impl that
- * calls a model to fold dropped messages into a synthetic recap message.
+ * the model's context limit) grow without bound as a thread accumulates messages. This package
+ * ships {@link import('../history-window.js').SlidingWindowHistory}; anything satisfying the seam
+ * works.
  *
- * Applied inside `hooks.step` so durable replay reuses the SAME windowed result deterministically —
- * required for any impl that calls a model (its own cost must not be paid twice on resume) and
- * harmless for a pure truncator.
+ * The two halves run in deliberately different places, and that split is what lets a window exist
+ * without moving a single one of the loop's checkpoint positions — see each method.
  */
 export interface HistoryWindow {
-    apply(messages: ModelMessage[], ctx: HistoryWindowContext): ModelMessage[] | Promise<ModelMessage[]>;
+    /**
+     * The most messages {@link select} can ever keep, where the ceiling can be stated as a row count.
+     *
+     * A hint the loop hands to the store, which then reads that many of the thread's newest rows
+     * rather than its whole transcript (see {@link import('./agent-store.js').ThreadTurnReader}).
+     * Declaring it is a PROMISE about `select`: that it keeps at most this many messages, and that
+     * they are the NEWEST ones — so a window of this size is indistinguishable, to `select`, from the
+     * full transcript. A window that can keep more than this, or something older than the newest
+     * `maxMessages`, must omit it rather than select over rows the store was never asked for.
+     *
+     * Omit where the ceiling is not a row count at all. Omitting costs only the bound on the READ; the
+     * prompt is identical either way.
+     */
+    readonly maxMessages?: number;
+    /**
+     * Decide what the model sees.
+     *
+     * MUST be a pure function of `messages`. The loop calls it OUTSIDE any checkpoint, which is safe
+     * only because its input already IS one (`load:thread`'s cached result), so a replay re-runs it
+     * over the same messages and reaches the same split. Read a clock, a feature flag or a database
+     * here and the resumed run windows differently from the one that suspended: the model gets a
+     * different prompt, and any step whose existence depends on the split lands at a position the
+     * history has no room for. Anything non-deterministic belongs in {@link summarize}.
+     *
+     * The newest message must always be in `keep` — dropping it leaves the turn with nothing to answer.
+     */
+    select(messages: ModelMessage[], ctx: HistoryWindowContext): HistorySelection;
+    /**
+     * Fold the dropped messages into prose the model reads in their place, prepended to the window as
+     * a `system` message. Optional — without it, dropped messages are simply gone.
+     *
+     * Runs inside the loop's `history:summarize` checkpoint, so it may call a model or hit the
+     * network: the first attempt's result is journaled and every replay reads it back instead of
+     * re-summarizing (and instead of paying for it twice). It runs once per RUN, not per model step,
+     * and only when `select` actually dropped something.
+     */
+    summarize?(dropped: ModelMessage[], ctx: HistoryWindowContext): Promise<HistorySummary>;
 }
 //# sourceMappingURL=history-window.d.ts.map

package/dist/src/spi/history-window.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history-window.d.ts","sourceRoot":"","sources":["../../../src/spi/history-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEvD,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CACH,QAAQ,EAAE,YAAY,EAAE,EACxB,GAAG,EAAE,oBAAoB,GACxB,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC7C"}
+{"version":3,"file":"history-window.d.ts","sourceRoot":"","sources":["../../../src/spi/history-window.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErE,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,oGAAoG;IACpG,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,oBAAoB,GAAG,gBAAgB,CAAC;IAC9E;;;;;;;;OAQG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACzF"}

package/dist/src/spi/model-provider.d.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { MessageUsage, ModelMessage, ToolCallRequest, ToolDefinition } from '../types.js';
 import type { SinkWriter } from './token-stream-sink.js';
 export interface ModelTurnArgs {
@@ -7,6 +8,16 @@ export interface ModelTurnArgs {
     /** The model writes streamed text deltas here as it generates them. */
     sink: SinkWriter;
     abortSignal?: AbortSignal;
+    /**
+     * Constrain this call's reply to a schema. Set only by the loop's structured-output formatting
+     * pass, which is non-streamed and carries `tools: []` — most providers cannot serve a response
+     * format and a tool set in the same request.
+     *
+     * An adapter that can constrain generation should, and report what it parsed as
+     * {@link ModelTurnResult.object}. One that cannot may ignore it entirely: the loop validates the
+     * reply either way, reading the JSON out of the text when no `object` comes back.
+     */
+    outputSchema?: StandardSchemaV1;
 }
 /** The outcome of ONE assistant turn. The loop — not the model — drives tool execution. */
 export interface ModelTurnResult {
@@ -26,6 +37,13 @@ export interface ModelTurnResult {
      * governance read-model uses it verbatim; otherwise it estimates from tokens × the pricing table.
      */
     costUsd?: number;
+    /**
+     * What the provider parsed out of a reply it constrained to {@link ModelTurnArgs.outputSchema}.
+     * The loop VALIDATES it regardless — "the provider says it matched" is not the same claim as "it
+     * matches", and a provider that ignored the schema has to fail where the failure is repairable.
+     * Omit when the adapter did not constrain generation.
+     */
+    object?: unknown;
 }
 /**
  * Thin wrapper over the actual LLM. The concrete impl (e.g. Vercel AI SDK `streamText`

package/dist/src/spi/model-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-provider.d.ts","sourceRoot":"","sources":["../../../src/spi/model-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACxD"}
+{"version":3,"file":"model-provider.d.ts","sourceRoot":"","sources":["../../../src/spi/model-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACxD"}

package/dist/src/spi/processors.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
+ * the prompt on its way out, an {@link OutputProcessor} inspects the answer on its way back and may
+ * redact, replace or refuse it. Wire them as `AgentLoopDeps.inputProcessors` / `outputProcessors`.
+ *
+ * WHAT THESE ARE NOT: a second way to decide what enters the context. {@link
+ * import('./history-window.js').HistoryWindow} owns SELECTION — which of the thread's messages ride
+ * into the turn, and what stands in for the rest. Processors run on whatever selection produced and
+ * own TRANSFORMATION — what those messages say. The distinction is load-bearing rather than
+ * stylistic: `select` is contractually pure and runs outside any checkpoint, while a processor is
+ * allowed to call a model, runs in a checkpoint of its own per step, and rewrites a DERIVED prompt
+ * that never becomes the thread's own memory of what was said.
+ */
+import type { Actor, ModelMessage, ToolCallRequest } from '../types.js';
+/** Which turn, and which model step of it, a processor is looking at. */
+export interface ProcessorContext {
+    threadId: string;
+    actor: Actor;
+    /** The agent running this turn. Undefined → the default/single agent. */
+    agentName?: string;
+    /** The persona the request selected, when it selected one. */
+    persona?: string;
+    /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
+    step: number;
+}
+/** Everything the model is about to be sent, as the previous processor in the chain left it. */
+export interface ProcessedPrompt {
+    /** The composed system prompt (agent base + persona + any injected retrieval block). */
+    system: string;
+    /** The turn's messages, oldest-first, already through the history ceiling. */
+    messages: ModelMessage[];
+}
+/**
+ * Rewrites the prompt before each model call of a turn — masking identifiers, stamping a policy
+ * preamble, collapsing an oversized tool result. Runs on EVERY step, not once per run, because the
+ * transcript grows between steps: a redactor that only saw the opening prompt would wave through
+ * whatever a tool result carried back.
+ *
+ * Runs inside the loop's `process:input:<step>` checkpoint and its result is journaled, so a
+ * processor may call a model or hit the network — a resumed run reads back the prompt the suspended
+ * attempt built rather than composing a different one.
+ */
+export interface InputProcessor {
+    /** Identifies this processor in a failure. Keep it stable — it is user-visible on an error. */
+    readonly name: string;
+    process(prompt: ProcessedPrompt, ctx: ProcessorContext): ProcessedPrompt | Promise<ProcessedPrompt>;
+}
+/** One model step's answer, as the previous processor in the chain left it. */
+export interface ModelAnswer {
+    /** The assembled assistant text for this step. */
+    text: string;
+    /**
+     * The tool calls the same step asked for. Read-only context — a processor cannot change them.
+     * A provider reports its calls when `runTurn` RETURNS, so on the incremental path (where the chain
+     * rules on a prefix while the call is still streaming) this is empty until the authoritative
+     * whole-answer pass, which always sees them.
+     */
+    toolCalls: readonly ToolCallRequest[];
+}
+/**
+ * What an {@link OutputProcessor} decided. `pass` hands the text to the next processor unchanged;
+ * `replace` hands it on rewritten (a redaction is a replacement); `reject` ends the chain AND the
+ * run — the text is never streamed, never persisted, and the caller gets an
+ * {@link OutputRejectedError} rather than an answer.
+ */
+export type OutputVerdict = {
+    action: 'pass';
+} | {
+    action: 'replace';
+    text: string;
+} | {
+    action: 'reject';
+    reason: string;
+};
+/**
+ * Characters an incremental gate keeps holding at the end of the transformed answer, when a
+ * processor declares {@link IncrementalGating} without naming its own window. Wide enough for the
+ * patterns a redactor is usually written against — an SSN, an email address, a card number — and
+ * deliberately not wider: the window IS the answer's minimum latency tail, since those characters
+ * are only released once the whole-answer pass runs.
+ */
+export declare const DEFAULT_INCREMENTAL_LOOKBACK_CHARS = 64;
+/**
+ * A processor's statement that its verdict on a PREFIX of an answer is worth acting on, which is
+ * what lets the loop release that prefix to the reader instead of holding the whole answer.
+ *
+ * Declaring it is a promise about every prefix `P` of the final answer, and the loop takes it at
+ * face value on the streaming path:
+ *
+ * 1. REJECTION IS PREFIX-DECIDABLE. The refusal this processor would return for the whole answer is
+ *    already returned for the first prefix that contains the reason. A refusal that only emerges
+ *    from the complete answer still fails the run, but by then the reader has seen a prefix — there
+ *    is no un-sending frames, and that is the cost of opting in.
+ * 2. REPLACEMENT IS PREFIX-STABLE UP TO THE WINDOW. Once a character of `process(P)`'s output is
+ *    more than {@link IncrementalGating.lookbackChars} from the end of that output, it never changes
+ *    as `P` grows.
+ *
+ * A broken second promise is caught, not tolerated: the whole-answer pass stays authoritative, and
+ * the loop raises a {@link ProcessorFailedError} when its result is not an extension of what the
+ * chain already released. So a window too short for a pattern fails loudly rather than streaming the
+ * text it was supposed to redact.
+ */
+export interface IncrementalGating {
+    /**
+     * How many characters of this processor's own output stay held back. Undefined →
+     * {@link DEFAULT_INCREMENTAL_LOOKBACK_CHARS}. Set it to the length of the longest pattern the
+     * processor can act on — anything shorter is a run that fails on the pattern it was written for.
+     */
+    readonly lookbackChars?: number;
+}
+/**
+ * Inspects each model step's answer before anything downstream sees it — before it reaches the live
+ * stream, before it is persisted, before it becomes the next step's context.
+ *
+ * Gating an answer and streaming it as it is generated are mutually exclusive, so registering ANY
+ * output processor switches the turn's model call off the run's sink: nothing reaches the subscriber
+ * until this chain has ruled on it. How much of that costs the reader is what
+ * {@link OutputProcessor.incremental} decides.
+ *
+ * Runs inside the loop's `process:output:<step>` checkpoint (which also performs the release), so a
+ * processor may call a model — a moderation pass is the motivating case — and a replay reads the
+ * verdict back instead of re-deciding it.
+ */
+export interface OutputProcessor {
+    /** Identifies this processor in a rejection or a failure. User-visible; keep it stable. */
+    readonly name: string;
+    /**
+     * Opt this processor into gating a PREFIX, so the turn keeps streaming — see
+     * {@link IncrementalGating} for what declaring it promises. Undefined means the whole answer,
+     * which is what a processor written against the complete text needs and therefore the only safe
+     * default; a chain is incremental only when EVERY member of it declares this, so a neighbour can
+     * never downgrade what another author was given.
+     */
+    readonly incremental?: IncrementalGating;
+    process(answer: ModelAnswer, ctx: ProcessorContext): OutputVerdict | Promise<OutputVerdict>;
+}
+/**
+ * The run ended because an output processor refused the answer — NOT because the model failed. The
+ * two must stay distinguishable: a model failure is worth retrying and worth paging someone about, a
+ * refusal is the control doing its job.
+ */
+export declare class OutputRejectedError extends Error {
+    /** {@link OutputProcessor.name} of the processor that refused. */
+    readonly processor: string;
+    /** The reason it gave, verbatim. */
+    readonly reason: string;
+    constructor(processor: string, reason: string);
+}
+/**
+ * A processor threw. Wrapped so it can never be mistaken for the model call failing — the loop's
+ * only other source of failure at that point in the turn — and so the failure names the processor
+ * that produced it instead of surfacing a bare `TypeError` from someone else's code.
+ */
+export declare class ProcessorFailedError extends Error {
+    /** Which seam it was on, so a reader knows whether the prompt or the answer was in flight. */
+    readonly phase: 'input' | 'output';
+    /** The processor's `name`. */
+    readonly processor: string;
+    constructor(phase: 'input' | 'output', processor: string, cause: unknown);
+}
+//# sourceMappingURL=processors.d.ts.map

package/dist/src/spi/processors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../../src/spi/processors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAExE,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gGAAgG;AAChG,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CACL,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,gBAAgB,GACpB,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC/C;AAED,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IACzC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,gBAAgB,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC7F;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAK5C;CACF;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAQvE;CACF"}

package/dist/src/spi/processors.js

@@ -0,0 +1,57 @@
+/**
+ * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
+ * the prompt on its way out, an {@link OutputProcessor} inspects the answer on its way back and may
+ * redact, replace or refuse it. Wire them as `AgentLoopDeps.inputProcessors` / `outputProcessors`.
+ *
+ * WHAT THESE ARE NOT: a second way to decide what enters the context. {@link
+ * import('./history-window.js').HistoryWindow} owns SELECTION — which of the thread's messages ride
+ * into the turn, and what stands in for the rest. Processors run on whatever selection produced and
+ * own TRANSFORMATION — what those messages say. The distinction is load-bearing rather than
+ * stylistic: `select` is contractually pure and runs outside any checkpoint, while a processor is
+ * allowed to call a model, runs in a checkpoint of its own per step, and rewrites a DERIVED prompt
+ * that never becomes the thread's own memory of what was said.
+ */
+/**
+ * Characters an incremental gate keeps holding at the end of the transformed answer, when a
+ * processor declares {@link IncrementalGating} without naming its own window. Wide enough for the
+ * patterns a redactor is usually written against — an SSN, an email address, a card number — and
+ * deliberately not wider: the window IS the answer's minimum latency tail, since those characters
+ * are only released once the whole-answer pass runs.
+ */
+export const DEFAULT_INCREMENTAL_LOOKBACK_CHARS = 64;
+/**
+ * The run ended because an output processor refused the answer — NOT because the model failed. The
+ * two must stay distinguishable: a model failure is worth retrying and worth paging someone about, a
+ * refusal is the control doing its job.
+ */
+export class OutputRejectedError extends Error {
+    /** {@link OutputProcessor.name} of the processor that refused. */
+    processor;
+    /** The reason it gave, verbatim. */
+    reason;
+    constructor(processor, reason) {
+        super(`Output rejected by "${processor}": ${reason}`);
+        this.name = 'OutputRejectedError';
+        this.processor = processor;
+        this.reason = reason;
+    }
+}
+/**
+ * A processor threw. Wrapped so it can never be mistaken for the model call failing — the loop's
+ * only other source of failure at that point in the turn — and so the failure names the processor
+ * that produced it instead of surfacing a bare `TypeError` from someone else's code.
+ */
+export class ProcessorFailedError extends Error {
+    /** Which seam it was on, so a reader knows whether the prompt or the answer was in flight. */
+    phase;
+    /** The processor's `name`. */
+    processor;
+    constructor(phase, processor, cause) {
+        super(`${phase} processor "${processor}" failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = 'ProcessorFailedError';
+        this.phase = phase;
+        this.processor = processor;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=processors.js.map

package/dist/src/spi/processors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.js","sourceRoot":"","sources":["../../../src/spi/processors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,EAAE,CAAC;AA0DrD;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,kEAAkE;IACzD,SAAS,CAAS;IAC3B,oCAAoC;IAC3B,MAAM,CAAS;IAExB,YAAY,SAAiB,EAAE,MAAc;QAC3C,KAAK,CAAC,uBAAuB,SAAS,MAAM,MAAM,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,8FAA8F;IACrF,KAAK,CAAqB;IACnC,8BAA8B;IACrB,SAAS,CAAS;IAE3B,YAAY,KAAyB,EAAE,SAAiB,EAAE,KAAc;QACtE,KAAK,CACH,GAAG,KAAK,eAAe,SAAS,aAAa,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACtG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/src/spi/token-stream-sink.d.ts

@@ -1,3 +1,4 @@
+import type { ElicitationRequest } from '../elicitation.js';
 /**
  * The "data plane": live token transport, decoupled from the durable control plane.
  *
@@ -13,6 +14,38 @@ export type StreamFrame = {
     t: 'component';
     name: string;
     data: unknown;
+}
+/**
+ * A question set the run is now parked on. Carries the whole request, so a client renders the form
+ * — and knows the total ("Question 1 of 3") — without a second fetch. Identical whether a
+ * configured intake or the model's `ask` authored it.
+ *
+ * `runId` is the run that is PARKED, which is not always the stream this frame arrived on: a
+ * delegated sub-agent forwards its frames into its top-level ancestor's stream so the human can
+ * see them, and answering it means addressing the CHILD's run. Without the id on the frame a
+ * watcher has the form and no way to reply to it.
+ */
+ | {
+    t: 'elicitation';
+    runId: string;
+    id: string;
+    request: ElicitationRequest;
+}
+/**
+ * An `action` tool call the run is now parked on, waiting for an approve/reject. Carries the tool
+ * and the arguments it was asked to run with, so a watcher can decide without a second fetch.
+ *
+ * `runId`, like the elicitation frame's, is the run that is PARKED rather than the stream this
+ * arrived on: a delegated sub-agent's action suspends its OWN run, and forwarding the frame into
+ * the ancestor's stream is the only way a human sees it — so the id has to ride along, or the
+ * watcher can see the approval and not make it.
+ */
+ | {
+    t: 'approval';
+    runId: string;
+    id: string;
+    toolName: string;
+    input: unknown;
 };
 export interface SinkWriter {
     write(frame: StreamFrame): void | Promise<void>;
@@ -27,4 +60,14 @@ export interface TokenStreamSink {
     /** Drop any buffer/resources for the run. */
     close(runId: string): void | Promise<void>;
 }
+/**
+ * Wrap a {@link SinkWriter} so a DELEGATED run forwards its frames into its top-level ancestor's
+ * stream but never closes it.
+ *
+ * Forwarding is what makes a sub-agent visible at all: its own runId is not a stream anyone
+ * subscribed to, so a question set it parks on would otherwise be written where nobody reads it.
+ * The ancestor owns the stream's lifecycle across however many delegations it spans, so the child's
+ * `end()` is a no-op — ending the shared stream mid-parent-run would cut the human off.
+ */
+export declare function childSinkWriter(inner: SinkWriter): SinkWriter;
 //# sourceMappingURL=token-stream-sink.d.ts.map