@adia-ai/agent 0.8.26

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.8.26] — 2026-08-05
+
+### Added
+- **L1 hardening per CHAT-HARNESS.md laws 1–3 + 6 (WCH-1, gh#596).** `AgentEvent` gains two additive kinds — `progress` (closed, code-owned `ProgressStage` enum: `PROGRESS_STAGES` + `isProgressStage()` guard; the loop emits `sent`/`retry`/`tool`/`done` at its genuine natural points) and `surface` (one generative-UI wire line, envelope-keyed) — both render-only in `reduce()`. A byte-identity baseline gate (`baseline/prompt-equivalence.baseline.json` + `baseline.test.js`, regenerated via `scripts/build/regen-agent-baseline.mjs`) pins that every optional `AgentConfig` axis, when absent, leaves no trace on the derived `ChatOpts`. `frameClientMessage()` + `shouldRunTurn()` (`src/frame.ts`) map a surface action / function result / validation rejection to a distinct, deterministic natural-language user turn — silent-apply kinds (`dataModelUpdate`, `ack`) gate out before framing and throw if framed directly. `agent.sendClientMessage(session, msg)` wires gate → frame → loop.
+- **Initial release — the composable chat-agent harness (gh#579).** `createAgent()` assembles an agent from four declared parts on top of `@adia-ai/llm`: cache-aware prompt layers (`promptLayer`), a JSON-schema'd tool registry with local-fn and endpoint executors plus the bounded execute-and-feed-back loop (`defineTool`, `maxToolRounds`, `onToolCall` gate), declarative workflow cascades (`defineWorkflow` — `until` accepts / terminal steps / `when` skips), and resources in `attach` (application-controlled prompt layer) or `tool` (model-controlled `read_<name>`) mode. Ships the serializable `Session` + the one shared event reducer (`reduce`), and `scriptClient` for deterministic keyless tests.

package/README.md

@@ -0,0 +1,172 @@
+# `@adia-ai/agent`
+
+Composable chat-agent harness. Assemble an agent from four declared parts —
+**prompt layers**, **tools**, **workflows**, **resources** — on top of
+[`@adia-ai/llm`](../llm/README.md). The package owns the tool-call loop, the
+serializable `Session`, and the one shared event reducer; it renders nothing
+(pair it with `web-modules/chat` or any UI).
+
+> **Experimental** until the A2UI pipeline migration validates the contracts
+> (tracked in [gh#579](https://github.com/adiahealth/gen-ui-kit/issues/579)).
+
+## Install
+
+```bash
+npm install @adia-ai/agent
+```
+
+## Usage
+
+```js
+import {
+  createAgent, promptLayer, defineTool, defineWorkflow,
+  defineResource, reduce,
+} from '@adia-ai/agent';
+
+const agent = createAgent({
+  llm: { model: 'claude-sonnet-4-6', proxyUrl: '/api/chat' },
+  prompt: [
+    promptLayer('identity', 'You are the AdiaUI copilot.', { cache: true }),
+    promptLayer('context', () => new Date().toISOString()),   // per-turn, never cached
+  ],
+  tools: [
+    defineTool({
+      name: 'search_patients',
+      description: 'Find a patient by name or MRN',
+      inputSchema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
+      execute: async ({ q }) => lookup(q),                    // or endpoint: { url, method }
+    }),
+  ],
+  workflows: [
+    defineWorkflow('generate', [
+      { name: 'zettel',     run: zettel,     until: r => r.strategy === 'composition-match' },
+      { name: 'free-form',  run: freeForm,   until: r => r.ok },
+      { name: 'monolithic', run: monolithic },                // terminal — always accepted
+    ]),
+  ],
+  resources: [
+    defineResource({ name: 'visit-summary', mode: 'attach', get: fetchSummary }), // app-controlled
+    defineResource({ name: 'care-plan',     mode: 'tool',   get: readPlan }),     // model-controlled
+  ],
+  maxToolRounds: 8,
+});
+
+let session = agent.createSession();            // plain JSON-safe object — you own persistence
+for await (const event of agent.send(session, 'weather in Oslo?')) {
+  session = reduce(session, event);             // the one reducer — the single session writer
+  render(event);                                // text | thinking | tool_use | tool_result | done | error
+}
+await agent.run(session, 'generate', { intent });
+```
+
+## The four parts
+
+| Part | Declared with | What the harness does |
+|---|---|---|
+| Prompt | `promptLayer(name, text, {cache})` | Static layers first, `cache_control` on the last cached one (Anthropic block array; joined string elsewhere) |
+| Tools | `defineTool({name, inputSchema, execute\|endpoint})` | JSON-schema check at the call boundary, then the execute-and-feed-back loop (bounded by `maxToolRounds`; gate calls via `onToolCall`) |
+| Workflows | `defineWorkflow(name, steps)` | Sequential cascade — `until` accepts, absent `until` is terminal, `when` skips |
+| Resources | `defineResource({name, mode, get})` | `attach` → dynamic prompt layer each turn; `tool` → a read-only `read_<name>` tool |
+
+## Events
+
+`agent.send()` yields the `AgentEvent` union; `reduce(session, event)` folds it.
+Every failure inside a tool call becomes an `isError` `tool_result` the model
+can react to — the loop throws for nothing tool-shaped.
+
+```
+{ type:'message', role:'user', text }
+{ type:'text', text, snapshot } · { type:'thinking', text }
+{ type:'tool_use', id, name, input } · { type:'tool_result', id, name, output, isError? }
+{ type:'step', workflow, step, data? }
+{ type:'progress', stage } · { type:'surface', surfaceId, line }
+{ type:'done', text, usage, stopReason } · { type:'error', error }
+```
+
+`stopReason` passes through raw from the provider; the loop adds exactly one
+synthetic value, `max_tool_rounds`, when the bound is hit.
+
+`thinking` / `step` / `error` / `progress` / `surface` are render-only —
+`reduce()` folds them into no session change.
+
+### Progress events (CHAT-HARNESS law 3)
+
+`progress` carries a CLOSED, code-owned `stage`: one of `PROGRESS_STAGES`
+(`'sent' | 'started' | 'reasoning' | 'content' | 'validating' | 'retry' |
+'tool' | 'done'`), exported alongside the `isProgressStage()` guard so any
+reader — a deserialized wire message, a stored transcript — can drop an
+out-of-vocabulary value instead of rendering it. **Never render `stage` as
+label text directly**; a UI's label table is code-owned and keyed on these
+strings, never on model output (the honesty guard).
+
+The loop today emits only the stages it genuinely reaches — `sent` before
+every provider call, `retry` before a call that repeats a round after tool
+feedback, `tool` before each tool executes, `done` right before the
+terminal `done` event. `started` / `reasoning` / `content` / `validating`
+are declared in the vocabulary for future producers (the L1 loop doesn't
+independently observe those signals today, so it doesn't invent an
+emission point for them).
+
+### Surface events
+
+`{ type:'surface', surfaceId, line }` carries one generative-UI wire line
+for an envelope-keyed surface. This package only carries the event kind on
+the union — turning it into a rendered surface is L3's job
+(`web-modules/chat`, WCH-4), never this package's.
+
+### Framed client-message turns (CHAT-HARNESS law 6)
+
+A surface action, a function/tool result, or a validation rejection
+re-enters the agent as a *turn* — never a raw data blob — through one
+framing function:
+
+```js
+import { frameClientMessage, shouldRunTurn } from '@adia-ai/agent';
+
+const msg = { kind: 'surfaceAction', surfaceId: 'sf_1', action: 'submit', context: { formId: 'f1' } };
+if (shouldRunTurn(msg)) {
+  for await (const event of agent.sendClientMessage(session, msg)) { /* … */ }
+}
+```
+
+`ClientMessage` arms and their framed wording:
+
+| Kind | Framed turn |
+|---|---|
+| `surfaceAction` | `The user triggered the ${action} action on surface ${surfaceId} with context ${JSON(context)}.` |
+| `functionResult` | `The function ${call} returned: ${JSON(value)}.` |
+| `validationRejection` | `The previous surface was rejected (${code}): ${message}. Emit a corrected surface.` |
+| `dataModelUpdate`, `ack` | silent-apply — `shouldRunTurn` returns `false`; `frameClientMessage` **throws** if called on one directly |
+
+`agent.sendClientMessage(session, msg, opts?)` is the wired entry: it gates
+with `shouldRunTurn`, frames with `frameClientMessage`, then runs the same
+loop as `agent.send()`. A silent-apply message yields nothing and never
+touches the provider — the caller already applied it directly (e.g. to a
+surface's data-model store).
+
+## Byte-identity baseline (CHAT-HARNESS law 2)
+
+Every axis on `AgentConfig` is optional, and absence must produce a
+byte-identical request to before the axis existed. `baseline/prompt-
+equivalence.baseline.json` pins the exact `ChatOpts` a minimal config (one
+static prompt layer, nothing else) produces; `baseline.test.js` re-derives
+it every run and diffs byte-for-byte, including asserting no optional-axis
+key (`tools`, `cache`, `signal`, …) appears at all — not even as an empty
+array.
+
+Changing a default that legitimately changes this output breaks the test
+until the baseline is deliberately regenerated:
+
+```bash
+npm run build -w @adia-ai/agent
+node scripts/build/regen-agent-baseline.mjs
+```
+
+Never hand-edit the JSON file — regenerate it, then diff-review the change
+like any other pinned contract.
+
+## Testing
+
+`scriptClient(turns)` is a deterministic `LLMClient`: script `[{text, toolUse}]`
+turns and drive the whole loop keylessly. It also records every `ChatOpts` it
+was called with (`client.calls`) so tests can assert what reached the wire.

package/agent.d.ts

@@ -0,0 +1,53 @@
+/**
+ * createAgent — assemble a chat agent from the four declared parts.
+ *
+ * The agent owns wiring, not state: send() streams AgentEvents through the
+ * tool loop, run() drives a named workflow. The caller holds the Session
+ * and folds events with reduce() — the agent never mutates it.
+ *
+ * System-prompt shape is provider-decided here (the one place that knows
+ * the provider): Anthropic gets the block array with cache_control markers,
+ * everyone else gets the joined string.
+ */
+import type { ChatOpts, LLMClient, ToolUse } from '@adia-ai/llm';
+import { type PromptLayer } from './prompt.js';
+import { type ResourceDef } from './resource.js';
+import { type Session } from './session.js';
+import type { AgentEvent } from './events.js';
+import { type ClientMessage } from './frame.js';
+import type { ToolContext, ToolDef } from './tools.js';
+import { type Workflow, type WorkflowResult } from './workflow.js';
+export interface AgentConfig {
+    /** Client defaults (model, proxyUrl, apiKey…) handed to createClient(),
+     *  or a ready-made client under `client` (tests: scriptClient; browser
+     *  demos passing a client built from /packages/llm/index.js directly). */
+    llm: Partial<ChatOpts> | {
+        client: LLMClient;
+        model?: string;
+        provider?: string;
+    };
+    prompt?: PromptLayer[];
+    tools?: ToolDef[];
+    workflows?: Array<Workflow<never, never>> | Workflow[];
+    resources?: ResourceDef[];
+    maxToolRounds?: number;
+    /** Gate every tool call; false denies it (isError feedback, loop continues). */
+    onToolCall?: (call: ToolUse, ctx: ToolContext) => boolean | Promise<boolean>;
+}
+export interface SendOpts {
+    signal?: AbortSignal;
+}
+export interface Agent {
+    createSession(id?: string): Session;
+    send(session: Session, text: string, opts?: SendOpts): AsyncGenerator<AgentEvent>;
+    /** Law 6 — gates the message with `shouldRunTurn`, frames it with
+     *  `frameClientMessage`, then runs it through the same loop as `send`.
+     *  A silent-apply message (shouldRunTurn ⇒ false) yields nothing and
+     *  never touches the loop — the caller already applied it directly. */
+    sendClientMessage(session: Session, msg: ClientMessage, opts?: SendOpts): AsyncGenerator<AgentEvent>;
+    run<TResult = unknown>(session: Session, workflowName: string, input?: unknown, onEvent?: (event: AgentEvent) => void): Promise<WorkflowResult<TResult>>;
+    /** The assembled tool set (declared + tool-mode resources) — inspectable. */
+    tools: ToolDef[];
+}
+export declare function createAgent(config: AgentConfig): Agent;
+//# sourceMappingURL=agent.d.ts.map

package/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAYjE,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAe,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAIhF,MAAM,WAAW,WAAW;IAC1B;;8EAE0E;IAC1E,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClF,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC;IACvD,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAClF;;;2EAGuE;IACvE,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IACrG,GAAG,CAAC,OAAO,GAAG,OAAO,EACnB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GACpC,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,6EAA6E;IAC7E,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAgFtD"}

package/agent.js

@@ -0,0 +1,99 @@
+/**
+ * createAgent — assemble a chat agent from the four declared parts.
+ *
+ * The agent owns wiring, not state: send() streams AgentEvents through the
+ * tool loop, run() drives a named workflow. The caller holds the Session
+ * and folds events with reduce() — the agent never mutates it.
+ *
+ * System-prompt shape is provider-decided here (the one place that knows
+ * the provider): Anthropic gets the block array with cache_control markers,
+ * everyone else gets the joined string.
+ */
+let _llm = null;
+function llmModule() {
+    if (!_llm)
+        _llm = import('@adia-ai/llm').catch(() => null);
+    return _llm;
+}
+import { composeSystem } from './prompt.js';
+import { attachLayers, resourceTools } from './resource.js';
+import { createSession } from './session.js';
+import { frameClientMessage, shouldRunTurn } from './frame.js';
+import { runLoop } from './loop.js';
+import { runWorkflow } from './workflow.js';
+const DEFAULT_MAX_TOOL_ROUNDS = 8;
+export function createAgent(config) {
+    const hasClient = 'client' in config.llm && !!config.llm.client;
+    const model = config.llm.model;
+    const explicitProvider = config.llm.provider;
+    let _resolved = null;
+    async function resolveClient() {
+        if (_resolved)
+            return _resolved;
+        const mod = await llmModule();
+        const provider = explicitProvider ?? (model ? mod?.detectProviderFromModel(model) ?? undefined : undefined);
+        if (hasClient) {
+            _resolved = { client: config.llm.client, provider };
+        }
+        else {
+            if (!mod)
+                throw new Error('@adia-ai/llm is not available — build packages/llm, or pass llm.client');
+            _resolved = { client: mod.createClient(config.llm), provider };
+        }
+        return _resolved;
+    }
+    const layers = config.prompt ?? [];
+    const resources = config.resources ?? [];
+    const tools = [...(config.tools ?? []), ...resourceTools(resources)];
+    const workflows = new Map((config.workflows ?? []).map(w => [w.name, w]));
+    const maxToolRounds = config.maxToolRounds ?? DEFAULT_MAX_TOOL_ROUNDS;
+    async function chatOverrides(provider) {
+        const allLayers = [...layers, ...(await attachLayers(resources))];
+        if (!allLayers.length)
+            return {};
+        const composed = composeSystem(allLayers);
+        // Anthropic takes the block array (cache markers ride the blocks, so
+        // ChatOpts.cache stays off — the adapter's cache flag would re-wrap).
+        if (provider === 'anthropic')
+            return { system: composed.blocks, cache: false };
+        return { system: composed.text };
+    }
+    return {
+        tools,
+        createSession(id) {
+            return createSession(id);
+        },
+        async *send(session, text, opts = {}) {
+            yield { type: 'message', role: 'user', text };
+            const { client, provider } = await resolveClient();
+            const messages = [...session.messages, { role: 'user', content: text }];
+            const ctx = { sessionId: session.id, ...(opts.signal ? { signal: opts.signal } : {}) };
+            yield* runLoop(messages, {
+                client,
+                chat: await chatOverrides(provider),
+                tools,
+                maxToolRounds,
+                ...(config.onToolCall ? { onToolCall: config.onToolCall } : {}),
+                ctx,
+            });
+        },
+        async *sendClientMessage(session, msg, opts = {}) {
+            if (!shouldRunTurn(msg))
+                return;
+            const text = frameClientMessage(msg);
+            yield* this.send(session, text, opts);
+        },
+        async run(session, workflowName, input, onEvent) {
+            const workflow = workflows.get(workflowName);
+            if (!workflow) {
+                throw new Error(`Unknown workflow "${workflowName}". Declared: ${[...workflows.keys()].join(', ') || '(none)'}`);
+            }
+            return runWorkflow(workflow, {
+                input,
+                sessionId: session.id,
+                ...(onEvent ? { emit: (e) => onEvent(e) } : {}),
+            });
+        },
+    };
+}
+//# sourceMappingURL=agent.js.map

package/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["src/agent.ts"],"names":[],"mappings":"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"}

package/events.d.ts

@@ -0,0 +1,92 @@
+/**
+ * AgentEvent — the one stream contract, and reduce() — the one reducer.
+ *
+ * Every surface consuming an agent renders from this union and folds
+ * session state with this reducer; hand-written per-surface switches over
+ * ad-hoc event shapes are the defect class this module exists to kill.
+ *
+ * reduce() is pure: (session, event) → new session. The loop emits events
+ * but never touches the caller's Session — reduce is the single writer.
+ */
+import type { AdapterUsage } from '@adia-ai/llm';
+import type { Msg, Session } from './session.js';
+/** CHAT-HARNESS law 3 — the closed, code-owned progress vocabulary. Every
+ *  reader that renders labels does so from its OWN table keyed on these
+ *  strings — never from model text — and drops anything not in this array
+ *  (see `isProgressStage`). Extending this list is an amendment to the
+ *  ruled contract, not a routine addition. */
+export declare const PROGRESS_STAGES: readonly ["sent", "started", "reasoning", "content", "validating", "retry", "tool", "done"];
+export type ProgressStage = (typeof PROGRESS_STAGES)[number];
+/** Guard for any reader (a deserialized wire message, a stored transcript,
+ *  a future stage a newer producer emits) — out-of-vocabulary stages must
+ *  be droppable here rather than rendered blind. */
+export declare function isProgressStage(value: unknown): value is ProgressStage;
+export type AgentEvent = {
+    type: 'message';
+    role: 'user';
+    text: string;
+} | {
+    type: 'text';
+    text: string;
+    snapshot: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    id: string;
+    name: string;
+    output: string;
+    isError?: boolean;
+} | {
+    type: 'step';
+    workflow: string;
+    step: string;
+    data?: unknown;
+} | {
+    type: 'done';
+    text: string;
+    usage: AdapterUsage;
+    stopReason: string;
+} | {
+    type: 'error';
+    error: Error;
+}
+/** Law 3 — a closed-vocabulary progress marker; render-only, no session
+ *  effect (see reduce()). */
+ | {
+    type: 'progress';
+    stage: ProgressStage;
+}
+/** A generative-UI line for one envelope-keyed surface; render-only, no
+ *  session effect (see reduce()). Surface HOSTING (L3, WCH-4) owns
+ *  turning this into a rendered surface — this package only carries the
+ *  event kind on the union. */
+ | {
+    type: 'surface';
+    surfaceId: string;
+    line: string;
+};
+/** Fold one event into a Session. Message-building rules:
+ *  - `message`      → append the user message.
+ *  - `text`         → update the draft's text snapshot.
+ *  - `tool_use`     → flush draft text into parts, append the tool_use part.
+ *  - `tool_result`  → close the draft as an assistant message (first result
+ *                     after tool_use parts), then append to the tool message
+ *                     (consecutive results merge into ONE tool msg — the
+ *                     Anthropic wire requires alternating roles).
+ *  - `done`         → close any remaining draft as the final assistant msg.
+ *  - `thinking`/`step`/`error`/`progress`/`surface` → no session effect
+ *    (render-only events — `progress`/`surface` included by the same rule:
+ *    they narrate the turn in flight, they don't alter the transcript).
+ */
+export declare function reduce(session: Session, event: AgentEvent): Session;
+/** Convenience for the loop and tests: fold a whole event array. */
+export declare function reduceAll(session: Session, events: AgentEvent[]): Session;
+export type { Msg, Session };
+//# sourceMappingURL=events.d.ts.map

package/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAQ,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;8CAI8C;AAC9C,eAAO,MAAM,eAAe,6FAElB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;oDAEoD;AACpD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE;AACjC;6BAC6B;GAC3B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE;AAC5C;;;+BAG+B;GAC7B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAsEnE;AAED,oEAAoE;AACpE,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAIzE;AAED,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC"}

package/events.js

@@ -0,0 +1,112 @@
+/**
+ * AgentEvent — the one stream contract, and reduce() — the one reducer.
+ *
+ * Every surface consuming an agent renders from this union and folds
+ * session state with this reducer; hand-written per-surface switches over
+ * ad-hoc event shapes are the defect class this module exists to kill.
+ *
+ * reduce() is pure: (session, event) → new session. The loop emits events
+ * but never touches the caller's Session — reduce is the single writer.
+ */
+/** CHAT-HARNESS law 3 — the closed, code-owned progress vocabulary. Every
+ *  reader that renders labels does so from its OWN table keyed on these
+ *  strings — never from model text — and drops anything not in this array
+ *  (see `isProgressStage`). Extending this list is an amendment to the
+ *  ruled contract, not a routine addition. */
+export const PROGRESS_STAGES = [
+    'sent', 'started', 'reasoning', 'content', 'validating', 'retry', 'tool', 'done',
+];
+/** Guard for any reader (a deserialized wire message, a stored transcript,
+ *  a future stage a newer producer emits) — out-of-vocabulary stages must
+ *  be droppable here rather than rendered blind. */
+export function isProgressStage(value) {
+    return typeof value === 'string' && PROGRESS_STAGES.includes(value);
+}
+/** Fold one event into a Session. Message-building rules:
+ *  - `message`      → append the user message.
+ *  - `text`         → update the draft's text snapshot.
+ *  - `tool_use`     → flush draft text into parts, append the tool_use part.
+ *  - `tool_result`  → close the draft as an assistant message (first result
+ *                     after tool_use parts), then append to the tool message
+ *                     (consecutive results merge into ONE tool msg — the
+ *                     Anthropic wire requires alternating roles).
+ *  - `done`         → close any remaining draft as the final assistant msg.
+ *  - `thinking`/`step`/`error`/`progress`/`surface` → no session effect
+ *    (render-only events — `progress`/`surface` included by the same rule:
+ *    they narrate the turn in flight, they don't alter the transcript).
+ */
+export function reduce(session, event) {
+    switch (event.type) {
+        case 'message':
+            return {
+                ...session,
+                messages: [...session.messages, { role: 'user', content: event.text }],
+            };
+        case 'text': {
+            const draft = session.draft ?? { text: '', parts: [] };
+            return { ...session, draft: { ...draft, text: event.snapshot } };
+        }
+        case 'tool_use': {
+            const draft = session.draft ?? { text: '', parts: [] };
+            const parts = [...draft.parts];
+            if (draft.text && !parts.some(p => p.type === 'text')) {
+                parts.unshift({ type: 'text', text: draft.text });
+            }
+            parts.push({ type: 'tool_use', id: event.id, name: event.name, input: event.input });
+            return { ...session, draft: { text: draft.text, parts } };
+        }
+        case 'tool_result': {
+            const resultPart = {
+                type: 'tool_result',
+                toolUseId: event.id,
+                name: event.name,
+                content: event.output,
+                ...(event.isError ? { isError: true } : {}),
+            };
+            const messages = [...session.messages];
+            const draft = session.draft;
+            if (draft?.parts.length) {
+                messages.push({ role: 'assistant', content: draft.parts });
+            }
+            const last = messages[messages.length - 1];
+            if (draft?.parts.length || last?.role !== 'tool' || typeof last.content === 'string') {
+                messages.push({ role: 'tool', content: [resultPart] });
+            }
+            else {
+                messages[messages.length - 1] = { role: 'tool', content: [...last.content, resultPart] };
+            }
+            const next = { ...session, messages };
+            delete next.draft;
+            return next;
+        }
+        case 'done': {
+            const messages = [...session.messages];
+            const draft = session.draft;
+            if (draft?.parts.length) {
+                messages.push({ role: 'assistant', content: draft.parts });
+            }
+            else if (event.text || draft?.text) {
+                messages.push({ role: 'assistant', content: event.text || draft?.text || '' });
+            }
+            const next = { ...session, messages };
+            delete next.draft;
+            return next;
+        }
+        case 'thinking':
+        case 'step':
+        case 'error':
+        case 'progress':
+        case 'surface':
+            return session;
+        default:
+            return session;
+    }
+}
+/** Convenience for the loop and tests: fold a whole event array. */
+export function reduceAll(session, events) {
+    let next = session;
+    for (const event of events)
+        next = reduce(next, event);
+    return next;
+}
+//# sourceMappingURL=events.js.map

package/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["src/events.ts"],"names":[],"mappings":"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"}

package/frame.d.ts

@@ -0,0 +1,60 @@
+/**
+ * frameClientMessage / shouldRunTurn — law 6: framed client-message turns.
+ *
+ * The session is a plain serializable turn array (session.ts); every
+ * surface action, function/tool result, and validation rejection re-enters
+ * the loop as a *distinct natural-language user turn* through this ONE
+ * framing function — never scattered ad-hoc string-building at call sites.
+ *
+ * Silent-apply kinds (a data-model echo, an action-response ack the caller
+ * already consumed) never construct a turn at all: `shouldRunTurn` gates
+ * them out BEFORE framing is attempted, and `frameClientMessage` itself
+ * THROWS if handed one directly — a should-not-run message is
+ * unconstructable as a turn, not merely skipped. This mirrors the wire's
+ * own three-arm client vocabulary (action / error / functionResponse) one
+ * level up, in plain language the model reads as a user turn.
+ */
+export type ClientMessage = 
+/** A surface action fired (a button, a form submit) — carries the
+ *  action's declared context, already resolved off the surface's store. */
+{
+    kind: 'surfaceAction';
+    surfaceId: string;
+    action: string;
+    context?: unknown;
+}
+/** A model-callable function returned its result. */
+ | {
+    kind: 'functionResult';
+    call: string;
+    value: unknown;
+}
+/** A previously emitted surface failed validation — the harness asks for
+ *  a corrected one. */
+ | {
+    kind: 'validationRejection';
+    code: string;
+    message: string;
+}
+/** Silent-apply: a data-model value changed and was already applied to
+ *  the surface's store directly — no narration, no turn. */
+ | {
+    kind: 'dataModelUpdate';
+    surfaceId: string;
+    path?: string;
+    value: unknown;
+}
+/** Silent-apply: an action-response the caller already resolved off its
+ *  own promise — nothing left to narrate. */
+ | {
+    kind: 'ack';
+    actionId: string;
+};
+/** Gate BEFORE framing: false means this message applies silently and must
+ *  never reach `frameClientMessage`. */
+export declare function shouldRunTurn(msg: ClientMessage): boolean;
+/** Maps one client-message arm to its pinned natural-language user turn.
+ *  Deterministic — same input, same string, always — so golden tests can
+ *  pin the exact wording. Throws for any kind `shouldRunTurn` rejects. */
+export declare function frameClientMessage(msg: ClientMessage): string;
+//# sourceMappingURL=frame.d.ts.map

package/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["src/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,aAAa;AACvB;2EAC2E;AACzE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE;AACjF,qDAAqD;GACnD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAC1D;uBACuB;GACrB;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAChE;4DAC4D;GAC1D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AAC/E;6CAC6C;GAC3C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAItC;wCACwC;AACxC,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAEzD;AAED;;0EAE0E;AAC1E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAsB7D"}