experimental-a2 0.16.1 → 0.17.0

package/dist/ai-client.d.ts

@@ -0,0 +1,27 @@
+import { s as CreateClientOptions, t as A2Client } from "./client-qRnRUzBS.js";
+import { a as AI_STATE_REDUCER, i as AIState, r as AIMessageOf, t as AIEventDefs } from "./ai-vpGtcaCB.js";
+//#region src/ai-client.d.ts
+/**
+ * The structural shape of `typeof` an `agent({ name })` server: one whose
+ * state the built-in reducer folds. Agents built from an extended contract
+ * use `createClient({ contract })` instead.
+ */
+type AnyAgent = {
+  readonly contract: {
+    readonly events: object;
+    readonly reducer: {
+      readonly name: typeof AI_STATE_REDUCER;
+    };
+  };
+};
+type AgentMessage<A extends AnyAgent> = AIMessageOf<A["contract"]["events"]>;
+type AgentClient<A extends AnyAgent = AnyAgent> = A2Client<AIEventDefs<AgentMessage<A>>, AIState<AgentMessage<A>>>;
+type CreateAgentClientOptions = Omit<CreateClientOptions<AIEventDefs, AIState>, "contract">;
+/**
+ * A client for the built-in AI protocol. Agents built from a shared
+ * `agentContract()` use `createClient({ contract })` instead.
+ */
+declare function createAgentClient<A extends AnyAgent = AnyAgent>(options: CreateAgentClientOptions): AgentClient<A>;
+//#endregion
+export { AgentClient, AgentMessage, AnyAgent, CreateAgentClientOptions, createAgentClient };
+//# sourceMappingURL=ai-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai-client.d.ts","names":[],"sources":["../src/ai-client.ts"],"mappings":";;;;;;;;KA8BY;WACD;aACE;aACA;eAAoB,aAAa;;;;KAIlC,aAAa,UAAU,YAAY,YAC7C;KAGU,YAAY,UAAU,WAAW,YAAY,SACvD,YAAY,aAAa,KACzB,QAAQ,aAAa;KAGX,2BAA2B,KACrC,oBAAoB,aAAa;;;;;iBAUnB,kBAAkB,UAAU,WAAW,UACrD,SAAS,2BACR,YAAY"}

package/dist/ai-client.js

@@ -0,0 +1,29 @@
+import { t as createClient } from "./client-COaiaDub.js";
+import { n as agentContract } from "./ai-UrWfKeuv.js";
+//#region src/ai-client.ts
+/**
+* experimental-a2/ai/client — a client for an `agent()` route that needs no
+* contract: the AI protocol and its `AIState` reducer are library code, and
+* the agent's types arrive through a type-only `typeof` import.
+*
+* ```ts
+* import type { assistant } from '@/server/assistant' // erased at build
+* const client = createAgentClient<typeof assistant>({ api: '/api/agent' })
+* await client.session(id).push(...inputs.message(message))
+* ```
+*/
+const protocol = agentContract({ name: "a2.ai" });
+/**
+* A client for the built-in AI protocol. Agents built from a shared
+* `agentContract()` use `createClient({ contract })` instead.
+*/
+function createAgentClient(options) {
+	return createClient({
+		...options,
+		contract: protocol
+	});
+}
+//#endregion
+export { createAgentClient };
+
+//# sourceMappingURL=ai-client.js.map

package/dist/ai-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-client.js","names":[],"sources":["../src/ai-client.ts"],"sourcesContent":["/**\n * experimental-a2/ai/client — a client for an `agent()` route that needs no\n * contract: the AI protocol and its `AIState` reducer are library code, and\n * the agent's types arrive through a type-only `typeof` import.\n *\n * ```ts\n * import type { assistant } from '@/server/assistant' // erased at build\n * const client = createAgentClient<typeof assistant>({ api: '/api/agent' })\n * await client.session(id).push(...inputs.message(message))\n * ```\n */\n\nimport {\n  agentContract,\n  type AI_STATE_REDUCER,\n  type AIEventDefs,\n  type AIMessageOf,\n  type AIState,\n} from './ai.ts'\nimport {\n  createClient,\n  type A2Client,\n  type CreateClientOptions,\n} from './client.ts'\n\n/**\n * The structural shape of `typeof` an `agent({ name })` server: one whose\n * state the built-in reducer folds. Agents built from an extended contract\n * use `createClient({ contract })` instead.\n */\nexport type AnyAgent = {\n  readonly contract: {\n    readonly events: object\n    readonly reducer: { readonly name: typeof AI_STATE_REDUCER }\n  }\n}\n\nexport type AgentMessage<A extends AnyAgent> = AIMessageOf<\n  A['contract']['events']\n>\n\nexport type AgentClient<A extends AnyAgent = AnyAgent> = A2Client<\n  AIEventDefs<AgentMessage<A>>,\n  AIState<AgentMessage<A>>\n>\n\nexport type CreateAgentClientOptions = Omit<\n  CreateClientOptions<AIEventDefs, AIState>,\n  'contract'\n>\n\nconst protocol = agentContract({ name: 'a2.ai' })\n\n/**\n * A client for the built-in AI protocol. Agents built from a shared\n * `agentContract()` use `createClient({ contract })` instead.\n */\nexport function createAgentClient<A extends AnyAgent = AnyAgent>(\n  options: CreateAgentClientOptions,\n): AgentClient<A> {\n  return createClient({ ...options, contract: protocol }) as AgentClient<A>\n}\n"],"mappings":";;;;;;;;;;;;;;AAmDA,MAAM,WAAW,cAAc,EAAE,MAAM,QAAQ,CAAC;;;;;AAMhD,SAAgB,kBACd,SACgB;CAChB,OAAO,aAAa;EAAE,GAAG;EAAS,UAAU;CAAS,CAAC;AACxD"}

package/dist/ai-react.d.ts

@@ -0,0 +1,96 @@
+import { s as Contract, t as Reducer, u as EventDefs } from "./reducer-BYu6DT7h.js";
+import { t as InitialSnapshot } from "./initial-snapshot-BrLso5x_.js";
+import { t as A2Client, u as PushResult } from "./client-qRnRUzBS.js";
+import { B as PendingApproval, V as PendingInput, d as AgentStatus, i as AIState, t as AIEventDefs } from "./ai-vpGtcaCB.js";
+import { AgentClient, AgentMessage, AnyAgent } from "./ai-client.js";
+import { c as UseSessionResult } from "./react-BbJ-g6Uu.js";
+import { JSONValue, UIMessage } from "ai";
+//#region src/ai-agent-actions.d.ts
+/** The input message type of a state: what its inbox holds. */
+type InputOf<S extends AIState> = S["inbox"]["items"][number]["message"];
+/** What the UI shows while nothing new is visible in the response. */
+type AgentIndicator = "starting" | "thinking" | "compacting" | null;
+/**
+ * Every action resolves like `push()`: to the persisted command events, whose
+ * `id` is the `commandId` of its `ai.control.decided` receipt. An action with
+ * nothing to address (Stop with no active turn) resolves to no events.
+ */
+type AgentActions<D extends EventDefs, M extends UIMessage> = {
+  /** Queue a user message. A string becomes one text part. */
+  sendMessage: (message: string | M, options?: {
+    generate?: boolean;
+  }) => PushResult<D>;
+  /** Hand off after the active turn's current step, or send when idle. */
+  steer: (message: string | M) => PushResult<D>;
+  /** Stop the active turn at the frontier this render showed. */
+  stop: () => PushResult<D>;
+  approve: (approval: PendingApproval) => PushResult<D>;
+  deny: (approval: PendingApproval, options?: {
+    reason?: string;
+  }) => PushResult<D>;
+  respond: (input: PendingInput, value: JSONValue) => PushResult<D>;
+  /** Rerun the failed model step of the active turn. */
+  retry: () => PushResult<D>;
+  pause: (options: {
+    when: "now" | "after-turn";
+  }) => PushResult<D>;
+  resume: () => PushResult<D>;
+  queue: {
+    edit: (message: M) => PushResult<D>;
+    move: (options: {
+      inputId: string;
+      beforeId: string | null;
+    }) => PushResult<D>;
+    remove: (inputId: string) => PushResult<D>;
+    /** Prioritize a queued input and hand off after the current step. */
+    sendNow: (inputId: string) => PushResult<D>;
+  };
+};
+type UseAgentResult<D extends EventDefs, S extends AIState> = UseSessionResult<D, S> & AgentActions<D, InputOf<S>> & {
+  messages: S["messages"];
+  status: AgentStatus;
+  indicator: AgentIndicator;
+};
+//#endregion
+//#region src/ai-react.d.ts
+type UseAgentOptions<A extends AnyAgent> = {
+  /** The session id. */
+  id: string;
+  /** The server-rendered `assistant.session(id).state()`. */
+  initial?: InitialSnapshot<AIState<AgentMessage<A>>>;
+  participant?: string;
+} & ({
+  /** The route serving the agent's `fetch`; its client is shared. */
+  api: string;
+  contract?: never;
+} | {
+  client: AgentClient<A>;
+});
+/**
+ * Use a session of an agent served from a shared `agentContract()`, folding
+ * its application state in the browser. The contract is a real import here.
+ */
+type UseContractAgentOptions<D extends EventDefs, S extends AIState> = {
+  /** The session id. */
+  id: string;
+  /** The server-rendered `agent.session(id).state()`. */
+  initial?: InitialSnapshot<S>;
+  participant?: string;
+} & ({
+  /** The route serving the agent's `fetch`; its client is shared. */
+  api: string;
+  contract: Contract<D, Record<never, never>, Reducer<D, S>>;
+} | {
+  /** `createClient({ contract, api })`, shared with pushes outside React. */
+  client: A2Client<D, S>;
+});
+/** Use a session of an agent served from a shared `agentContract()`. */
+declare function useAgent<D extends EventDefs, S extends AIState>(options: UseContractAgentOptions<D, S>): UseAgentResult<D, S>;
+/**
+ * Use one agent session. Pass `typeof` the server's `agent()` for its
+ * message types; the import is type-only and erased.
+ */
+declare function useAgent<A extends AnyAgent = AnyAgent>(options: UseAgentOptions<A>): UseAgentResult<AIEventDefs<AgentMessage<A>>, AIState<AgentMessage<A>>>;
+//#endregion
+export { type AgentActions, type AgentClient, type AgentIndicator, type AgentMessage, type AnyAgent, UseAgentOptions, type UseAgentResult, UseContractAgentOptions, useAgent };
+//# sourceMappingURL=ai-react.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai-react.d.ts","names":[],"sources":["../src/ai-agent-actions.ts","../src/ai-react.ts"],"mappings":";;;;;;;;;KAcK,QAAQ,UAAU,WAAW;;KAGtB;;;;;;KAOA,aAAa,UAAU,WAAW,UAAU;;EAEtD,cACE,kBAAkB,GAClB;IAAY;QACT,WAAW;;EAEhB,QAAQ,kBAAkB,MAAM,WAAW;;EAE3C,YAAY,WAAW;EACvB,UAAU,UAAU,oBAAoB,WAAW;EACnD,OACE,UAAU,iBACV;IAAY;QACT,WAAW;EAChB,UAAU,OAAO,cAAc,OAAO,cAAc,WAAW;;EAE/D,aAAa,WAAW;EACxB,QAAQ;IAAW;QAAiC,WAAW;EAC/D,cAAc,WAAW;EACzB;IACE,OAAO,SAAS,MAAM,WAAW;IACjC,OAAO;MACL;MACA;UACI,WAAW;IACjB,SAAS,oBAAoB,WAAW;;IAExC,UAAU,oBAAoB,WAAW;;;KAIjC,eACV,UAAU,WACV,UAAU,WACR,iBAAiB,GAAG,KACtB,aAAa,GAAG,QAAQ;EACtB,UAAU;EACV,QAAQ;EACR,WAAW;;;;KClCH,gBAAgB,UAAU;;EAEpC;;EAEA,UAAU,gBAAgB,QAAQ,aAAa;EAC/C;;;EAII;EACA;;EAEA,QAAQ,YAAY;;;;;;KAOd,wBAAwB,UAAU,WAAW,UAAU;;EAEjE;;EAEA,UAAU,gBAAgB;EAC1B;;;EAII;EACA,UAAU,SAAS,GAAG,sBAAsB,QAAQ,GAAG;;;EAIvD,QAAQ,SAAS,GAAG;;;iBA+CV,SAAS,UAAU,WAAW,UAAU,SACtD,SAAS,wBAAwB,GAAG,KACnC,eAAe,GAAG;;;;;iBAKL,SAAS,UAAU,WAAW,UAC5C,SAAS,gBAAgB,KACxB,eAAe,YAAY,aAAa,KAAK,QAAQ,aAAa"}

package/dist/ai-react.js

@@ -0,0 +1,142 @@
+"use client";
+import { t as createClient } from "./client-COaiaDub.js";
+import { useSession } from "./react.js";
+import { s as inputs, x as isCompactionPart } from "./ai-UrWfKeuv.js";
+import { createAgentClient } from "./ai-client.js";
+//#region src/ai-agent-actions.ts
+const visible = (part) => part.type === "text" ? part.text.length > 0 : part.type !== "reasoning" && part.type !== "step-start" && !isCompactionPart(part);
+const indicatorOf = (state) => {
+	if (state.starting) return "starting";
+	if (state.status !== "generating") return null;
+	if (state.compaction?.status === "running") return "compacting";
+	const responseId = state.activeGeneration?.responseMessageId ?? state.activeResponseMessageId ?? state.activeProjection?.responseMessageId;
+	const response = responseId === void 0 || responseId === null ? void 0 : state.messages.findLast((message) => message.id === responseId);
+	if (response === void 0 || state.activeGeneration === null && state.activeResponseMessageId !== null) return "thinking";
+	const projection = state.activeProjection;
+	const start = state.activeGeneration !== null && projection?.generationId === state.activeGeneration.generationId && projection.base !== void 0 ? projection.base.partCount : response.parts.findLastIndex((part) => part.type === "step-start") + 1;
+	return response.parts.slice(start).some(visible) ? null : "thinking";
+};
+const userMessage = (message) => typeof message === "string" ? {
+	id: crypto.randomUUID(),
+	role: "user",
+	parts: [{
+		type: "text",
+		text: message
+	}]
+} : message;
+function withAgentActions(session) {
+	const { state, index, push } = session;
+	const send = (events) => events.length === 0 ? Object.assign(Promise.resolve([]), { confirmed: Promise.resolve([]) }) : push(...events);
+	const active = state.active;
+	const lastSeenIndex = index;
+	const actions = {
+		sendMessage: (message, options) => send(inputs.message(userMessage(message), options)),
+		steer: (message) => send(active === null ? inputs.message(userMessage(message)) : inputs.steer({
+			turnId: active.turnId,
+			message: userMessage(message),
+			lastSeenIndex
+		})),
+		stop: () => send(active === null ? [] : inputs.stop({
+			turnId: active.turnId,
+			lastSeenIndex
+		})),
+		approve: (approval) => send(inputs.approval({
+			...approvalOwner(approval),
+			approved: true
+		})),
+		deny: (approval, options) => send(inputs.approval({
+			...approvalOwner(approval),
+			approved: false,
+			...options?.reason === void 0 ? {} : { reason: options.reason }
+		})),
+		respond: (input, value) => send(inputs.input({
+			requestId: input.requestId,
+			messageId: input.messageId,
+			generationId: input.generationId,
+			inputId: input.inputId,
+			name: input.name,
+			value
+		})),
+		retry: () => {
+			const responseMessageId = state.activeProjection?.responseMessageId;
+			return send(state.status !== "failed" || active === null || responseMessageId === void 0 ? [] : inputs.retry({
+				messageId: active.input.id,
+				responseMessageId,
+				retryId: crypto.randomUUID()
+			}));
+		},
+		pause: (options) => send(inputs.pause(options)),
+		resume: () => send(inputs.resume()),
+		queue: {
+			edit: (message) => send(inputs.queue.edit({ message })),
+			move: (options) => send(inputs.queue.move(options)),
+			remove: (inputId) => send(inputs.queue.remove({ inputId })),
+			sendNow: (inputId) => send(inputs.queue.sendNow({
+				inputId,
+				turnId: active?.turnId ?? null,
+				lastSeenIndex
+			}))
+		}
+	};
+	return {
+		...session,
+		...actions,
+		messages: state.messages,
+		status: state.status,
+		indicator: indicatorOf(state)
+	};
+}
+const approvalOwner = (approval) => ({
+	requestId: approval.requestId,
+	messageId: approval.messageId,
+	generationId: approval.generationId,
+	approvalId: approval.approvalId
+});
+//#endregion
+//#region src/ai-react.ts
+const clients = /* @__PURE__ */ new Map();
+const contractClients = /* @__PURE__ */ new WeakMap();
+/**
+* One client per route for the page's lifetime; its idle sessions expire
+* after the default `gcTime`. It reads `globalThis.fetch` per request, so
+* instrumentation installed later still applies.
+*/
+const clientFor = (api) => {
+	let client = clients.get(api);
+	if (client === void 0) {
+		client = createAgentClient({
+			api,
+			fetch: (input, init) => globalThis.fetch(input, init)
+		});
+		clients.set(api, client);
+	}
+	return client;
+};
+/** One client per contract and route, like `clientFor`. */
+const contractClientFor = (contract, api) => {
+	let byApi = contractClients.get(contract);
+	if (byApi === void 0) {
+		byApi = /* @__PURE__ */ new Map();
+		contractClients.set(contract, byApi);
+	}
+	let client = byApi.get(api);
+	if (client === void 0) {
+		client = createClient({
+			contract,
+			api,
+			fetch: (input, init) => globalThis.fetch(input, init)
+		});
+		byApi.set(api, client);
+	}
+	return client;
+};
+function useAgent(options) {
+	return withAgentActions(useSession("client" in options ? options.client : options.contract !== void 0 ? contractClientFor(options.contract, options.api) : clientFor(options.api), options.id, {
+		...options.initial === void 0 ? {} : { initial: options.initial },
+		...options.participant === void 0 ? {} : { participant: options.participant }
+	}));
+}
+//#endregion
+export { useAgent };
+
+//# sourceMappingURL=ai-react.js.map

package/dist/ai-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-react.js","names":[],"sources":["../src/ai-agent-actions.ts","../src/ai-react.ts"],"sourcesContent":["import type { JSONValue, UIMessage } from 'ai'\nimport {\n  inputs,\n  isCompactionPart,\n  type AIState,\n  type AgentStatus,\n  type PendingApproval,\n  type PendingInput,\n} from './ai.ts'\nimport type { AppendInput, EventDefs } from './contract.ts'\nimport type { PushResult } from './client.ts'\nimport type { UseSessionResult } from './react.ts'\n\n/** The input message type of a state: what its inbox holds. */\ntype InputOf<S extends AIState> = S['inbox']['items'][number]['message']\n\n/** What the UI shows while nothing new is visible in the response. */\nexport type AgentIndicator = 'starting' | 'thinking' | 'compacting' | null\n\n/**\n * Every action resolves like `push()`: to the persisted command events, whose\n * `id` is the `commandId` of its `ai.control.decided` receipt. An action with\n * nothing to address (Stop with no active turn) resolves to no events.\n */\nexport type AgentActions<D extends EventDefs, M extends UIMessage> = {\n  /** Queue a user message. A string becomes one text part. */\n  sendMessage: (\n    message: string | M,\n    options?: { generate?: boolean },\n  ) => PushResult<D>\n  /** Hand off after the active turn's current step, or send when idle. */\n  steer: (message: string | M) => PushResult<D>\n  /** Stop the active turn at the frontier this render showed. */\n  stop: () => PushResult<D>\n  approve: (approval: PendingApproval) => PushResult<D>\n  deny: (\n    approval: PendingApproval,\n    options?: { reason?: string },\n  ) => PushResult<D>\n  respond: (input: PendingInput, value: JSONValue) => PushResult<D>\n  /** Rerun the failed model step of the active turn. */\n  retry: () => PushResult<D>\n  pause: (options: { when: 'now' | 'after-turn' }) => PushResult<D>\n  resume: () => PushResult<D>\n  queue: {\n    edit: (message: M) => PushResult<D>\n    move: (options: {\n      inputId: string\n      beforeId: string | null\n    }) => PushResult<D>\n    remove: (inputId: string) => PushResult<D>\n    /** Prioritize a queued input and hand off after the current step. */\n    sendNow: (inputId: string) => PushResult<D>\n  }\n}\n\nexport type UseAgentResult<\n  D extends EventDefs,\n  S extends AIState,\n> = UseSessionResult<D, S> &\n  AgentActions<D, InputOf<S>> & {\n    messages: S['messages']\n    status: AgentStatus\n    indicator: AgentIndicator\n  }\n\nconst visible = (part: UIMessage['parts'][number]): boolean =>\n  part.type === 'text'\n    ? part.text.length > 0\n    : part.type !== 'reasoning' &&\n      part.type !== 'step-start' &&\n      !isCompactionPart(part)\n\nconst indicatorOf = (state: AIState): AgentIndicator => {\n  if (state.starting) return 'starting'\n  if (state.status !== 'generating') return null\n  if (state.compaction?.status === 'running') return 'compacting'\n  const responseId =\n    state.activeGeneration?.responseMessageId ??\n    state.activeResponseMessageId ??\n    state.activeProjection?.responseMessageId\n  const response =\n    responseId === undefined || responseId === null\n      ? undefined\n      : state.messages.findLast((message) => message.id === responseId)\n  // A requested step that has not started has produced nothing yet.\n  if (\n    response === undefined ||\n    (state.activeGeneration === null && state.activeResponseMessageId !== null)\n  )\n    return 'thinking'\n  const projection = state.activeProjection\n  // A started step's own output begins after its base; before its first chunk\n  // the previous step's parts are not this step's progress.\n  const start =\n    state.activeGeneration !== null &&\n    projection?.generationId === state.activeGeneration.generationId &&\n    projection.base !== undefined\n      ? projection.base.partCount\n      : response.parts.findLastIndex((part) => part.type === 'step-start') + 1\n  return response.parts.slice(start).some(visible) ? null : 'thinking'\n}\n\nconst userMessage = <M extends UIMessage>(message: string | M): M =>\n  typeof message === 'string'\n    ? ({\n        id: crypto.randomUUID(),\n        role: 'user',\n        parts: [{ type: 'text', text: message }],\n      } as UIMessage as M)\n    : message\n\nexport function withAgentActions<D extends EventDefs, S extends AIState>(\n  session: UseSessionResult<D, S>,\n): UseAgentResult<D, S> {\n  type M = InputOf<S>\n  const { state, index, push } = session\n  const send = (\n    events: { type: 'ai.control.requested'; payload: unknown }[],\n  ): PushResult<D> =>\n    events.length === 0\n      ? Object.assign(Promise.resolve([]), {\n          confirmed: Promise.resolve([]),\n        })\n      : push(...(events as AppendInput<D>[]))\n  const active = state.active\n  // `index` is this render's frontier: Stop freezes the response the user\n  // saw, not whatever arrived before the click was handled.\n  const lastSeenIndex = index\n  const actions: AgentActions<D, M> = {\n    sendMessage: (message, options) =>\n      send(inputs.message(userMessage(message), options)),\n    steer: (message) =>\n      send(\n        active === null\n          ? inputs.message(userMessage(message))\n          : inputs.steer({\n              turnId: active.turnId,\n              message: userMessage(message),\n              lastSeenIndex,\n            }),\n      ),\n    stop: () =>\n      send(\n        active === null\n          ? []\n          : inputs.stop({ turnId: active.turnId, lastSeenIndex }),\n      ),\n    approve: (approval) =>\n      send(inputs.approval({ ...approvalOwner(approval), approved: true })),\n    deny: (approval, options) =>\n      send(\n        inputs.approval({\n          ...approvalOwner(approval),\n          approved: false,\n          ...(options?.reason === undefined ? {} : { reason: options.reason }),\n        }),\n      ),\n    respond: (input, value) =>\n      send(\n        inputs.input({\n          requestId: input.requestId,\n          messageId: input.messageId,\n          generationId: input.generationId,\n          inputId: input.inputId,\n          name: input.name,\n          value,\n        }),\n      ),\n    retry: () => {\n      const responseMessageId = state.activeProjection?.responseMessageId\n      return send(\n        state.status !== 'failed' ||\n          active === null ||\n          responseMessageId === undefined\n          ? []\n          : inputs.retry({\n              messageId: active.input.id,\n              responseMessageId,\n              retryId: crypto.randomUUID(),\n            }),\n      )\n    },\n    pause: (options) => send(inputs.pause(options)),\n    resume: () => send(inputs.resume()),\n    queue: {\n      edit: (message) => send(inputs.queue.edit({ message })),\n      move: (options) => send(inputs.queue.move(options)),\n      remove: (inputId) => send(inputs.queue.remove({ inputId })),\n      sendNow: (inputId) =>\n        send(\n          inputs.queue.sendNow({\n            inputId,\n            turnId: active?.turnId ?? null,\n            lastSeenIndex,\n          }),\n        ),\n    },\n  }\n  return {\n    ...session,\n    ...actions,\n    messages: state.messages,\n    status: state.status,\n    indicator: indicatorOf(state as AIState),\n  }\n}\n\nconst approvalOwner = (\n  approval: PendingApproval,\n): Pick<\n  PendingApproval,\n  'requestId' | 'messageId' | 'generationId' | 'approvalId'\n> => ({\n  requestId: approval.requestId,\n  messageId: approval.messageId,\n  generationId: approval.generationId,\n  approvalId: approval.approvalId,\n})\n","'use client'\n/**\n * experimental-a2/ai/react — one hook for an agent session: its live\n * optimistic `AIState`, and actions that fill in protocol identities.\n *\n * ```tsx\n * import type { assistant } from '@/server/assistant' // erased at build\n * const { messages, indicator, sendMessage, stop } =\n *   useAgent<typeof assistant>({ api: '/api/agent', id, initial })\n * ```\n *\n * With a shared `agentContract()`, pass it as `contract` to fold its\n * application state in the browser too.\n */\n\nimport type { AIEventDefs, AIState } from './ai.ts'\nimport { withAgentActions, type UseAgentResult } from './ai-agent-actions.ts'\nimport {\n  createAgentClient,\n  type AgentClient,\n  type AgentMessage,\n  type AnyAgent,\n} from './ai-client.ts'\nimport type { Contract, EventDefs } from './contract.ts'\nimport type { InitialSnapshot } from './initial-snapshot.ts'\nimport { createClient, type A2Client } from './client.ts'\nimport type { Reducer } from './reducer.ts'\nimport { useSession, type UseSessionResult } from './react.ts'\n\nexport type UseAgentOptions<A extends AnyAgent> = {\n  /** The session id. */\n  id: string\n  /** The server-rendered `assistant.session(id).state()`. */\n  initial?: InitialSnapshot<AIState<AgentMessage<A>>>\n  participant?: string\n} & (\n  | {\n      /** The route serving the agent's `fetch`; its client is shared. */\n      api: string\n      contract?: never\n    }\n  | { client: AgentClient<A> }\n)\n\n/**\n * Use a session of an agent served from a shared `agentContract()`, folding\n * its application state in the browser. The contract is a real import here.\n */\nexport type UseContractAgentOptions<D extends EventDefs, S extends AIState> = {\n  /** The session id. */\n  id: string\n  /** The server-rendered `agent.session(id).state()`. */\n  initial?: InitialSnapshot<S>\n  participant?: string\n} & (\n  | {\n      /** The route serving the agent's `fetch`; its client is shared. */\n      api: string\n      contract: Contract<D, Record<never, never>, Reducer<D, S>>\n    }\n  | {\n      /** `createClient({ contract, api })`, shared with pushes outside React. */\n      client: A2Client<D, S>\n    }\n)\n\nconst clients = new Map<string, AgentClient>()\nconst contractClients = new WeakMap<object, Map<string, object>>()\n\n/**\n * One client per route for the page's lifetime; its idle sessions expire\n * after the default `gcTime`. It reads `globalThis.fetch` per request, so\n * instrumentation installed later still applies.\n */\nconst clientFor = (api: string): AgentClient => {\n  let client = clients.get(api)\n  if (client === undefined) {\n    client = createAgentClient({\n      api,\n      fetch: (input, init) => globalThis.fetch(input, init),\n    })\n    clients.set(api, client)\n  }\n  return client\n}\n\n/** One client per contract and route, like `clientFor`. */\nconst contractClientFor = <D extends EventDefs, S>(\n  contract: Contract<D, Record<never, never>, Reducer<D, S>>,\n  api: string,\n): A2Client<D, S> => {\n  let byApi = contractClients.get(contract)\n  if (byApi === undefined) {\n    byApi = new Map()\n    contractClients.set(contract, byApi)\n  }\n  let client = byApi.get(api) as A2Client<D, S> | undefined\n  if (client === undefined) {\n    client = createClient({\n      contract,\n      api,\n      fetch: (input, init) => globalThis.fetch(input, init),\n    })\n    byApi.set(api, client)\n  }\n  return client\n}\n\n/** Use a session of an agent served from a shared `agentContract()`. */\nexport function useAgent<D extends EventDefs, S extends AIState>(\n  options: UseContractAgentOptions<D, S>,\n): UseAgentResult<D, S>\n/**\n * Use one agent session. Pass `typeof` the server's `agent()` for its\n * message types; the import is type-only and erased.\n */\nexport function useAgent<A extends AnyAgent = AnyAgent>(\n  options: UseAgentOptions<A>,\n): UseAgentResult<AIEventDefs<AgentMessage<A>>, AIState<AgentMessage<A>>>\nexport function useAgent(\n  options:\n    UseAgentOptions<AnyAgent> | UseContractAgentOptions<AIEventDefs, AIState>,\n): object {\n  const session: UseSessionResult<AIEventDefs, AIState> = useSession(\n    'client' in options\n      ? options.client\n      : options.contract !== undefined\n        ? contractClientFor(options.contract, options.api)\n        : clientFor(options.api),\n    options.id,\n    {\n      ...(options.initial === undefined ? {} : { initial: options.initial }),\n      ...(options.participant === undefined\n        ? {}\n        : { participant: options.participant }),\n    },\n  )\n  return withAgentActions(session)\n}\n\nexport type { AgentClient, AgentMessage, AnyAgent }\nexport type {\n  AgentActions,\n  AgentIndicator,\n  UseAgentResult,\n} from './ai-agent-actions.ts'\n"],"mappings":"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"}

package/dist/ai-server.browser.js

@@ -1,6 +1,6 @@
 //#region src/ai-server.browser.ts
-/** experimental-a2/ai/server is server-only; agent definitions live in experimental-a2/ai. */
-throw new Error("experimental-a2/ai/server is server-only — a client bundle imported it. Import agent from experimental-a2/ai in browser code instead.");
+/** experimental-a2/ai/server is server-only; browsers use experimental-a2/ai/react or /ai/client. */
+throw new Error("experimental-a2/ai/server is server-only — a client bundle imported it. Import its agent's type with `import type`, and use experimental-a2/ai/react or experimental-a2/ai/client in browser code.");
 //#endregion
 
 //# sourceMappingURL=ai-server.browser.js.map

package/dist/ai-server.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-server.browser.js","names":[],"sources":["../src/ai-server.browser.ts"],"sourcesContent":["/** experimental-a2/ai/server is server-only; agent definitions live in experimental-a2/ai. */\nthrow new Error(\n  'experimental-a2/ai/server is server-only — a client bundle imported it. Import agent from experimental-a2/ai in browser code instead.',\n)\nexport {}\n"],"mappings":";;AACA,MAAM,IAAI,MACR,uIACF"}
+{"version":3,"file":"ai-server.browser.js","names":[],"sources":["../src/ai-server.browser.ts"],"sourcesContent":["/** experimental-a2/ai/server is server-only; browsers use experimental-a2/ai/react or /ai/client. */\nthrow new Error(\n  \"experimental-a2/ai/server is server-only — a client bundle imported it. Import its agent's type with `import type`, and use experimental-a2/ai/react or experimental-a2/ai/client in browser code.\",\n)\nexport {}\n"],"mappings":";;AACA,MAAM,IAAI,MACR,oMACF"}

package/dist/ai-server.d.ts

@@ -1,6 +1,6 @@
-import { a as ContractEvent, s as EventDefs } from "./reducer-otzHjuJj.js";
-import { n as A2Server, p as ServerOptions, s as HandlerContext } from "./server-DbD7IJVK.js";
-import { l as AgentToolContext, o as AgentDefinition, t as AIEventDefs, u as AgentToolEventDefs } from "./ai-CrEf6p_W.js";
+import { c as ContractEvent, s as Contract, t as Reducer, u as EventDefs, v as StandardSchemaV1 } from "./reducer-BYu6DT7h.js";
+import { n as A2Server, p as ServerOptions, s as HandlerContext } from "./server-CGM8WzRG.js";
+import { H as ReasoningLevel, a as AI_STATE_REDUCER, f as AgentToolContext, i as AIState, p as AgentToolEventDefs, r as AIMessageOf, t as AIEventDefs } from "./ai-vpGtcaCB.js";
 import { Instructions, LanguageModel, ModelMessage, TextStreamPart, ToolSet, ToolSet as ToolSet$1, UIMessage, UIMessageChunk, streamText } from "ai";
 //#region src/ai-sdk-step.d.ts
 type StreamTextOptions<T extends ToolSet$1> = Parameters<typeof streamText<T>>[0];
@@ -37,39 +37,46 @@ type AISDKStepSettings<T extends ToolSet$1> = Partial<Omit<StreamTextOptions<T>,
   experimental_transform?: ModelPhaseTransform<T> | Array<ModelPhaseTransform<T>>;
 };
 //#endregion
-//#region src/ai-server.d.ts
-type AgentGenerateContext<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet> = {
-  request: ContractEvent<D, "ai.generation.requested">;
-  requestId: string;
+//#region src/ai-agent.d.ts
+type AgentGenerateContext<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet, X extends object = Record<never, never>> = AgentResolverContext<M, D, X> & {
   generationId: string;
-  responseMessageId: string;
-  messages: M[];
   modelMessages: ModelMessage[];
-  session: Pick<HandlerContext<D>["session"], "state">;
-  signal: AbortSignal;
   model: LanguageModel;
   tools: T;
   instructions?: Instructions;
   generation: AgentGenerationSettings<T>;
 };
-type AgentGenerate<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet> = (context: AgentGenerateContext<M, D, T>) => ReadableStream<UIMessageChunk> | Promise<ReadableStream<UIMessageChunk>>;
+type AgentGenerate<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet, X extends object = Record<never, never>> = (context: AgentGenerateContext<M, D, T, X>) => ReadableStream<UIMessageChunk> | Promise<ReadableStream<UIMessageChunk>>;
 type UIMessageMetadata<M extends UIMessage> = M extends UIMessage<infer Metadata> ? Metadata : unknown;
-type AgentMessageMetadata<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet> = (context: AgentGenerateContext<M, D, T> & {
+type AgentMessageMetadata<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet, X extends object = Record<never, never>> = (context: AgentGenerateContext<M, D, T, X> & {
   part: TextStreamPart<T>;
 }) => UIMessageMetadata<M> | undefined;
-type AgentResolverContext<M extends UIMessage, D extends AIEventDefs<M> & EventDefs> = {
+type AgentResolverContext<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, X extends object = Record<never, never>> = {
   event: ContractEvent<D, "ai.generation.requested">;
   messages: M[];
+  /**
+   * The contract's application state, as of the captured snapshot. It rides
+   * in the checkpoint the generation already reads, so it costs no I/O.
+   */
+  state: X;
   session: Pick<HandlerContext<D>["session"], "state">;
   signal: AbortSignal;
 };
 type Resolvable<T, C> = T | ((context: C) => T | Promise<T>);
-type CompactionPolicy<M extends UIMessage, D extends AIEventDefs<M> & EventDefs> = {
-  shouldCompact(context: AgentResolverContext<M, D> & {
+/** A model with its reasoning level and speed, chosen together. */
+type ModelSettings = {
+  model: LanguageModel;
+  /** Overrides `generation.reasoning`. */
+  reasoning?: ReasoningLevel;
+  /** `fast` prefers AI Gateway's faster tier when the model offers one. */
+  speed?: "fast" | "standard";
+};
+type CompactionPolicy<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, X extends object = Record<never, never>> = {
+  shouldCompact(context: AgentResolverContext<M, D, X> & {
     messages: M[];
     modelMessages: ModelMessage[];
   }): boolean | Promise<boolean>;
-  compact(context: AgentResolverContext<M, D> & {
+  compact(context: AgentResolverContext<M, D, X> & {
     messages: M[];
     modelMessages: ModelMessage[];
   }): M[] | Promise<M[]>;
@@ -78,46 +85,83 @@ type AutomaticCompaction = {
   thresholdTokens?: number;
   instructions?: string;
 };
-type CompactionOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs> = false | AutomaticCompaction | CompactionPolicy<M, D>;
+type CompactionOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, X extends object = Record<never, never>> = false | AutomaticCompaction | CompactionPolicy<M, D, X>;
 type AgentGenerationSettings<T extends ToolSet> = AISDKStepSettings<T>;
-type CreateHandlersOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet> = {
-  agent: AgentDefinition<M, D>;
-  /** AI SDK model string or provider model, optionally resolved per generation. */
-  model: Resolvable<LanguageModel, AgentResolverContext<M, D>>;
+type AgentModelOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet, X extends object = Record<never, never>> = {
+  /**
+   * AI SDK model string or provider model, or `ModelSettings` to choose its
+   * reasoning level and speed with it, optionally resolved per generation.
+   */
+  model: Resolvable<LanguageModel | ModelSettings, AgentResolverContext<M, D, X>>;
   tools?: T;
-  instructions?: Resolvable<Instructions | undefined, AgentResolverContext<M, D>>;
-  /** Settings for each one-step AI SDK streamText call. */
-  generation?: AgentGenerationSettings<T>;
+  instructions?: Resolvable<Instructions | undefined, AgentResolverContext<M, D, X>>;
+  /** Settings for each one-step AI SDK streamText call, resolved per generation. */
+  generation?: Resolvable<AgentGenerationSettings<T>, AgentResolverContext<M, D, X>>;
   /**
    * Maximum model steps in one assistant response. Defaults to Infinity.
    */
   maxSteps?: number;
   /** Map default AI SDK stream parts to typed assistant message metadata. */
-  messageMetadata?: AgentMessageMetadata<M, D, T>;
+  messageMetadata?: AgentMessageMetadata<M, D, T, X>;
   /**
    * Replace model generation with an AI SDK UI message chunk stream.
    * The custom stream owns its metadata chunks.
    */
-  generate?: AgentGenerate<M, D, T>;
-  compaction?: Resolvable<CompactionOptions<M, D>, AgentResolverContext<M, D>>;
+  generate?: AgentGenerate<M, D, T, X>;
+  compaction?: Resolvable<CompactionOptions<M, D, X>, AgentResolverContext<M, D, X>>;
   /** Progress is durably flushed at either limit, whichever is reached first. */
   progress?: {
     maxChunks?: number;
     maxDelayMs?: number;
   };
+  /**
+   * Run local tool executions one at a time on this lane. By default,
+   * independent tools run concurrently.
+   */
+  toolLane?: string;
 };
-type CreateAgentServerOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet> = CreateHandlersOptions<M, D, T> & Omit<ServerOptions<D>, "contract" | "handlers"> & {
-  handlers?: ServerOptions<D>["handlers"];
+type AgentServerOptions<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, S, T extends ToolSet, X extends object = Record<never, never>> = AgentModelOptions<M, D, T, X> & Omit<ServerOptions<D, Record<never, never>, Reducer<D, S>>, "contract" | "handlers"> & {
+  /** Handlers for application events. */
+  handlers?: ServerOptions<D, Record<never, never>, Reducer<D, S>>["handlers"];
 };
+type AgentOptions<M extends UIMessage, E extends EventDefs, T extends ToolSet> = AgentServerOptions<NoInfer<M>, AIEventDefs<NoInfer<M>> & E, AIState<NoInfer<M>>, T> & {
+  /** Identity: prefixes storage keys and queue messages. */
+  name: string;
+  /**
+   * Server-only application events. Browsers push application events through
+   * a shared `agentContract()`.
+   */
+  events?: E;
+  /** Optional stricter schema for custom UIMessage metadata/data/tool types. */
+  messageSchema?: StandardSchemaV1<M>;
+};
+type AgentFromContractOptions<D extends AIEventDefs<AIMessageOf<D>> & EventDefs, S, T extends ToolSet, Name extends string = string, X extends object = Record<never, never>> = AgentServerOptions<AIMessageOf<D>, D, S, T, X> & {
+  /**
+   * A shared `agentContract()`. Its application state reaches every resolver
+   * as `state`; a fully custom contract is core A2, served by `createServer()`.
+   */
+  contract: Contract<D, Record<never, never>, Reducer<D, S> & {
+    readonly name: Name;
+    readonly "~appState": X;
+  }>;
+};
+/**
+ * An A2 server for the AI protocol; `typeof` it types `useAgent`. `Name` is
+ * its reducer's name: the built-in one lets contract-free clients fold state.
+ */
+type Agent<D extends EventDefs, S, Name extends string = string> = A2Server<D, Record<never, never>, Reducer<D, S> & {
+  readonly name: Name;
+}>;
 /** Run `fn` with `ctx` as the ambient tool handler context, for direct tool tests. */
 declare function runWithHandlerContext<D extends AgentToolEventDefs, R>(ctx: AgentToolContext<D>, fn: () => R): R;
 /**
- * Build the ordinary A2 handler table for the built-in agent protocol.
- * Application handlers can be spread beside this table.
+ * Serve an AI agent: the built-in protocol, its handlers, and A2's store,
+ * scheduler, and telemetry, as one ordinary A2 server. Pass `name` for the
+ * built-in protocol, or a shared `agentContract()` when clients fold
+ * application state.
  */
-declare function createHandlers<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet>(options: CreateHandlersOptions<M, D, T>): NonNullable<ServerOptions<D>["handlers"]>;
-/** Assemble an A2 server with the built-in agent handlers and app extensions. */
-declare function createAgentServer<M extends UIMessage, D extends AIEventDefs<M> & EventDefs, T extends ToolSet = ToolSet>(options: CreateAgentServerOptions<M, D, T>): A2Server<D>;
+declare function agent<T extends ToolSet = ToolSet, M extends UIMessage = UIMessage, E extends EventDefs = Record<never, never>>(options: AgentOptions<M, E, T>): Agent<AIEventDefs<M> & E, AIState<M>, typeof AI_STATE_REDUCER>;
+declare function agent<D extends AIEventDefs<AIMessageOf<D>> & EventDefs, S, T extends ToolSet = ToolSet, Name extends string = string, X extends object = Record<never, never>>(options: AgentFromContractOptions<D, S, T, Name, X>): Agent<D, S, Name>;
 //#endregion
-export { AgentGenerate, AgentGenerateContext, AgentGenerationSettings, AgentMessageMetadata, AgentResolverContext, AutomaticCompaction, CompactionOptions, CompactionPolicy, CreateAgentServerOptions, CreateHandlersOptions, type Instructions, type LanguageModel, Resolvable, type ToolSet, createAgentServer, createHandlers, runWithHandlerContext };
+export { type Agent, type AgentFromContractOptions, type AgentGenerate, type AgentGenerateContext, type AgentGenerationSettings, type AgentMessageMetadata, type AgentModelOptions, type AgentOptions, type AgentResolverContext, type AutomaticCompaction, type CompactionOptions, type CompactionPolicy, type Instructions, type LanguageModel, type ModelSettings, type Resolvable, type ToolSet, agent, runWithHandlerContext };
 //# sourceMappingURL=ai-server.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ai-server.d.ts","names":[],"sources":["../src/ai-sdk-step.ts","../src/ai-server.ts"],"mappings":"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"}
+{"version":3,"file":"ai-server.d.ts","names":[],"sources":["../src/ai-sdk-step.ts","../src/ai-agent.ts"],"mappings":"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"}