experimental-a2 0.6.0 → 0.8.0

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "experimental-a2",
-  "version": "0.6.0",
+  "version": "0.8.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",
-  "bin": {
-    "a2": "./dist/cli-bin.js"
-  },
   "sideEffects": false,
   "engines": {
     "node": ">=22.13"
@@ -39,7 +36,6 @@
       "browser": "./dist/ai-server.browser.js",
       "default": "./dist/ai-server.js"
     },
-    "./http": "./dist/http.js",
     "./store-memory": "./dist/store-memory.js",
     "./store-sqlite": "./dist/store-sqlite.js",
     "./store-postgres": "./dist/store-postgres.js",
@@ -49,15 +45,6 @@
     "./scheduler-vercel": "./dist/scheduler-vercel.js",
     "./cache-indexeddb": "./dist/cache-indexeddb.js",
     "./otel": "./dist/otel.js",
-    "./devtools": "./dist/devtools.js",
-    "./devtools/server": {
-      "browser": "./dist/devtools-server.browser.js",
-      "default": "./dist/devtools-server.js"
-    },
-    "./testing": {
-      "browser": "./dist/testing.browser.js",
-      "default": "./dist/testing.js"
-    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {

package/src/ai-server.ts

@@ -57,11 +57,14 @@ import {
   createServer,
   type A2Server,
   type HandlerContext,
-  type PushValidationContext,
   type ServerOptions,
 } from './server.ts'
+import {
+  setServerFetchHooks,
+  type ServerIngressContext,
+} from './server-fetch.ts'
 
-export function validateAgentPush(context: PushValidationContext): void {
+function validateAgentIngress(context: ServerIngressContext): void {
   const rejected = context.events.find((event) => {
     if (event.type !== 'ai.message.created') {
       return !(
@@ -203,7 +206,7 @@ export type CreateAgentServerOptions<
   D extends AIEventDefs<M> & EventDefs,
   T extends ToolSet = ToolSet,
 > = CreateHandlersOptions<M, D, T> &
-  Omit<ServerOptions<D>, 'contract' | 'handlers' | 'validatePush'> & {
+  Omit<ServerOptions<D>, 'contract' | 'handlers'> & {
     handlers?: ServerOptions<D>['handlers']
   }
 
@@ -839,13 +842,16 @@ export function createHandlers<
   const scheduleNext = async (
     ctx: Pick<HandlerContext<D>, 'session'>,
   ): Promise<AppendInput<D> | void> =>
-    requestForNextMessage((await ctx.session.state(coordinator)).state)
+    requestForNextMessage(
+      (await ctx.session.state(coordinator, { through: 'latest' })).state,
+    )
 
   const continueIfReady = async (
     ctx: Pick<HandlerContext<D>, 'session'>,
     generationId: string,
   ): Promise<void> => {
-    const state = (await ctx.session.state(coordinator)).state
+    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
+      .state
     const response = state.response
     if (response?.generation?.generationId !== generationId) {
       return
@@ -1089,6 +1095,7 @@ export function createHandlers<
       call,
       ctx.session.history,
     )
+    if (ctx.signal.aborted) return
     const scope: AmbientToolScope = {
       contract: options.agent.contract,
       context: ctx,
@@ -1103,7 +1110,8 @@ export function createHandlers<
   const handleToolCall = async (
     ctx: HandlerContext<D, 'ai.tool.called'>,
   ): Promise<AppendInput<D> | void> => {
-    const state = (await ctx.session.state(coordinator)).state
+    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
+      .state
     const response = state.response
     const current = response?.calls.find(
       (candidate) => candidate.index === ctx.event.index,
@@ -1127,7 +1135,8 @@ export function createHandlers<
   const handleApproval = async (
     ctx: HandlerContext<D, 'ai.approval.responded'>,
   ): Promise<AppendInput<D> | void> => {
-    const state = (await ctx.session.state(coordinator)).state
+    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
+      .state
     const response = state.response
     const current = response?.calls.find(
       (candidate) =>
@@ -1160,7 +1169,9 @@ export function createHandlers<
     const history = await ctx.session.history()
     const requestId = ctx.event.id
     const request = ctx.event.payload
-    const coordinatorState = (await ctx.session.state(coordinator)).state
+    const coordinatorState = (
+      await ctx.session.state(coordinator, { through: 'latest' })
+    ).state
     if (
       coordinatorState.closed ||
       coordinatorState.response?.activeRequestId !== requestId
@@ -1314,7 +1325,9 @@ export function createHandlers<
     } as AppendInput<D>)
     await ctx.session.append('generation-start', ...startEvents)
 
-    const startedCoordinatorState = (await ctx.session.state(coordinator)).state
+    const startedCoordinatorState = (
+      await ctx.session.state(coordinator, { through: 'latest' })
+    ).state
     if (
       startedCoordinatorState.response?.activeRequestId !== requestId ||
       startedCoordinatorState.response.generation?.generationId !== generationId
@@ -1361,8 +1374,12 @@ export function createHandlers<
       }
     }
 
-    const currentState = (await ctx.session.state(options.agent.reducer)).state
-    const currentCoordinatorState = (await ctx.session.state(coordinator)).state
+    const currentState = (
+      await ctx.session.state(options.agent.reducer, { through: 'latest' })
+    ).state
+    const currentCoordinatorState = (
+      await ctx.session.state(coordinator, { through: 'latest' })
+    ).state
     const generationMessages = activeContextMessages(
       currentState,
       currentCoordinatorState,
@@ -1378,6 +1395,7 @@ export function createHandlers<
         options.instructions === undefined
           ? undefined
           : await resolve(options.instructions, resolverContext)
+      if (ctx.signal.aborted) return
       const generateContext: AgentGenerateContext<M, D, T> = {
         request: ctx.event,
         requestId,
@@ -1538,7 +1556,8 @@ export function createHandlers<
   const handleRetry = async (
     ctx: HandlerContext<D, 'ai.retry.requested'>,
   ): Promise<AppendInput<D> | void> => {
-    const state = (await ctx.session.state(coordinator)).state
+    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
+      .state
     const response = state.response
     if (
       response?.status !== 'failed' ||
@@ -1561,7 +1580,8 @@ export function createHandlers<
   const handleInputResponse = async (
     ctx: HandlerContext<D, 'ai.input.responded'>,
   ): Promise<void> => {
-    const state = (await ctx.session.state(coordinator)).state
+    const state = (await ctx.session.state(coordinator, { through: 'latest' }))
+      .state
     const response = state.response
     if (
       response?.responseMessageId !== ctx.event.payload.messageId ||
@@ -1708,12 +1728,13 @@ export function createAgentServer<
     ...(compaction === undefined ? {} : { compaction }),
     ...(progress === undefined ? {} : { progress }),
   })
-  return createServer({
+  const server = createServer({
     ...serverOptions,
     contract: definition.contract,
     handlers: { ...builtIns, ...handlers },
-    validatePush: validateAgentPush,
   })
+  setServerFetchHooks(server, { validateIngress: validateAgentIngress })
+  return server
 }
 
 export type { Instructions, LanguageModel, ToolSet }

package/src/client.ts

@@ -808,7 +808,7 @@ const wsTransport = (
         settleChannel(
           channel,
           new Error(
-            'subscribe not confirmed: is the ws route serving the multiplexed socket (handle with options.upgrade)?',
+            'subscribe not confirmed: is the ws route calling server.fetch with upgradeWebSocket?',
           ),
         )
       }, STREAM_TIMINGS.stallTimeoutMs)
@@ -1562,7 +1562,7 @@ export function createClient<
       const readHistory = transport.history
       if (readHistory === undefined) {
         throw new TypeError(
-          'loadHistory requires an http api — the ws transport has no history lane; serve the session over handle() and pass its route url as the string or { type: "http" } api',
+          'loadHistory requires an http api — the ws transport has no history lane; serve the session with server.fetch and pass its route url as the string or { type: "http" } api',
         )
       }
       const before = loadOptions?.before

package/src/errors.ts

@@ -8,6 +8,7 @@
 
 export type A2ErrorCode =
   | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written
+  | 'FORBIDDEN' // external ingress was denied by server.fetch authorization
   | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map
   | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events
   | 'SUPERSEDED_ATTEMPT' // handler append from an attempt a recovery claim replaced

package/src/internal.ts

@@ -4,7 +4,7 @@
  */
 
 import type { ScheduledEvent } from './scheduler-task.ts'
-import type { A2Scheduler, DrainableServer } from './server.ts'
+import type { DrainableServer } from './server.ts'
 
 export type DrainOutcome = 'busy' | 'stalled' | 'settled'
 
@@ -67,14 +67,6 @@ export type ServerInternals = {
 
 export const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()
 
-type ServerSchedulerBinding = {
-  scheduler: A2Scheduler | undefined
-}
-
-/** Scheduler configuration captured only for servers made by `createServer`. */
-export const serverSchedulerBindings: WeakMap<object, ServerSchedulerBinding> =
-  new WeakMap()
-
 const objectLike = (value: unknown): value is object =>
   (typeof value === 'object' && value !== null) || typeof value === 'function'
 
@@ -232,13 +224,11 @@ const isDrainableServer = (value: unknown): value is DrainableServer => {
 
 /**
  * Validate the server list captured by a scheduler route at construction time.
- * Built-in adapters keep their low-level target seam structural for custom
- * integrations. The application-facing `schedulerHandler` uses strict mode
- * so only servers made by this A2 copy reach a configured adapter.
+ * The seam stays structural so custom scheduler integrations can supply their
+ * own drainable targets.
  */
 export function assertSchedulerTargets(
   servers: readonly unknown[],
-  options: { allowStructural: boolean },
 ): asserts servers is readonly DrainableServer[] {
   const contracts = new Set<string>()
   for (const target of servers) {
@@ -252,56 +242,7 @@ export function assertSchedulerTargets(
       )
     }
     contracts.add(name)
-
-    const binding = serverSchedulerBindings.get(target)
-    if (!binding) {
-      if (!options.allowStructural) {
-        throw new TypeError(
-          `a2 scheduler: server for contract '${name}' was not created by createServer()`,
-        )
-      }
-      continue
-    }
-  }
-}
-
-/** Require every real server to share one exact configured scheduler. */
-export function assertServerSchedulerBindings(
-  scheduler: A2Scheduler,
-  servers: readonly DrainableServer[],
-): void {
-  for (const server of servers) {
-    const binding = serverSchedulerBindings.get(server)
-    if (!binding?.scheduler) {
-      throw new TypeError(
-        `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
-      )
-    }
-    if (binding.scheduler !== scheduler) {
-      throw new TypeError(
-        `a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`,
-      )
-    }
-  }
-}
-
-/** Resolve the scheduler privately bound to a real A2 server. */
-export function schedulerForServer(server: unknown): A2Scheduler {
-  if (!isDrainableServer(server)) {
-    throw new TypeError('a2 scheduler: expected a server from createServer()')
-  }
-  const binding = serverSchedulerBindings.get(server)
-  if (!binding) {
-    throw new TypeError(
-      `a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`,
-    )
-  }
-  if (!binding.scheduler) {
-    throw new TypeError(
-      `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
-    )
   }
-  return binding.scheduler
 }
 
 /**

package/src/push-envelope.ts

@@ -1,14 +1,25 @@
 /**
- * The push envelope's trust boundary — parsing and provenance-branding
- * for `{ sessionId, events, presence? }`, shared verbatim by the HTTP
+ * The push envelope's trust boundary for `{ sessionId, events, presence? }`,
+ * shared verbatim by the HTTP
  * POST lane and the socket's push/presence frames so INVALID_PAYLOAD
- * shapes are one implementation. Internal module — `handle` (and the
- * socket handler) compose it; it is not part of the public surface.
+ * shapes are one implementation. Internal module, not public API.
  */
 
 import { A2Error } from './errors.ts'
 import { MAX_DATE_MS, RESERVED_PARTICIPANT_IDS } from './internal.ts'
-import type { PushedEvent, PushedPresence } from './server.ts'
+
+export type ParsedPushEvent = {
+  type: string
+  payload: unknown
+  id?: string
+}
+
+export type ParsedPushPresence = {
+  participant: string
+  values: Record<string, unknown>
+  seen?: number
+  at?: number
+}
 
 export const invalidPushBody = (message: string): A2Error =>
   new A2Error('INVALID_PAYLOAD', `malformed push body: ${message}`)
@@ -17,18 +28,13 @@ const invalid = invalidPushBody
 
 export type PushBody = {
   sessionId: string
-  /** Branded: `session.append` accepts these directly (the push route
-   * path); schema validation still happens inside `append`. Empty only
-   * for a presence-only push. */
-  events: PushedEvent[]
-  /** Branded like `events`: `session.setPresence` accepts it whole;
-   * field validation still happens inside `setPresence`. */
-  presence?: PushedPresence
+  events: ParsedPushEvent[]
+  presence?: ParsedPushPresence
 }
 
 export function parsePresenceSibling(
   value: unknown,
-): PushedPresence | undefined {
+): ParsedPushPresence | undefined {
   if (value === undefined) return undefined
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     throw invalid('presence must be an object when present')
@@ -68,14 +74,12 @@ export function parsePresenceSibling(
   } = { participant, values: values as Record<string, unknown> }
   if (seen !== undefined) out.seen = seen
   if (at !== undefined) out.at = at
-  Object.defineProperty(out, '~a2.pushed', { value: true })
-  return out as PushedPresence
+  return out
 }
 
-/** The events half of the envelope — shared verbatim by the POST body
- * and the socket's `push` frames, so the provenance brand and the
- * INVALID_PAYLOAD shapes are one implementation. */
-export function parsePushEvents(events: unknown): PushedEvent[] {
+/** The events half of the envelope, shared by the POST body and socket
+ * `push` frames so INVALID_PAYLOAD shapes have one implementation. */
+export function parsePushEvents(events: unknown): ParsedPushEvent[] {
   if (!Array.isArray(events) || events.length === 0) {
     throw invalid('events must be a non-empty array')
   }
@@ -95,8 +99,7 @@ export function parsePushEvents(events: unknown): PushedEvent[] {
       payload,
     }
     if (id !== undefined) out.id = id
-    Object.defineProperty(out, '~a2.pushed', { value: true })
-    return out as PushedEvent
+    return out
   })
 }
 

package/src/scheduler-qstash.ts

@@ -94,7 +94,7 @@ export type QStashTransport = {
 }
 
 export type QStashSchedulerOptions = {
-  /** Exact URL mounted with `schedulerHandler(...)`. Inferred in local dev and on Vercel. */
+  /** Exact URL mounted with `scheduler.handler(...)`. Inferred in local dev and on Vercel. */
   url?: string
   /** QStash API token. Default: `QSTASH_TOKEN`. */
   token?: string
@@ -819,7 +819,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
     },
 
     handler(...servers: DrainableServer[]) {
-      assertSchedulerTargets(servers, { allowStructural: true })
+      assertSchedulerTargets(servers)
       const byContract = new Map<string, DrainableServer>()
       for (const server of servers) {
         byContract.set(server.contract.name, server)
@@ -851,7 +851,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
         const server = byContract.get(task.contract)
         if (!server) {
           throw new Error(
-            `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+            `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,
           )
         }
         const internals = serverInternals.get(server)

package/src/scheduler-vercel.ts

@@ -368,7 +368,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
     },
 
     handler(...servers: DrainableServer[]) {
-      assertSchedulerTargets(servers, { allowStructural: true })
+      assertSchedulerTargets(servers)
       const byContract = new Map<string, DrainableServer>()
       for (const server of servers) {
         byContract.set(server.contract.name, server)
@@ -386,7 +386,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
             // wiring bug — throw so it redelivers and stays visible in
             // queue observability instead of vanishing on an ack.
             throw new Error(
-              `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+              `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,
             )
           }
           const internals = serverInternals.get(server)