experimental-a2 0.11.0 → 0.12.0

package/docs/reference/01-api.mdx

@@ -65,6 +65,64 @@ client exposes its `A2ClientError` subclass. See
 
 ## `experimental-a2/server`
 
+### `handler(entry)`
+
+Define handlers inline in `createServer({ handlers })` for ordinary use.
+Use this helper when composing an existing handler.
+
+Accepts a handler function or an object with `handler` and optional `lane` and
+`abortOn`. Returns the object shape: a function becomes `{ handler: entry }`,
+and an object is returned unchanged. The original function and object types
+are preserved. Use it to compose an existing handler without branching on its
+shape.
+
+```ts server/composed-orders.ts
+import * as a2 from 'experimental-a2'
+import { createServer, handler, type HandlerContext } from 'experimental-a2/server'
+import { z } from 'zod'
+
+const orders = a2.contract({
+  name: 'composed-orders',
+  events: {
+    created: z.object({ shopId: z.string() }),
+    notified: z.object({ shopId: z.string() }),
+  },
+})
+
+const created = handler({
+  lane: 'orders',
+  handler: async (ctx: HandlerContext<typeof orders.events, 'created'>) => {
+    return orders.batch({ type: 'notified', payload: ctx.event.payload })
+  },
+})
+
+export const ordersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: {
+      ...created,
+      handler: async (ctx) => {
+        const result = await created.handler(ctx)
+        // Your additional work goes here:
+        // await notifyShop(ctx.event.payload, { idempotencyKey: ctx.event.id })
+        return result
+      },
+    },
+  },
+})
+```
+
+Spreading the object preserves its `lane` and `abortOn`. Set either property
+after the spread to override it. Changing a built-in AI handler's lane can
+separate it from the handlers it coordinates with.
+
+Composition runs in one handler attempt. Work after the original function
+resolves still runs before its returned events commit. A thrown error fails
+the composed attempt; on retry, the wrapper and original handler can run again.
+For a new handler, annotate its context as above or pass an already typed
+function. `handler` does not bind a handler to a contract;
+`createServer({ handlers })` checks that it matches the contract.
+
 ### `createServer(options)`
 
 ```ts
@@ -1205,7 +1263,12 @@ it into `createServer({ handlers })` beside application handlers when you need
 a custom assembly. The table handles input facts, generation requests, model
 step completion, tool calls, approval responses, and terminal tool results.
 Application handlers spread later can deliberately replace a built-in
-handler. A custom assembly owns its browser ingress policy. Use
+handler. Use `handler` from `experimental-a2/server` to normalize an
+existing entry before wrapping its `handler` and spreading its execution
+policy. Entries in this table's type are optional; narrow an entry before
+passing it to `handler`.
+
+A custom assembly owns its browser ingress policy. Use
 `server.fetch(request, { authorize })` to reject server-authored AI event names
 before they reach the server. `createAgentServer()` installs the built-in
 browser allowlist automatically.

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.11.0",
+    "experimental-a2": "0.12.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.11.0",
+  "version": "0.12.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/server.ts

@@ -301,6 +301,17 @@ export type HandlerEntry<
       handler: Handler<D, K, P>
     }
 
+type HandlerFunction = (ctx: never) => Promise<unknown>
+
+export function handler<
+  H extends HandlerFunction | { handler: HandlerFunction },
+>(entry: H): H extends HandlerFunction ? { handler: H } : H
+export function handler(
+  entry: HandlerFunction | { handler: HandlerFunction },
+): { handler: HandlerFunction } {
+  return typeof entry === 'function' ? { handler: entry } : entry
+}
+
 export type ServerOptions<
   D extends EventDefs,
   P extends PresenceDefs = Record<never, never>,
@@ -615,8 +626,8 @@ export function createServer<
         `contract '${name}' has no event type '${type}' — cannot register a handler for it`,
       )
     }
-    const handler = typeof entry === 'function' ? entry : entry?.handler
-    if (typeof handler !== 'function') {
+    const callback = typeof entry === 'function' ? entry : entry?.handler
+    if (typeof callback !== 'function') {
       throw new TypeError(`handler for '${type}' must be a function`)
     }
     let abortOn: AbortMatcher | null = null
@@ -660,7 +671,7 @@ export function createServer<
       )
     }
     handlers.set(type, {
-      handler: handler as Handler<D>,
+      handler: callback as Handler<D>,
       abortOn,
       lane: lane as Lane<D> | null,
     })