experimental-a2 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.20.0
+
+### Minor Changes
+
+- 123c993: The Postgres store no longer creates its tables. Before you deploy this release, apply the SQL it needs, `node_modules/experimental-a2/sql/postgres/schema.sql`, once per database, however you run SQL against it. It creates only what is missing and leaves existing data alone, so it is safe on a database an earlier release set up, and the deployment that is running now keeps working against it, without waiting on its writes. It also records a schema version in a new `a2_schema` table. Apply it as the role your app connects with; if another role applies it, grant your app's role `select` on `a2_schema`. With `listenConnectionString`, also apply `sql/postgres/notifications.sql`, which installs the triggers A2 used to install for you.
+
+  If you deploy first, the store throws `STORE_NOT_CONFIGURED` on its first query, naming the file to apply, and the next call after you apply it succeeds without a redeploy. Until then, nothing is written: appends fail, and scheduled work waits. Vercel Queues keeps redelivering it, and the QStash scheduler now treats `STORE_NOT_CONFIGURED` like a store outage, handing each task to a later message (30 seconds, backing off to one day) instead of letting QStash's retries run out into its DLQ. That also covers a missing driver package, which used to dead-letter.
+
+  Each cold start now reads the schema version instead of running DDL. The DDL took a share lock on `a2_events` even when every table existed, so a cold start waited behind any open write to it, and writes waited behind the cold start. The store also no longer needs permission to create tables, so a runtime role with only read and write access works. SQLite still creates its tables on open.
+
+### Patch Changes
+
+- 123c993: Docs: stores and schedulers each get their own section, with one page per adapter, such as `docs/stores/04-postgres.mdx` and `docs/schedulers/03-qstash.mdx`. `docs/server/05-production.mdx` is gone: resolving dead letters moved to `docs/server/01-handlers.mdx`, and traces to `docs/reference/05-telemetry.mdx`, which replaces `docs/reference/05-adapters.mdx`.
+- 5228ecb: A returned batch the store refuses, such as one that reuses an event id, now dead-letters the event on that first attempt, like a `NonRetriableError`, with the store's error as its `lastError`: a retry would return the same ids. Before, the refused completion left the claim to lapse, so the event was retried on every watchdog wake and dead-lettered with no error. A scheduler delivery whose drain throws after arming its successor watchdog now acknowledges once that successor is durable, with the error on its `a2.drain` span (`a2.drain.outcome: failed`). Before, it threw: Vercel Queues redelivered the message alongside the successor, each redelivery arming another, and QStash retried it or, for a store outage, published a second, outage successor. `server.drain()` still throws.
+- 272e603: `fx()` model calls now carry the same AI Gateway defaults as the AI SDK harness: `caching: 'auto'` in the request's Gateway options, under any Gateway options FX sets itself such as its fast tier, and the session's stable `x-session-affinity` header. Before, FX asked for no caching and sent its own affinity, which changed every time A2 rebuilt the kernel, so a response's model calls rarely reused the provider's prompt cache. The rest of each request goes as FX wrote it.
+
+## 0.19.0
+
+### Minor Changes
+
+- 8f373b5: Under `fx()` and `pi()`, a user message's images now reach the model. A2 fetches each `image/*` file part from its `https:` or `data:` URL through the AI SDK's download, which refuses private addresses and checks redirects, up to 32 MiB of one message's files, and keeps what it fetched for the process. FX gets them as image prompt blocks and Pi as prompt and steering images. A file that isn't an image, an image A2 can't fetch, or a steer with files under FX fails the turn with an error that names the file. Every step sends the conversation so far with all its files, as under `{ type: 'ai-sdk' }`.
+
+  Before, both harnesses read only a message's text and dropped its files without a word.
+
+- b83ba8b: `agent()` now throws a `TypeError` when a provider-defined tool (`type: 'provider'`, such as a provider's web search) is passed with `fx()` or `pi()`, as it does for a tool that sets `needsApproval`. Before, both harnesses dropped such a tool without a word, so the model never saw it.
+- 88ee923: A2's AI log stores each message's content once, in the `ai.control.requested` command that brought it in. Before, a message sent with no turn running was stored three times, and a queued or steering one four: in its command, in `ai.control.committed`, and in `ai.message.created`.
+
+  - `ai.message.created` now records an admission as `{ messageId, role, generate? }`. `MessageCreatedPayload` is no longer generic. Only A2's control lane writes the event, after the command that brought its input in; `reduceAIState()` and `deriveUIMessages()` throw on one that no command explains.
+  - `ai.control.committed` never carries message content: queued inputs and `AIState.active.input` are the new `InputRef` type, `{ id, role, generate, afterStepOf? }`. `ActiveTurn` is no longer generic. `AIState.inbox.items` keep their `message`, now with `role`.
+  - `AIMessageOf` reads the message type from the contract's input command schema.
+  - The AI state, model context, and control reducers advance to `a2.ai.state.v27`, `a2.ai.context.v7`, and `a2.ai.control.v6`, so their checkpoints rebuild from the log. Logs written before this release don't fold.
+
+  Reading the log costs nothing more: the transcript's readers keep a queued input's content in their state from its command until its admission.
+
+- da1e0e5: Steering hands off in the order it was sent, as one turn. `steer()` now queues new input right after the turn's earlier steering instead of ahead of it, and `queue.sendNow()` lands after that steering too. At the handoff, every input steering the turn enters together: the last one starts the new turn and the earlier ones enter as its context (`generate: false`), so the model answers them once. Under `fx()` and `pi()`, they reach the harness as one steering message. A turn paused with `pause({ when: 'now' })` keeps its steering until `resume()`, so every steer sent while it's paused targets it and they all enter on Resume.
+
+  Before, each steer jumped to the front, so several steers ran last-first, each as its own turn, and the first steer ended a paused turn at once, leaving later steers no turn to target.
+
+### Patch Changes
+
+- 9b80f3e: Under `pi()`, `speed: 'fast'` now asks AI Gateway for the model's fast tier on each of Pi's model calls, as it already did under `{ type: 'ai-sdk' }` and `fx()`. Before, `pi()` ignored `speed`, so every step ran at standard speed.
+- b83ba8b: The interruption reason `'steered after step'` is reserved: A2 writes it when steering ends a response, and `fx()` and `pi()` replay the next response as that steering. A client interruption that carries it is now rejected. Before, one would make the harness replay a stopped response as steered, so the replay diverged and the session failed.
+- c7afea6: `vercelQueues()` no longer refuses delays over six days itself. A task's delay goes to Vercel Queues as asked, with the seven-day retention it already set, and Vercel Queues refuses one longer than that.
+
 ## 0.18.1
 
 ### Patch Changes

package/dist/actor.js

@@ -1,7 +1,7 @@
 import { a as NonRetriableError, i as A2Error, n as isSessionCleared, r as sessionClearedError } from "./session-clear-DGI4jTQ5.js";
 import { n as internalContract } from "./contract-BYKASlCV.js";
 import { v as serverInternals } from "./internal-CscSY7K_.js";
-import { c as parsePresenceSibling, o as setServerFetchHooks, s as sseResponse, t as createServer } from "./server-D-Y4pqwu.js";
+import { c as parsePresenceSibling, o as setServerFetchHooks, s as sseResponse, t as createServer } from "./server-qyb5aJJG.js";
 import { a as actorFailedSchema, c as isJsonTree, i as ActorRefusedError, l as openPresenceDefs, n as ACTOR_LANE, o as actorReducer, r as ACTOR_STATE_EVENT, s as actorStateSchema, t as ACTOR_FAILED_EVENT } from "./actor-shared-t7w8xIKP.js";
 //#region src/actor.ts
 /**

package/dist/{ai-BMLlI2Ff.d.ts → ai-Cz3hqVhk.d.ts}

@@ -22,12 +22,20 @@ type MessageBase = {
 };
 //#endregion
 //#region src/ai-control.d.ts
-type InboxItem<M extends UIMessage = UIMessage> = {
+/**
+ * An input in the queue or the active turn. Its content stays in the
+ * `ai.control.requested` command that brought it, and in no other event.
+ */
+type InputRef = {
   id: string;
-  message: M;
+  role: UIMessage["role"];
   generate: boolean;
   afterStepOf?: string;
 };
+/** A queued input with its content, as `AIState` shows it. */
+type InboxItem<M extends UIMessage = UIMessage> = InputRef & {
+  message: M;
+};
 type ControlCommand<M extends UIMessage = UIMessage> = {
   action: "send";
   message: M;
@@ -86,9 +94,9 @@ type ControlReceipt = {
   outcome: "applied" | "rejected";
   reason?: "not-pending" | "role-mismatch" | "stale-turn" | "not-found" | "closed" | "stale-work" | "not-user-input";
 };
-type ActiveTurn<M extends UIMessage = UIMessage> = {
+type ActiveTurn = {
   turnId: string;
-  input: InboxItem<M>;
+  input: InputRef;
   phase: "starting" | "generating" | "tools" | "waiting" | "failed" | "pausing" | "paused";
 };
 type WorkFact = {
@@ -216,10 +224,15 @@ type SessionCreatedPayload = {
 type SessionClosedPayload = {
   reason?: string;
 };
-type MessageCreatedPayload<M extends UIMessage$1> = {
-  message: M;
-  /** For user messages, false records passive context. Omission or true schedules. */
-  generate?: boolean;
+/**
+ * A message entering the transcript. Its content is the command's that brought
+ * it in, which every reader of the transcript has already folded.
+ */
+type MessageCreatedPayload = {
+  messageId: string;
+  role: UIMessage$1["role"];
+  /** For user messages, false records passive context. Omission schedules. */
+  generate?: false;
 };
 type MessageCompletedPayload = {
   messageId: string;
@@ -400,7 +413,7 @@ type AIEventDefs<M extends UIMessage$1 = UIMessage$1> = {
   }>;
   "ai.session.created": StandardSchemaV1<SessionCreatedPayload>;
   "ai.session.closed": StandardSchemaV1<SessionClosedPayload>;
-  "ai.message.created": StandardSchemaV1<MessageCreatedPayload<M>>;
+  "ai.message.created": StandardSchemaV1<MessageCreatedPayload>;
   "ai.message.completed": StandardSchemaV1<MessageCompletedPayload>;
   "ai.message.interrupted": StandardSchemaV1<MessageInterruptedPayload>;
   "ai.generation.requested": StandardSchemaV1<GenerationRequestedPayload>;
@@ -491,7 +504,7 @@ type AIState<M extends UIMessage$1 = UIMessage$1> = {
     items: InboxItem<M>[];
   };
   pendingQueueCommands?: PendingQueueCommand<M>[];
-  active: ActiveTurn<M> | null;
+  active: ActiveTurn | null;
   starting: boolean;
   receipt: ControlReceipt | null;
   pausedGenerationIds?: Record<string, true>;
@@ -518,10 +531,14 @@ type AIState<M extends UIMessage$1 = UIMessage$1> = {
   usage: GenerationUsage[];
   error: string | null;
 };
-/** The `UIMessage` type a contract's `ai.message.created` schema carries. */
+/** The `UIMessage` type a contract's input commands carry. */
 type AIMessageOf<D> = D extends {
-  readonly "ai.message.created": infer S extends StandardSchemaV1;
-} ? StandardSchemaV1.InferOutput<S> extends MessageCreatedPayload<infer M extends UIMessage$1> ? M : UIMessage$1 : UIMessage$1;
+  readonly "ai.control.requested": infer S extends StandardSchemaV1;
+} ? Extract<StandardSchemaV1.InferOutput<S>, {
+  action: "send";
+}> extends {
+  message: infer M extends UIMessage$1;
+} ? M : UIMessage$1 : UIMessage$1;
 /** What `agentContract()` returns: the AI protocol, with `X` as application state. */
 type AgentContract<M extends UIMessage$1 = UIMessage$1, D extends EventDefs = AIEventDefs<M>, X extends object = Record<never, never>> = Contract<D, Record<never, never>, AgentReducer<M, D, X>>;
 type AgentToolEventDefs = EventDefs & Pick<AIEventDefs, "ai.tool.execution.requested">;
@@ -640,7 +657,7 @@ declare const inputs: AIInputs;
  */
 declare function handlerContext<D extends AgentToolEventDefs = AIEventDefs>(contract?: Contract<D>): AgentToolContext<D>;
 /** The built-in AI reducer's name, and so its checkpoint identity. */
-declare const AI_STATE_REDUCER = "a2.ai.state.v26";
+declare const AI_STATE_REDUCER = "a2.ai.state.v27";
 /**
  * The built-in AI protocol plus application events, as a core contract whose
  * reducer folds `AIState`. Isomorphic: share it when a client needs
@@ -649,5 +666,5 @@ declare const AI_STATE_REDUCER = "a2.ai.state.v26";
  */
 declare function agentContract<M extends UIMessage$1 = UIMessage$1, E extends EventDefs = Record<never, never>, X extends object = Record<never, never>>(options: AgentContractOptions<M, E, X>): AgentContract<M, AIEventDefs<M> & E, X>;
 //#endregion
-export { agentContract as $, InputRespondedPayload as A, PendingApproval as B, GenerationFailedPayload as C, GenerationStartedPayload as D, GenerationRequestedPayload as E, MessageInterruptedPayload as F, SessionClosedPayload as G, ReasoningLevel as H, ModelLimits as I, ToolCalledPayload as J, SessionCreatedPayload as K, ModelMetadataRequestedPayload as L, LanguageModelUsage as M, MessageCompletedPayload as N, GenerationUsage as O, MessageCreatedPayload as P, UIMessageChunk$1 as Q, ModelMetadataResolvedPayload as R, GenerationCompletedPayload as S, GenerationReason as T, RetryGenerationOptions as U, PendingInput as V, RetryRequestedPayload as W, TranscriptMessage as X, ToolResultPayload as Y, UIMessage$1 as Z, CompactionPart as _, AI_STATE_REDUCER as a, reasoningLevels as at, CompactionState as b, AgentContract as c, PendingQueueCommand as ct, AgentStatus as d, ControlReceipt as dt, createEvents as et, AgentToolContext as f, InboxItem as ft, CompactionCompletedPayload as g, ApprovalRespondedPayload as h, AIState as i, inputs as it, JSONValue$1 as j, InputRequestedPayload as k, AgentContractOptions as l, ActiveTurn as lt, ApprovalRequestedPayload as m, AIInputs as n, events as nt, ActiveGeneration as o, reduceAIState as ot, AgentToolEventDefs as p, ToolActivity as q, AIMessageOf as r, handlerContext as rt, ActiveGenerationProjection as s, isCompactionPart as st, AIEventDefs as t, deriveUIMessages as tt, AgentReducer as u, ControlCommand as ut, CompactionPartData as v, GenerationProgressPayload as w, FinishReason as x, CompactionRequestedPayload as y, ModelMetadataState as z };
-//# sourceMappingURL=ai-BMLlI2Ff.d.ts.map
+export { agentContract as $, InputRespondedPayload as A, PendingApproval as B, GenerationFailedPayload as C, GenerationStartedPayload as D, GenerationRequestedPayload as E, MessageInterruptedPayload as F, SessionClosedPayload as G, ReasoningLevel as H, ModelLimits as I, ToolCalledPayload as J, SessionCreatedPayload as K, ModelMetadataRequestedPayload as L, LanguageModelUsage as M, MessageCompletedPayload as N, GenerationUsage as O, MessageCreatedPayload as P, UIMessageChunk$1 as Q, ModelMetadataResolvedPayload as R, GenerationCompletedPayload as S, GenerationReason as T, RetryGenerationOptions as U, PendingInput as V, RetryRequestedPayload as W, TranscriptMessage as X, ToolResultPayload as Y, UIMessage$1 as Z, CompactionPart as _, AI_STATE_REDUCER as a, reasoningLevels as at, CompactionState as b, AgentContract as c, PendingQueueCommand as ct, AgentStatus as d, ControlReceipt as dt, createEvents as et, AgentToolContext as f, InboxItem as ft, CompactionCompletedPayload as g, ApprovalRespondedPayload as h, AIState as i, inputs as it, JSONValue$1 as j, InputRequestedPayload as k, AgentContractOptions as l, ActiveTurn as lt, ApprovalRequestedPayload as m, AIInputs as n, events as nt, ActiveGeneration as o, reduceAIState as ot, AgentToolEventDefs as p, InputRef as pt, ToolActivity as q, AIMessageOf as r, handlerContext as rt, ActiveGenerationProjection as s, isCompactionPart as st, AIEventDefs as t, deriveUIMessages as tt, AgentReducer as u, ControlCommand as ut, CompactionPartData as v, GenerationProgressPayload as w, FinishReason as x, CompactionRequestedPayload as y, ModelMetadataState as z };
+//# sourceMappingURL=ai-Cz3hqVhk.d.ts.map

package/dist/ai-Cz3hqVhk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-Cz3hqVhk.d.ts","names":[],"sources":["../src/ai-message-base.ts","../src/ai-control.ts","../src/ai-client-state.ts","../src/ai-projector.ts","../src/ai-progress-batches.ts","../src/ai-message-projection.ts","../src/ai.ts"],"mappings":";;;;KAGK;EAAc;;EAAsB;;EAAmB;;KACvD,aAAa,eAAe;KAC5B;EAAa,OAAO;;EAAiC,QAAQ;;KAEtD;EACV;EACA,SAAS;EACT,QAAQ,eAAe;;;;;;;;KCQb;EACV;EACA,MAAM;EACN;EACA;;;KAIU,UAAU,UAAU,YAAY,aAAa;EACvD,SAAS;;KAGC,eAAe,UAAU,YAAY;EAC3C;EAAgB,SAAS;EAAG;;EAC5B;EAAgB,SAAS;;EACzB;EAAgB;EAAiB;;EACjC;EAAkB;;EAElB;EACA;EACA;EACA;;EAEA;EAAgB;EAAgB;;EAChC;EAAiB;EAAgB,SAAS;EAAG;;EAC7C;EAAiB;;EACjB;;EACA;EAAuB,QAAQ;;EAC/B;EAAoB,UAAU;;EAC9B;EAAiB,UAAU;;EAC3B;EAAyB,SAAS;;EAClC;EAAiB,SAAS;;EAC1B;EAAqB,SAAS;;KAExB;EACV;EACA;EACA;EACA;;KAUU;EACV;EACA,OAAO;EACP;;KA+BU;EAAa;EAAc;EAAY;;KACvC;EACV;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;;KAGE;EACV;EACA;EACA,MAAM;EACN,YAAY;;KAoDF;EACV;EACA;EACA;EACA;IAAW;IAAe;IAAqB;;EAC/C;IAAS;IAAc;;;KAGb;EACV,SAAS;EACT;IACE;IACA;IACA,OAAO;IACP;IACA;IACA;IACA,eAAe;IACf;IACA;;;;;KC7KQ,aAAa,UAAU,aAAa,QAC9C,eAAe;EAEb;;KAYQ,oBAAoB,UAAU;EACxC;EACA,SAAS,aAAa;;;;KCpBnB;EACH;EACA;EACA;EACA;EACA;EACA;EACA;;KAwJU;EACV,MAAM;EACN,WAAW;EACX,OAAO,eAAe;;;;KChJZ;EAAkB;EAAe,QAAQ;;KAChD,aAAa;EAAoB,MAAM;EAAY,OAAO;;KAEnD;EACV;EACA,MAAM;EACN,QAAQ,MAAM;;;;cCmgBH,mBAAoB;EAC/B;MACE,QAAQ;;;KCncA;KAGA;KAEA,iBAAiB,YAAY;cAE5B,0BAA0B;KAU3B;EACV;EACA;EACA;EACA;EACA,QAAQ;;;KAIE;EACV;EACA;EACA,MAAM;;;;;;KASI,kBAAkB,UAAU,eAAa,KAAK;EACxD,OAAO,MAAM,qBAAqB;;KAGxB;EAA0B,WAAW;;KACrC;EAAyB;;;;;;KAKzB;EACV;EACA,MAAM;;EAEN;;KAEU;EAA4B;;KACnC;EACH;EACA;;EAEA;;KAEU,4BAA4B;EAEhC;EAAsB;;EACtB;EAAmB;;KAEf;EACV;IAAY;IAAgB;;EAC5B;EACA,QAAQ;EACR;EACA;;KAEU;EACV;EACA;EACA;;KAEU,wBAAwB;KACxB;EACV;EACA;EACA;EACA;EACA;;EAEA;EACA;;KAEU;;EAEV;EACA,QAAQ;;KAEE;EACV;EACA;EACA;EACA;EACA,eAAe;EACf,QAAQ;EACR;;KAEU;EACV;EACA;EACA;EACA;EACA;;EAEA;EACA;;KAEU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;KAEU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;KAEU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;;KAEU;EACV;EACA;EACA;EACA;EACA;EACA;;KAEU;EACV;EACA;EACA;EACA;EACA;EACA,WAAW;;KAED;EACV;EACA;EACA;EACA;EACA;EACA,OAAO;;KAEG;EACV;EACA;;KAEU;EAAkC;;KAClC;EACV;EACA,QAAQ;;KAEE;EACN;;EACA;EAAoB,QAAQ;;EAC5B;;KAEM;EACV;EACA;EACA;EACA;EACA;EACA;;KAEU,2BAA2B,UAAU;EAC/C;EACA;EACA;EACA,UAAU;EACV;EACA;EACA,QAAQ;;KAGE,YAAY,UAAU,cAAY;EAC5C,wBAAwB,iBAAiB,eAAe;EACxD,wBAAwB,iBAAiB;EACzC,sBAAsB,iBAAiB;EACvC,oBAAoB,iBAAiB;EACrC,+BAA+B,iBAAiB;EAChD,wBAAwB;IACtB;IACA;;EAEF,sBAAsB,iBAAiB;EACvC,qBAAqB,iBAAiB;EACtC,sBAAsB,iBAAiB;EACvC,wBAAwB,iBAAiB;EACzC,0BAA0B,iBAAiB;EAC3C,2BAA2B,iBAAiB;EAC5C,sBAAsB,iBAAiB;EACvC,yBAAyB,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"}

package/dist/ai-client.d.ts

@@ -1,5 +1,5 @@
 import { s as CreateClientOptions, t as A2Client } from "./client-h_DKFAjj.js";
-import { a as AI_STATE_REDUCER, i as AIState, r as AIMessageOf, t as AIEventDefs } from "./ai-BMLlI2Ff.js";
+import { a as AI_STATE_REDUCER, i as AIState, r as AIMessageOf, t as AIEventDefs } from "./ai-Cz3hqVhk.js";
 //#region src/ai-client.d.ts
 /**
  * The structural shape of `typeof` an `agent({ name })` server: one whose

package/dist/ai-client.js

@@ -1,5 +1,5 @@
 import { t as createClient } from "./client-BhHLoNKF.js";
-import { n as agentContract } from "./ai-D6mGlO8j.js";
+import { n as agentContract } from "./ai-mMiWul1T.js";
 //#region src/ai-client.ts
 /**
 * experimental-a2/ai/client — a client for an `agent()` route that needs no

package/dist/ai-control-CvLbW10B.js

@@ -0,0 +1,46 @@
+//#region src/ai-control.ts
+/**
+* The `ai.message.interrupted` reason A2 writes when steering ends a response
+* after a step; a harness's replay continues the turn on it. Reserved, so a
+* client's interruption can't carry it.
+*/
+const STEERED_REASON = "steered after step";
+/**
+* A fold met an admission no command explains. Only A2's control lane writes
+* `ai.message.created`, after the command that brought its input in.
+*/
+const unexplainedAdmission = (messageId) => /* @__PURE__ */ new TypeError(`ai.message.created for ${messageId} follows no command that brought it in; only A2's control lane writes it`);
+/**
+* Where new steering for a turn goes in the inbox: right after the turn's
+* earlier steering, or first, so it hands off in the order it was sent.
+*/
+const steeringEnd = (items, turnId) => items.findLastIndex((item) => item.afterStepOf === turnId) + 1;
+/**
+* Whether an input steering a turn enters as context for later steering: the
+* run of inputs steering one turn is admitted together, and only its last
+* generating input starts the next turn.
+*/
+const steersOn = (item, rest) => {
+	if (item.afterStepOf === void 0) return false;
+	for (const next of rest) {
+		if (next.afterStepOf !== item.afterStepOf) return false;
+		if (next.generate) return true;
+	}
+	return false;
+};
+const initialControlState = () => ({
+	pendingStops: {},
+	inbox: {
+		paused: false,
+		items: []
+	},
+	active: null,
+	coordinator: {
+		closed: false,
+		queued: []
+	}
+});
+//#endregion
+export { unexplainedAdmission as a, steersOn as i, initialControlState as n, steeringEnd as r, STEERED_REASON as t };
+
+//# sourceMappingURL=ai-control-CvLbW10B.js.map

package/dist/ai-control-CvLbW10B.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-control-CvLbW10B.js","names":[],"sources":["../src/ai-control.ts"],"sourcesContent":["import type { UIMessage } from 'ai'\nimport type { AICoordinatorState } from './ai-coordinator.ts'\nimport type {\n  ApprovalRespondedPayload,\n  GenerationStartedPayload,\n  GenerationReason,\n  InputRequestedPayload,\n  InputRespondedPayload,\n  MessageInterruptedPayload,\n  RetryRequestedPayload,\n  ToolCalledPayload,\n  ToolResultPayload,\n} from './ai.ts'\n\n/**\n * An input in the queue or the active turn. Its content stays in the\n * `ai.control.requested` command that brought it, and in no other event.\n */\nexport type InputRef = {\n  id: string\n  role: UIMessage['role']\n  generate: boolean\n  afterStepOf?: string\n}\n\n/** A queued input with its content, as `AIState` shows it. */\nexport type InboxItem<M extends UIMessage = UIMessage> = InputRef & {\n  message: M\n}\n\nexport type ControlCommand<M extends UIMessage = UIMessage> =\n  | { action: 'send'; message: M; generate?: boolean }\n  | { action: 'edit'; message: M }\n  | { action: 'move'; inputId: string; beforeId: string | null }\n  | { action: 'remove'; inputId: string }\n  | {\n      action: 'send-now'\n      inputId: string\n      turnId: string | null\n      lastSeenIndex?: number\n    }\n  | { action: 'stop'; turnId: string; lastSeenIndex?: number }\n  | { action: 'steer'; turnId: string; message: M; lastSeenIndex?: number }\n  | { action: 'pause'; when: 'now' | 'after-turn' }\n  | { action: 'resume' }\n  | { action: 'tool-result'; result: ToolResultPayload }\n  | { action: 'approval'; response: ApprovalRespondedPayload }\n  | { action: 'input'; response: InputRespondedPayload }\n  | { action: 'request-input'; request: InputRequestedPayload }\n  | { action: 'retry'; request: RetryRequestedPayload }\n  | { action: 'interrupt'; request: MessageInterruptedPayload }\n\nexport type ControlReceipt = {\n  commandId: string\n  work?: true\n  outcome: 'applied' | 'rejected'\n  reason?:\n    | 'not-pending'\n    | 'role-mismatch'\n    | 'stale-turn'\n    | 'not-found'\n    | 'closed'\n    | 'stale-work'\n    | 'not-user-input'\n}\n\nexport type ActiveTurn = {\n  turnId: string\n  input: InputRef\n  phase:\n    | 'starting'\n    | 'generating'\n    | 'tools'\n    | 'waiting'\n    | 'failed'\n    | 'pausing'\n    | 'paused'\n}\n\nexport type ControlWork = {\n  id: string\n  version: number\n  settled: boolean\n  attempt?: number\n  facts?: string[]\n}\n\nexport type AIControlState = {\n  pendingStops: Record<string, string>\n  inbox: { paused: boolean; items: InputRef[] }\n  active:\n    | (ActiveTurn & {\n        version: number\n        suspended: boolean\n        model: ControlWork | null\n      })\n    | null\n  coordinator: AICoordinatorState\n}\n\nexport type WorkFact = { type: string; id: string; payload: unknown }\nexport type WorkReport = {\n  attempt: number\n  workId: string\n  turnId: string\n  version: number\n  kind: 'model' | 'tool'\n  settled: boolean\n  events: WorkFact[]\n}\n\nexport type ToolExecutionRequest = {\n  turnId: string\n  version: number\n  call: ToolCalledPayload\n  generation: GenerationStartedPayload\n}\n\n/**\n * The `ai.message.interrupted` reason A2 writes when steering ends a response\n * after a step; a harness's replay continues the turn on it. Reserved, so a\n * client's interruption can't carry it.\n */\nexport const STEERED_REASON = 'steered after step'\n\n/**\n * A fold met an admission no command explains. Only A2's control lane writes\n * `ai.message.created`, after the command that brought its input in.\n */\nexport const unexplainedAdmission = (messageId: string): TypeError =>\n  new TypeError(\n    `ai.message.created for ${messageId} follows no command that brought it in; only A2's control lane writes it`,\n  )\n\n/**\n * Where new steering for a turn goes in the inbox: right after the turn's\n * earlier steering, or first, so it hands off in the order it was sent.\n */\nexport const steeringEnd = (\n  items: readonly InputRef[],\n  turnId: string,\n): number => items.findLastIndex((item) => item.afterStepOf === turnId) + 1\n\n/**\n * Whether an input steering a turn enters as context for later steering: the\n * run of inputs steering one turn is admitted together, and only its last\n * generating input starts the next turn.\n */\nexport const steersOn = (\n  item: InputRef,\n  rest: readonly InputRef[],\n): boolean => {\n  if (item.afterStepOf === undefined) return false\n  for (const next of rest) {\n    if (next.afterStepOf !== item.afterStepOf) return false\n    if (next.generate) return true\n  }\n  return false\n}\n\nexport const initialControlState = (): AIControlState => ({\n  pendingStops: {},\n  inbox: { paused: false, items: [] },\n  active: null,\n  coordinator: { closed: false, queued: [] },\n})\n\nexport type ControlChange = {\n  path: (string | number)[]\n  value?: unknown\n  remove?: true\n  splice?: { index: number; deleteCount: number; items: unknown[] }\n  move?: { from: number; to: number }\n}\n\nexport type ControlCommit = {\n  changes: ControlChange[]\n  view: {\n    turnId: string | null\n    version: number | null\n    phase: ActiveTurn['phase'] | null\n    paused: boolean\n    closed: boolean\n    requestId: string | null\n    requestReason: GenerationReason | null\n    sourceGenerationId: string | null\n    responseMessageId: string | null\n  }\n}\n"],"mappings":";;;;;;AA2HA,MAAa,iBAAiB;;;;;AAM9B,MAAa,wBAAwB,8BACnC,IAAI,UACF,0BAA0B,UAAU,yEACtC;;;;;AAMF,MAAa,eACX,OACA,WACW,MAAM,eAAe,SAAS,KAAK,gBAAgB,MAAM,IAAI;;;;;;AAO1E,MAAa,YACX,MACA,SACY;CACZ,IAAI,KAAK,gBAAgB,KAAA,GAAW,OAAO;CAC3C,KAAK,MAAM,QAAQ,MAAM;EACvB,IAAI,KAAK,gBAAgB,KAAK,aAAa,OAAO;EAClD,IAAI,KAAK,UAAU,OAAO;CAC5B;CACA,OAAO;AACT;AAEA,MAAa,6BAA6C;CACxD,cAAc,CAAC;CACf,OAAO;EAAE,QAAQ;EAAO,OAAO,CAAC;CAAE;CAClC,QAAQ;CACR,aAAa;EAAE,QAAQ;EAAO,QAAQ,CAAC;CAAE;AAC3C"}

package/dist/ai-fx.d.ts

@@ -1,4 +1,4 @@
-import { t as Harness } from "./ai-harness-B2suP2Qh.js";
+import { t as Harness } from "./ai-harness-CV6rXbB3.js";
 //#region src/ai-fx.d.ts
 /**
  * The FX harness. Every model call FX makes is one durable step; A2 rebuilds

package/dist/ai-fx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-fx.d.ts","names":[],"sources":["../src/ai-fx.ts"],"mappings":";;;;;;iBAyCgB,MAAM"}
+{"version":3,"file":"ai-fx.d.ts","names":[],"sources":["../src/ai-fx.ts"],"mappings":";;;;;;iBA4CgB,MAAM"}

package/dist/ai-fx.js

@@ -1,5 +1,5 @@
 import { t as boundedCache } from "./bounded-cache-CPHWF-8h.js";
-import { c as pending, d as saveHarness, i as gatewayCredential, l as readHarness, n as deferred, r as defineHarness, t as Divergence } from "./ai-harness-BuLh_EYi.js";
+import { a as gatewaySessionAffinity, d as readHarness, i as gatewayCredential, n as deferred, p as saveHarness, r as defineHarness, s as harnessImages, t as Divergence, u as pending } from "./ai-harness-Clbg5ei7.js";
 import { t as schemaInput } from "./ai-tool-input-DmSqMUQi.js";
 import { asSchema } from "ai";
 //#region src/ai-fx.ts
@@ -19,6 +19,8 @@ function fx() {
 }
 const SNAPSHOT_VERSION = 1;
 const CATALOG_TTL_MS = 36e5;
+/** The Gateway model catalog libfx reads for each new kernel. */
+const CATALOG_PATH = "/coding-agent/v1/models";
 function fail(state, error) {
 	state.failure ??= error;
 	state.fxTurn.cancel();
@@ -111,10 +113,13 @@ async function runStep(step) {
 	};
 	const hostFetch = async (input, init = {}) => {
 		const url = input instanceof Request ? input.url : String(input);
-		if ((init.method ?? "GET").toUpperCase() === "GET") return catalog(url, credential, withAuth(init.headers, credential));
+		const method = (init.method ?? "GET").toUpperCase();
+		if (method === "GET" && new URL(url).pathname === CATALOG_PATH) return catalog(url, credential, withAuth(init.headers, credential));
+		if (method === "GET") return fetch(input, init);
 		const state = turn;
 		if (state.failure) throw state.failure;
-		const compaction = isCompaction(decodeBody(init.body));
+		const body = decodeBody(init.body);
+		const compaction = isCompaction(body);
 		const recorded = state.plan.calls[state.next];
 		if (recorded !== void 0) {
 			if (recorded.kind === "compaction" !== compaction) fail(state, diverged(`request ${state.next} is not a ${recorded.kind}`));
@@ -138,13 +143,23 @@ async function runStep(step) {
 			return pending(init.signal);
 		}
 		state.live = true;
-		return live(state, url, init, compaction);
+		return live(state, url, {
+			...init,
+			body
+		}, compaction);
 	};
+	const affinity = gatewaySessionAffinity({
+		agentName: step.agentName,
+		sessionId: step.sessionId
+	});
 	let compactions = 0;
 	const live = async (state, url, init, compaction) => {
+		const headers = withAuth(init.headers, credential);
+		headers.set("x-session-affinity", affinity);
 		const response = await fetch(url, {
 			...init,
-			headers: withAuth(init.headers, credential),
+			body: withGatewayCaching(init.body),
+			headers,
 			signal: network
 		});
 		if (init.signal?.aborted) {
@@ -208,7 +223,7 @@ async function runStep(step) {
 		}
 		return fail(state, diverged(`no recorded result for ${toolName}`));
 	});
-	let turns = read.turns.map(turnPlan);
+	const plans = (turns) => Promise.all(turns.map((recorded) => turnPlan(recorded, step.signal)));
 	let results = read.results;
 	let controller;
 	let closed = false;
@@ -239,11 +254,10 @@ async function runStep(step) {
 						} catch (error) {
 							if (read.saved === void 0) throw error;
 							read = await replayAll();
-							turns = read.turns.map(turnPlan);
 							results = read.results;
 							agent = await create(void 0);
 						}
-						await run(streamController, turns);
+						await run(streamController, await plans(read.turns));
 						closed = true;
 						streamController.close();
 					} catch (error) {
@@ -266,24 +280,41 @@ async function runStep(step) {
 		completion: () => completion
 	};
 }
-function turnPlan(turn) {
+async function turnPlan(turn, signal) {
 	const calls = [];
 	const steers = /* @__PURE__ */ new Map();
-	const steer = (at, texts) => {
-		if (texts !== void 0) steers.set(Math.max(0, at), texts);
+	const steer = (at, inputs) => {
+		if (inputs !== void 0) steers.set(Math.max(0, at), inputs.map(steerText));
 	};
 	steer(0, turn.generations.length === 0 ? turn.steers.get(0) : void 0);
 	turn.generations.forEach((generation, index) => {
 		calls.push(...recordedCalls(generation.chunks, generation.completed));
 		steer(calls.length - 1, turn.steers.get(index));
 	});
+	const images = await harnessImages({
+		harness: "fx()",
+		input: turn.prompt,
+		signal
+	});
 	return {
-		prompt: turn.prompt,
+		prompt: images.length === 0 ? turn.prompt.text : [...images.map((image) => ({
+			type: "image",
+			data: image.data,
+			mimeType: image.mediaType
+		})), ...turn.prompt.text === "" ? [] : [{
+			type: "text",
+			text: turn.prompt.text
+		}]],
 		calls,
 		steers,
 		end: turn.end
 	};
 }
+/** libfx steers with text alone, so a steer's files fail the step. */
+function steerText(input) {
+	if (input.files.length > 0) throw new Error("fx() steers with text only: send files in a message of their own");
+	return input.text;
+}
 /** A completed generation's model calls: its compactions, then its step. */
 function recordedCalls(chunks, completed) {
 	const calls = [];
@@ -569,6 +600,25 @@ async function loadLibfx() {
 		throw new Error("fx() needs the libfx package: install libfx", { cause: error });
 	}
 }
+/**
+* A model request with Gateway's automatic caching, as the AI SDK harness
+* asks for it; options the request already has take precedence. Every other
+* byte stays as the kernel wrote it, a tool input's spacing included.
+*/
+function withGatewayCaching(body) {
+	const options = JSON.parse(body).providerOptions;
+	if (options === void 0) return body.replace(/^\{/, "{\"providerOptions\":{\"gateway\":{\"caching\":\"auto\"}},");
+	const own = `"providerOptions":${JSON.stringify(options)}}`;
+	if (!body.endsWith(own)) return body;
+	const merged = {
+		...options,
+		gateway: {
+			caching: "auto",
+			...options["gateway"]
+		}
+	};
+	return `${body.slice(0, -own.length)}"providerOptions":${JSON.stringify(merged)}}`;
+}
 function withAuth(headers, credential) {
 	const result = new Headers(headers);
 	result.set("ai-gateway-auth-method", credential.method);
@@ -585,7 +635,7 @@ function kernelModel(step) {
 	};
 }
 async function kernelTools(tools, execute) {
-	return Promise.all(Object.entries(tools).filter(([, tool]) => tool.type !== "provider").map(async ([toolName, tool]) => ({
+	return Promise.all(Object.entries(tools).map(async ([toolName, tool]) => ({
 		name: toolName,
 		description: typeof tool.description === "string" ? tool.description : toolName,
 		inputSchema: await asSchema(tool.inputSchema).jsonSchema,