experimental-a2 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+Notable changes to the `experimental-a2` package. The telemetry span/attribute
+catalogue (see the API reference) is treated as a contract: renames and
+additions are breaking for dashboards and are called out here.
+
+## Unreleased
+
+### Breaking
+
+- **`a2.machine` is gone.** The API is now `a2.contract({ name, events })`
+  (isomorphic identity + vocabulary, from `experimental-a2`) plus
+  `createServer({ contract, log?, recovery?, telemetry?, handlers? })`
+  (from the new server-only entry point `experimental-a2/server`). Handlers are
+  declared at construction — `.on()` no longer exists; an entry is a
+  handler function or `{ abortOn, handler }`.
+- **`a2.events` and `a2.reducer` are gone.** The contract carries the
+  vocabulary; reducers derive from it:
+  `contract.reducer({ name, initialState, stateSchema? }).fold(fn)`.
+- **Definition takes a bag, runtime takes values.** All definition-time
+  constructors take a single options object (`contract`, `reducer`,
+  `createServer`, matching `createClient`/`createReact`). Runtime ids
+  stay positional: `server.session(id)`, `server.drain(sessionId)`.
+- **Lease operations take named options.** Custom `A2Log` adapters and direct
+  callers now use `lease.acquire({ sessionId, holder, ttlMs, expiresAtMs })`
+  and `lease.release({ sessionId, holder })` instead of positional arguments.
+- **Custom `A2Log` drain operations are atomic.** `recordFailure()` and
+  `StoredEvent.attempts` are replaced by `claimNext()`,
+  `completeAndClaimNext()`, `failAttempt()`, `attemptCount`, and
+  `failureCount`.
+- **Custom `A2Log` state reads are one operation.** Optional
+  `getSnapshot()`/`putSnapshot()` hooks are replaced by required
+  `readState()`/`putSnapshot()` methods. `readState()` returns one consistent
+  snapshot-plus-tail view. Every built-in backend implements it as one storage
+  operation.
+- **Reads no longer dispatch handlers.** `state()` and `stream()` are
+  observational. Without recovery, a later append or explicit `drain()` is the
+  retry path. Snapshot write-back now runs as tracked platform `waitUntil` work
+  and does not delay `state()`.
+- **Custom `A2Log` events expose durable lifecycle metadata.** `StoredEvent`
+  adds atomic `cause`, `firstClaimedAt`, `lastClaimedAt`,
+  `processedByAttempt`, `lastFailedAt`, and `lastFailedAttempt`. Adapter append,
+  claim, completion, and failure operations must persist these fields.
+- **Telemetry attribute renames** — dashboards keyed on the old names
+  go blank:
+  - `a2.machine` → `a2.contract` (every span)
+  - `a2.reducer` → `a2.state.reducer` (on `a2.state` spans)
+- **Telemetry outcome addition.** `a2.event.outcome` adds `superseded`;
+  exhaustive dashboards must handle it.
+
+### Added
+
+- **Durable causal lifecycle metadata.** Stored events now retain the
+  same-session parent index and attempt as one atomic cause, plus first/latest
+  claim, write-once completion, and latest caught-failure summaries. Built-in
+  backends persist the metadata in their existing atomic operations, so causal
+  trees and useful lifecycle boundaries require no extra backend round trip.
+
+- **Durable `ctx.attempt`.** This 1-based claim ordinal is also reported as
+  `a2.event.attempt`. Hard kills consume attempts, but not the failure budget.
+  Atomic claim and handoff add no log round trips.
+
+- `LOG_NOT_CONFIGURED` defers from construction to first use during
+  `next build`'s page-data collection (`NEXT_PHASE`), so CIs without
+  runtime env vars can build; real production boots still fail fast.
+
+- **`experimental-a2/log-postgres`** — the production log backend. Real
+  transactions; appends serialize per session on an advisory lock;
+  streaming polls the log (a LISTEN/NOTIFY upgrade can land without
+  API change). `pg` is an optional peer dependency — pass
+  `connectionString`, or inject any pool-shaped `client` (PGlite
+  passes the full conformance suite in-process).
+- **`experimental-a2/log-redis`** — the push-native log backend, on Redis Streams:
+  the stream entry ID is the a2 index, so `XREAD BLOCK` parks
+  server-side and delivers the instant an event lands — no poll
+  interval anywhere (measured: sub-20ms to a parked subscriber).
+  Every write path is one atomic Lua script; lease expiry stays on
+  the injected clock (real-time `PX` is garbage collection only).
+  `ioredis` optional peer, or inject any `call`/`duplicate` client;
+  `keyPrefix` isolates apps sharing one Redis. Single-instance /
+  non-cluster (Upstash — durable by default — Valkey, your own box).
+- **Lease watchdog recovery.** Handler dispatch no longer predicts the
+  platform deadline. Every lease acquisition and renewal arms a watchdog for
+  just after that execution window, while the queue send and database lease
+  proceed independently. A known invocation deadline caps the final window,
+  so a real function timeout retries the same unprocessed event promptly.
+  Whole-second due-time keys coalesce racing arms, and busy callbacks advance
+  the existing heartbeat-aligned slot series instead of starting another one.
+  Queue failure never blocks processing or lease renewal.
+- **`experimental-a2/recovery-vercel`** — queue-backed recovery over Vercel Queues
+  (`@vercel/queue` optional peer). `vercelQueues()` returns the
+  `A2Recovery` pair: `arm` (absolute `dueAt`, delayed, idempotent) and
+  `handler(...servers)` (drain, ack when settled or a later watchdog is
+  durable). The initial arm starts alongside inline work and is awaited only
+  before `append` resolves, with a bounded wait. A failed or hung arm never
+  fails the append; it marks the span `a2.append.armed: false` and degrades
+  that append to append-driven healing. Unacknowledged callbacks use Vercel
+  Queues' 30-second minimum visibility as the fallback when a fresh watchdog
+  send fails.
+- **Activity-adaptive polling** in the sqlite and postgres streams:
+  25ms between polls while a session is producing events, doubling to
+  a 250ms ceiling when it goes quiet. Token streams read smoothly
+  instead of clumping at the idle interval; an idle stream costs the
+  same as before. The cadence is owned, not configurable — there is no
+  `pollIntervalMs` option; the floor keeps active streams smooth, and
+  every poll is a catch-up read, so correctness is untouched.
+- **SSE heartbeat**: `sseResponse` emits a `: ping` comment frame every
+  15 seconds (in addition to the `: connected` prelude), so clients and
+  proxies can tell a quiet stream from a dead one.
+- **Client stall detection**: the session client treats a stream with
+  no bytes for two missed heartbeats (~35s) as dead — it aborts and
+  reconnects through the normal backoff path. A `live` connection now
+  means data is actually flowing.
+- **`connection` on the session snapshot** (and `useSession`),
+  replacing the flat `status` field: a discriminated union —
+  `{ status: 'idle' } | { status: 'connecting', reconnects, error } |
+{ status: 'live', reconnects } | { status: 'closed' }` — so an error
+  only exists while disconnected and reconnect state needs no
+  status-diffing effects.
+- **`push()` returns a `PushResult`**: awaiting it gives the server ack
+  exactly as before, and its lazy `.confirmed` promise resolves when
+  the live stream has delivered the batch back — the per-push
+  lifecycle (applied → acked → confirmed) as one call and two awaits.
+  A rejected push rejects both with the same `A2Error`.
+- The API reference now documents the full span catalogue: all four
+  span names (including `a2.state`), which attributes arrive at span
+  start vs mid-span via `setAttribute`, and the complete outcome value
+  sets.

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

@@ -0,0 +1 @@
+export {}

package/dist/ai-server.browser.js

@@ -0,0 +1,4 @@
+//#region src/ai-server.browser.ts
+/** a2/ai/server is server-only; agent definitions live in a2/ai. */
+throw new Error("a2/ai/server is server-only — a client bundle imported it. Import agent from a2/ai in browser code instead.");
+//#endregion

package/dist/ai-server.d.ts

@@ -0,0 +1,65 @@
+import { i as EventDefs, r as ContractEvent } from "./contract-DL8btVd9.js";
+import { AIEventDefs, AIState, AgentDefinition } from "./ai.js";
+import { A2Server, ServerOptions } from "./server.js";
+import { Instructions, LanguageModel, ToolLoopAgentSettings, ToolSet, UIMessage, UIMessageChunk } from "ai";
+//#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;
+  generationId: string;
+  responseMessageId: string;
+  messages: M[];
+  state: AIState<M>;
+  history: ContractEvent<D>[];
+  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 AgentResolverContext<M extends UIMessage, D extends AIEventDefs<M> & EventDefs> = {
+  event: ContractEvent<D, "ai.generation.requested">;
+  state: AIState<M>;
+  history: ContractEvent<D>[];
+  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> & {
+    messages: M[];
+  }): boolean | Promise<boolean>;
+  compact(context: AgentResolverContext<M, D> & {
+    messages: M[];
+  }): M[] | Promise<M[]>;
+};
+type AgentGenerationSettings<T extends ToolSet> = Partial<Omit<ToolLoopAgentSettings<never, T>, "id" | "model" | "tools" | "instructions" | "callOptionsSchema" | "prepareCall">>;
+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>>;
+  tools?: T;
+  instructions?: Resolvable<Instructions | undefined, AgentResolverContext<M, D>>;
+  /** Passed to AI SDK's ToolLoopAgent. */
+  generation?: AgentGenerationSettings<T>;
+  /** Replace model generation with an AI SDK UI message chunk stream. */
+  generate?: AgentGenerate<M, D, T>;
+  compaction?: CompactionPolicy<M, D>;
+  /** Progress is durably flushed at either limit, whichever is reached first. */
+  progress?: {
+    maxChunks?: number;
+    maxDelayMs?: number;
+  };
+};
+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"];
+};
+/**
+ * Build the ordinary A2 handler table for the built-in agent protocol.
+ * Application handlers can be spread beside this table.
+ */
+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>;
+//#endregion
+export { AgentGenerate, AgentGenerateContext, AgentGenerationSettings, AgentResolverContext, CompactionPolicy, CreateAgentServerOptions, CreateHandlersOptions, type Instructions, type LanguageModel, Resolvable, type ToolLoopAgentSettings, type ToolSet, createAgentServer, createHandlers };