experimental-a2 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -2,4 +2,8 @@ import { a as ContractEvent, c as PresenceDefs, d as PresenceSnapshot, f as Redu
 import { i as Event } from "./store-D_yhNdPz.js";
 import { i as NonRetriableError, n as A2ErrorCode, r as A2ServerErrorCode, t as A2Error } from "./errors-DvhSXnxk.js";
 import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-CpeclqB2.js";
-export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2ServerErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, NonRetriableError, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceSnapshot, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };
+//#region src/idempotent-id.d.ts
+declare function idempotentId(...parts: string[]): Promise<string>;
+//#endregion
+export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2ServerErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, NonRetriableError, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceSnapshot, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract, idempotentId };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/idempotent-id.ts"],"mappings":";;;;;iBAAsB,gBAAgB,kBAAkB"}

package/dist/index.js

@@ -1,3 +1,15 @@
 import { t as contract } from "./contract-CKRg_E4q.js";
 import { n as NonRetriableError, t as A2Error } from "./errors-DCk6ch5n.js";
-export { A2Error, NonRetriableError, contract };
+//#region src/idempotent-id.ts
+async function idempotentId(...parts) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(parts)));
+	const bytes = new Uint8Array(digest).slice(0, 16);
+	bytes[6] = bytes[6] & 15 | 128;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+//#endregion
+export { A2Error, NonRetriableError, contract, idempotentId };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/idempotent-id.ts"],"sourcesContent":["export async function idempotentId(...parts: string[]): Promise<string> {\n  const digest = await crypto.subtle.digest(\n    'SHA-256',\n    new TextEncoder().encode(JSON.stringify(parts)),\n  )\n  const bytes = new Uint8Array(digest).slice(0, 16)\n  bytes[6] = (bytes[6]! & 0x0f) | 0x80\n  bytes[8] = (bytes[8]! & 0x3f) | 0x80\n  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`\n}\n"],"mappings":";;;AAAA,eAAsB,aAAa,GAAG,OAAkC;CACtE,MAAM,SAAS,MAAM,OAAO,OAAO,OACjC,WACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,UAAU,KAAK,CAAC,CAChD;CACA,MAAM,QAAQ,IAAI,WAAW,MAAM,CAAC,CAAC,MAAM,GAAG,EAAE;CAChD,MAAM,KAAM,MAAM,KAAM,KAAQ;CAChC,MAAM,KAAM,MAAM,KAAM,KAAQ;CAChC,MAAM,MAAM,MAAM,KAAK,QAAQ,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;CAC7E,OAAO,GAAG,IAAI,MAAM,GAAG,CAAC,EAAE,GAAG,IAAI,MAAM,GAAG,EAAE,EAAE,GAAG,IAAI,MAAM,IAAI,EAAE,EAAE,GAAG,IAAI,MAAM,IAAI,EAAE,EAAE,GAAG,IAAI,MAAM,IAAI,EAAE;AAC7G"}

package/docs/guides/06-ai-agents.mdx

@@ -67,11 +67,30 @@ and continuation between steps. Responses have no step limit by default. Set
 `maxSteps` to a positive integer to limit one complete assistant response.
 Individual providers decide which model settings they support. `generation`
 therefore excludes `stopWhen`, tool execution callbacks, tool callers, sandbox
-execution, and the tool approval secret. Everything else, including
-`toolsContext`, passes through to the AI SDK untouched. A local tool reads its
-durable execution context later, from the handler that runs it. Model-step
+execution, and the tool approval secret. A2 preserves all other supplied
+settings, including `toolsContext`, when calling the AI SDK. A local tool
+reads its durable execution context later, from the handler that runs it. Model-step
 timeouts are supported; tool-execution timeouts are not.
 
+For AI Gateway models, the default generator sets
+`generation.providerOptions.gateway.caching` to `'auto'`. A2 merges this
+default with your provider options, with caller-supplied values taking
+precedence. Other Gateway options and provider namespaces are preserved.
+The same default applies to automatic compaction. A custom `generate`
+function receives your original settings and owns its caching policy.
+
+Gateway calls also send an `x-session-affinity` header derived from a SHA-256
+hash of the agent name and session ID. The value stays stable across turns,
+retries, worker restarts, and automatic compaction. No raw session identifier
+is sent in this header. A caller-supplied `generation.headers` entry takes
+precedence, regardless of header casing; an explicit `undefined` suppresses
+A2's default header. Set overrides here, since A2's per-call default can
+override headers configured on the model itself.
+Affinity helps supporting providers reuse their cache; it does not select
+Gateway's provider or guarantee a cache hit.
+See [Gateway automatic caching](https://vercel.com/docs/ai-gateway/models-and-providers/automatic-caching)
+for provider support and cache-write costs.
+
 ### Store assistant metadata
 
 Extend the agent's `UIMessage` type to keep generation status and usage on the

package/docs/reference/01-api.mdx

@@ -63,6 +63,31 @@ The shared base for A2 failures, discriminated by `code`. The session
 client exposes its `A2ClientError` subclass. See
 [Errors](/reference/errors).
 
+### `idempotentId(...parts)`
+
+`idempotentId(...parts: string[]): Promise<string>` derives a stable UUIDv8
+from an ordered tuple of strings. It runs on the server and in the browser.
+
+```ts shared/request-id.ts
+import { idempotentId } from 'experimental-a2'
+
+export const id = await idempotentId('orders', 'shop-7', 'request-42')
+```
+
+Pass the result as an event's `id` when retries should converge on the same
+event. The same tuple produces the same ID across runtimes and A2 versions.
+String boundaries, order, and case matter; strings are not normalized.
+Empty strings and an empty tuple are valid inputs.
+
+Every argument has the same role. A prefix such as `'orders'` is a namespace
+by convention. Include enough context to distinguish operations across
+contracts and sessions, since event IDs are globally unique within a store.
+
+The helper performs no I/O. A2 preserves explicit IDs and keeps its automatic
+ID generation unchanged. Changing an existing application's ID recipe changes
+retry identity, so retries of previously committed requests need to retain
+their original IDs.
+
 ## `experimental-a2/server`
 
 ### `handler(entry)`

package/examples/playground/package.json

@@ -22,7 +22,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.14.0",
+    "experimental-a2": "0.15.0",
     "ioredis": "^5.9.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",

package/src/ai-server.ts

@@ -11,6 +11,7 @@
 import { createControlRuntime, ControlCancelled } from './ai-control-server.ts'
 import type { ControlCommit } from './ai-control.ts'
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { createHash } from 'node:crypto'
 import { asSchema, convertToModelMessages } from 'ai'
 import type {
   FinishReason,
@@ -336,10 +337,38 @@ async function generateWithAISDK<
   M extends UIMessage,
   D extends AIEventDefs<M> & EventDefs,
   T extends ToolSet,
->(
-  context: AgentGenerateContext<M, D, T>,
-  messageMetadata: AgentMessageMetadata<M, D, T> | undefined,
-): Promise<GenerationSource> {
+>(options: {
+  agentName: string
+  context: AgentGenerateContext<M, D, T>
+  messageMetadata: AgentMessageMetadata<M, D, T> | undefined
+}): Promise<GenerationSource> {
+  const { agentName, context, messageMetadata } = options
+  const headers = context.generation.headers ?? {}
+  const generation =
+    gatewayModelId(context.model) === undefined
+      ? context.generation
+      : {
+          ...context.generation,
+          headers: Object.keys(headers).some(
+            (key) => key.toLowerCase() === 'x-session-affinity',
+          )
+            ? headers
+            : {
+                ...headers,
+                'x-session-affinity': createHash('sha256')
+                  .update(
+                    JSON.stringify([agentName, context.request.sessionId]),
+                  )
+                  .digest('hex'),
+              },
+          providerOptions: {
+            ...context.generation.providerOptions,
+            gateway: {
+              caching: 'auto',
+              ...context.generation.providerOptions?.['gateway'],
+            },
+          },
+        }
   const step = await generateAISDKStep<M, T>({
     model: context.model,
     tools: context.tools,
@@ -350,11 +379,12 @@ async function generateWithAISDK<
     ...(context.instructions === undefined
       ? {}
       : { instructions: context.instructions }),
-    settings: context.generation,
+    settings: generation,
     ...(messageMetadata === undefined
       ? {}
       : {
-          messageMetadata: ({ part }) => messageMetadata({ ...context, part }),
+          messageMetadata: ({ part }) =>
+            messageMetadata({ ...context, generation, part }),
         }),
   })
   return {
@@ -457,6 +487,7 @@ const summarize = async <
   D extends AIEventDefs<M> & EventDefs,
   T extends ToolSet,
 >(options: {
+  agentName: string
   context: AgentGenerateContext<M, D, T>
   instructions: string | undefined
 }): Promise<{ summary: string; usage?: LanguageModelUsage }> => {
@@ -498,8 +529,9 @@ const summarize = async <
       return [name, definition]
     }),
   ) as T
-  const source = await generateWithAISDK(
-    {
+  const source = await generateWithAISDK({
+    agentName: options.agentName,
+    context: {
       ...options.context,
       generation,
       tools,
@@ -509,8 +541,8 @@ const summarize = async <
       ],
       responseMessageId: `${options.context.generationId}:summary`,
     },
-    undefined,
-  )
+    messageMetadata: undefined,
+  })
   let summary = ''
   let calledTool = false
   let finish: AgentGenerationFinish | undefined
@@ -1663,6 +1695,7 @@ export function createHandlers<
             ? {
                 messages: [] as M[],
                 ...(await summarize({
+                  agentName: options.agent.contract.name,
                   context: baseContext,
                   instructions: policy.instructions,
                 })),
@@ -1765,7 +1798,11 @@ export function createHandlers<
       const custom = options.generate !== undefined
       const source =
         options.generate === undefined
-          ? await generateWithAISDK(generateContext, options.messageMetadata)
+          ? await generateWithAISDK({
+              agentName: options.agent.contract.name,
+              context: generateContext,
+              messageMetadata: options.messageMetadata,
+            })
           : { stream: await options.generate(generateContext) }
       const updates = consumeGeneration({
         source,

package/src/idempotent-id.ts

@@ -0,0 +1,11 @@
+export async function idempotentId(...parts: string[]): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(JSON.stringify(parts)),
+  )
+  const bytes = new Uint8Array(digest).slice(0, 16)
+  bytes[6] = (bytes[6]! & 0x0f) | 0x80
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}

package/src/index.ts

@@ -8,6 +8,7 @@
  */
 
 export { contract } from './contract.ts'
+export { idempotentId } from './idempotent-id.ts'
 export type {
   AppendInput,
   Contract,