@hamak/ai-agent-backend 0.9.3 → 0.9.5

package/dist/anthropic-provider.d.ts

@@ -8,10 +8,24 @@
  *
  * Wire format (POST https://api.anthropic.com/v1/messages):
  *   headers: x-api-key, anthropic-version: 2023-06-01, content-type: json
- *   body:    { model, max_tokens, system?, messages, stream }
+ *   body:    { model, max_tokens, system?, tools?, messages, stream }
+ *   tools:   [{ name, description, input_schema }] — sent only when the loop
+ *            advertises tools (`CompleteOpts.tools`).
+ *   reply:   content blocks `text` and `tool_use { id, name, input }`;
+ *            `stop_reason: "tool_use"` when the model wants a tool run.
  *   stream:  SSE — message_start (usage.input_tokens),
- *            content_block_delta/text_delta (delta.text),
- *            message_delta (usage.output_tokens), message_stop.
+ *            content_block_start (tool_use: id + name),
+ *            content_block_delta/text_delta (delta.text) or
+ *            content_block_delta/input_json_delta (delta.partial_json),
+ *            content_block_stop, message_delta (usage.output_tokens),
+ *            message_stop.
+ *
+ * History mapping (issue #52): assistant turns that called tools are sent as
+ * `[text?, tool_use…]` blocks and the `role: 'tool'` results that follow are
+ * grouped into ONE user message of `tool_result` blocks — the API rejects a
+ * `tool_result` that does not answer a `tool_use` in the immediately preceding
+ * assistant turn, and rejects consecutive same-role turns, so both invariants
+ * are enforced in {@link toAnthropicMessages}.
  *
  * Note: Opus 4.8 / 4.7 reject `temperature`/`top_p` (400), so `temperature` is
  * sent only when explicitly configured. Default model: claude-opus-4-8.

package/dist/anthropic-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic-provider.d.ts","sourceRoot":"","sources":["../src/anthropic-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,iBAAiB,CAAC;AAOzB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AA4BD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,MAAM,GAAE,uBAA4B;IAchD,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,IAAI;IAYN,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAgC3E,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,UAAU,CAAC;CAgDvF"}
+{"version":3,"file":"anthropic-provider.d.ts","sourceRoot":"","sources":["../src/anthropic-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EAIZ,MAAM,iBAAiB,CAAC;AASzB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAuMD,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;gBAExB,MAAM,GAAE,uBAA4B;IAchD,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,IAAI;IAaN,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA8C3E,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,YAAY,GAAG,aAAa,CAAC,UAAU,CAAC;CA0FvF"}

package/dist/anthropic-provider.js

@@ -8,10 +8,24 @@
  *
  * Wire format (POST https://api.anthropic.com/v1/messages):
  *   headers: x-api-key, anthropic-version: 2023-06-01, content-type: json
- *   body:    { model, max_tokens, system?, messages, stream }
+ *   body:    { model, max_tokens, system?, tools?, messages, stream }
+ *   tools:   [{ name, description, input_schema }] — sent only when the loop
+ *            advertises tools (`CompleteOpts.tools`).
+ *   reply:   content blocks `text` and `tool_use { id, name, input }`;
+ *            `stop_reason: "tool_use"` when the model wants a tool run.
  *   stream:  SSE — message_start (usage.input_tokens),
- *            content_block_delta/text_delta (delta.text),
- *            message_delta (usage.output_tokens), message_stop.
+ *            content_block_start (tool_use: id + name),
+ *            content_block_delta/text_delta (delta.text) or
+ *            content_block_delta/input_json_delta (delta.partial_json),
+ *            content_block_stop, message_delta (usage.output_tokens),
+ *            message_stop.
+ *
+ * History mapping (issue #52): assistant turns that called tools are sent as
+ * `[text?, tool_use…]` blocks and the `role: 'tool'` results that follow are
+ * grouped into ONE user message of `tool_result` blocks — the API rejects a
+ * `tool_result` that does not answer a `tool_use` in the immediately preceding
+ * assistant turn, and rejects consecutive same-role turns, so both invariants
+ * are enforced in {@link toAnthropicMessages}.
  *
  * Note: Opus 4.8 / 4.7 reject `temperature`/`top_p` (400), so `temperature` is
  * sent only when explicitly configured. Default model: claude-opus-4-8.
@@ -20,21 +34,160 @@ import { fetchWithRetry } from '@hamak/ai-agent';
 const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
 const ANTHROPIC_VERSION = '2023-06-01';
 const DEFAULT_MAX_TOKENS = 4096;
-/** Map agent messages to Anthropic's user/assistant turns. */
+/** Schema sent for a tool that declares none — the API requires an object schema. */
+const EMPTY_INPUT_SCHEMA = { type: 'object', properties: {} };
+// ---------------------------------------------------------------------------
+// Request mapping
+// ---------------------------------------------------------------------------
+function toAnthropicTools(tools) {
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.inputSchema ?? EMPTY_INPUT_SCHEMA,
+    }));
+}
+/**
+ * Map agent messages to Anthropic's user/assistant turns.
+ *
+ * Invariants enforced (the API 400s otherwise):
+ *  - `system` messages are dropped here (sent in the top-level `system` field);
+ *  - assistant `toolCalls` become `tool_use` blocks, and the `role: 'tool'`
+ *    messages that follow are grouped into ONE user message of `tool_result`
+ *    blocks, each paired with a `tool_use` id of that assistant turn;
+ *  - a `tool_use` with no recorded result gets an `is_error` placeholder so the
+ *    pairing stays complete; a result with no matching call is sent as text;
+ *  - adjacent same-role turns are merged; the first turn is always `user`;
+ *  - empty assistant turns (e.g. an aborted stream) are skipped.
+ */
 function toAnthropicMessages(messages) {
     const out = [];
-    for (const m of messages) {
+    const push = (role, blocks) => {
+        if (blocks.length === 0)
+            return;
+        const last = out[out.length - 1];
+        if (last && last.role === role) {
+            last.content = [...asBlocks(last.content), ...blocks];
+        }
+        else {
+            out.push({ role, content: blocks });
+        }
+    };
+    /** Ids of the tool_use blocks in the latest assistant turn, awaiting results. */
+    let openCalls = [];
+    for (let i = 0; i < messages.length; i += 1) {
+        const m = messages[i];
         if (m.role === 'system')
-            continue; // system is passed separately
-        // tool results are surfaced as plain user text in this text-only skeleton
-        out.push({ role: m.role === 'assistant' ? 'assistant' : 'user', content: m.content });
+            continue;
+        if (m.role === 'assistant') {
+            const blocks = [];
+            if (m.content)
+                blocks.push({ type: 'text', text: m.content });
+            for (const call of m.toolCalls ?? []) {
+                blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input ?? {} });
+            }
+            if (blocks.length === 0)
+                continue; // aborted / in-progress placeholder
+            // Close any still-open calls before starting a new assistant turn.
+            push('user', placeholders(openCalls));
+            openCalls = (m.toolCalls ?? []).map((c) => c.id);
+            push('assistant', blocks);
+            continue;
+        }
+        if (m.role === 'tool') {
+            // Gather the whole run of consecutive tool results into one user turn.
+            const results = [];
+            const orphans = [];
+            let j = i;
+            while (j < messages.length && messages[j].role === 'tool') {
+                const t = messages[j];
+                const idx = t.toolCallId ? openCalls.indexOf(t.toolCallId) : -1;
+                if (idx !== -1 && t.toolCallId) {
+                    openCalls.splice(idx, 1);
+                    results.push({ type: 'tool_result', tool_use_id: t.toolCallId, content: t.content });
+                }
+                else if (t.content) {
+                    orphans.push({ type: 'text', text: t.content });
+                }
+                j += 1;
+            }
+            i = j - 1;
+            // Every tool_use must be answered in this same user message.
+            results.push(...placeholders(openCalls));
+            openCalls = [];
+            push('user', [...results, ...orphans]);
+            continue;
+        }
+        // user
+        push('user', placeholders(openCalls));
+        openCalls = [];
+        if (m.content)
+            push('user', [{ type: 'text', text: m.content }]);
     }
+    // Trailing unanswered calls (the loop always records results before the next
+    // provider call, so this only guards a truncated history).
+    push('user', placeholders(openCalls));
     // The Messages API requires the first turn to be `user`.
     if (out.length > 0 && out[0].role !== 'user') {
         out.unshift({ role: 'user', content: '(context)' });
     }
+    // Collapse text-only turns to plain strings (smaller payload, stable shape).
+    for (const turn of out)
+        turn.content = collapse(turn.content);
     return out;
 }
+function placeholders(ids) {
+    return ids.map((id) => ({
+        type: 'tool_result',
+        tool_use_id: id,
+        content: 'No result was recorded for this tool call.',
+        is_error: true,
+    }));
+}
+function asBlocks(content) {
+    return typeof content === 'string' ? [{ type: 'text', text: content }] : content;
+}
+function collapse(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content.every((b) => b.type === 'text')) {
+        return content.map((b) => b.text).join('\n\n');
+    }
+    return content;
+}
+// ---------------------------------------------------------------------------
+// Response mapping
+// ---------------------------------------------------------------------------
+/**
+ * Parse a streamed `tool_use` input. Unparsable JSON is an error, never a
+ * tool call: executing a tool with garbage input is worse than failing the
+ * turn, and a truncated input is handled by the caller via `stop_reason`.
+ */
+function parseToolInput(raw, call) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        throw new Error(`[anthropic] tool_use input for "${call.name}" (${call.id}) is not valid JSON`);
+    }
+}
+/** Map the wire `stop_reason` to the provider-neutral {@link StopReason}. */
+function toStopReason(raw) {
+    switch (raw) {
+        case 'end_turn':
+        case 'tool_use':
+        case 'max_tokens':
+        case 'refusal':
+        case 'stop_sequence':
+            return raw;
+        default:
+            // `pause_turn` (server-tool long turns: resend to continue) and anything
+            // newer are left undefined rather than mistaken for a finished turn.
+            return undefined;
+    }
+}
 let seq = 0;
 function genId() {
     seq += 1;
@@ -70,6 +223,7 @@ export class AnthropicProvider {
             ...(opts.systemPrompt ? { system: opts.systemPrompt } : {}),
             // Only send temperature when explicitly set — Opus 4.8/4.7 reject it.
             ...(opts.temperature != null ? { temperature: opts.temperature } : {}),
+            ...(opts.tools && opts.tools.length > 0 ? { tools: toAnthropicTools(opts.tools) } : {}),
             messages: toAnthropicMessages(messages),
             stream,
         });
@@ -85,17 +239,32 @@ export class AnthropicProvider {
             throw new Error(`[anthropic] ${res.status} ${res.statusText}: ${await safeText(res)}`);
         }
         const json = (await res.json());
-        const content = (json.content ?? [])
+        const blocks = json.content ?? [];
+        const stopReason = toStopReason(json.stop_reason);
+        const content = blocks
             .filter((b) => b.type === 'text')
             .map((b) => b.text ?? '')
             .join('');
+        // A `max_tokens` stop can leave a tool_use block with a cut-off input; the
+        // JSON body gives no per-block completeness signal, so no tool call from
+        // such a response is executed — the stop reason tells the loop why.
+        const toolCalls = stopReason === 'max_tokens'
+            ? []
+            : blocks
+                .filter((b) => b.type === 'tool_use')
+                .map((b, n) => ({ id: b.id ?? `toolu-${genId()}-${n}`, name: b.name ?? '', input: b.input ?? {} }));
         return {
             message: {
                 id: genId(),
                 role: 'assistant',
                 content,
+                ...(toolCalls.length > 0
+                    ? { toolCalls: toolCalls.map((c) => ({ id: c.id, name: c.name, input: c.input })) }
+                    : {}),
                 createdAt: new Date().toISOString(),
             },
+            ...(toolCalls.length > 0 ? { toolCalls } : {}),
+            ...(stopReason ? { stopReason } : {}),
             usage: {
                 inputTokens: json.usage?.input_tokens ?? 0,
                 outputTokens: json.usage?.output_tokens ?? 0,
@@ -118,6 +287,10 @@ export class AnthropicProvider {
         let buffer = '';
         let inputTokens = 0;
         let outputTokens = 0;
+        /** In-flight `tool_use` blocks keyed by content-block index. */
+        const pending = new Map();
+        const toolCalls = [];
+        let stopReason;
         try {
             for (;;) {
                 const { value, done } = await reader.read();
@@ -134,15 +307,45 @@ export class AnthropicProvider {
                     if (!payload || payload === '[DONE]')
                         continue;
                     const evt = JSON.parse(payload);
+                    const index = evt.index ?? 0;
                     if (evt.type === 'message_start') {
                         inputTokens = evt.message?.usage?.input_tokens ?? inputTokens;
                     }
-                    else if (evt.type === 'content_block_delta' && evt.delta?.type === 'text_delta') {
-                        if (evt.delta.text)
-                            yield { type: 'text-delta', delta: evt.delta.text };
+                    else if (evt.type === 'content_block_start') {
+                        if (evt.content_block?.type === 'tool_use') {
+                            pending.set(index, {
+                                id: evt.content_block.id ?? `toolu-${genId()}-${index}`,
+                                name: evt.content_block.name ?? '',
+                                json: '',
+                            });
+                        }
+                        else if (evt.content_block?.type === 'text' && evt.content_block.text) {
+                            yield { type: 'text-delta', delta: evt.content_block.text };
+                        }
+                    }
+                    else if (evt.type === 'content_block_delta') {
+                        if (evt.delta?.type === 'text_delta') {
+                            if (evt.delta.text)
+                                yield { type: 'text-delta', delta: evt.delta.text };
+                        }
+                        else if (evt.delta?.type === 'input_json_delta') {
+                            const p = pending.get(index);
+                            if (p)
+                                p.json += evt.delta.partial_json ?? '';
+                        }
+                    }
+                    else if (evt.type === 'content_block_stop') {
+                        const p = pending.get(index);
+                        if (p) {
+                            pending.delete(index);
+                            const call = { id: p.id, name: p.name, input: parseToolInput(p.json, p) };
+                            toolCalls.push(call);
+                            yield { type: 'tool-call', call };
+                        }
                     }
                     else if (evt.type === 'message_delta') {
                         outputTokens = evt.usage?.output_tokens ?? outputTokens;
+                        stopReason = toStopReason(evt.delta?.stop_reason) ?? stopReason;
                     }
                 }
             }
@@ -150,9 +353,21 @@ export class AnthropicProvider {
         finally {
             reader.releaseLock();
         }
+        // A tool_use block that never got its `content_block_stop` has an
+        // incomplete input. Cut off by the token limit it is dropped (the loop sees
+        // `stopReason: 'max_tokens'`); any other cause is a broken stream.
+        if (pending.size > 0 && stopReason !== 'max_tokens') {
+            const names = [...pending.values()].map((p) => p.name).join(', ');
+            throw new Error(`[anthropic] stream ended before the tool_use input for ${names} was complete`);
+        }
         const usage = { inputTokens, outputTokens };
         yield { type: 'usage', usage };
-        yield { type: 'done', usage };
+        yield {
+            type: 'done',
+            ...(toolCalls.length > 0 ? { toolCalls } : {}),
+            ...(stopReason ? { stopReason } : {}),
+            usage,
+        };
     }
 }
 async function safeText(res) {

package/dist/create-agent-backend.d.ts

@@ -22,8 +22,14 @@ export interface AgentBackendConfig {
     tools?: IAgentTool[];
     /**
      * Tool approval gate (§6) applied to backend *and* frontend (split-loop)
-     * tools. Omitted = allow everything (back-compat). Pass a
-     * `DefaultToolAuthorizer` to get the policy-driven review flow.
+     * tools. Omitted = allow everything (back-compat).
+     *
+     * An authorizer that *reviews* (rather than auto-allowing) suspends the run
+     * until an approve/deny arrives, and only `createAgentChannelRoutes` carries
+     * those: its `POST /commands` relays the full `AgentCommand` set. Mounting a
+     * reviewing authorizer behind `createAgentRoutes` alone — whose `/chat` SSE
+     * relays only `token`/`usage`/`turn-end` — leaves the caller with a request
+     * that never completes, because nothing can deliver the decision.
      */
     authorizer?: IToolAuthorizer;
 }

package/dist/create-agent-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-agent-backend.d.ts","sourceRoot":"","sources":["../src/create-agent-backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAqB,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACpC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAgC3E"}
+{"version":3,"file":"create-agent-backend.d.ts","sourceRoot":"","sources":["../src/create-agent-backend.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAqB,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,SAAS,CAAC,EAAE,uBAAuB,CAAC;IACpC,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACpC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAgC3E"}

package/dist/file-agent-memory.d.ts

@@ -5,21 +5,70 @@
  *
  * This is the backend analogue of the frontend's `StoreFsMemory` — same
  * `IAgentMemory` contract, different substrate (node `fs` vs the virtual store).
+ *
+ * Durability model (issue #53):
+ *  - **Atomic writes.** Every write goes to a unique `<file>.<pid>.<n>.tmp` in
+ *    the *same* directory, is flushed with `fsync`, and is then `rename`d over
+ *    the target. `rename` within a directory is atomic, so a reader (or a crash)
+ *    never observes a half-written conversation — it sees the previous complete
+ *    file or the new complete file. The temp file is removed if anything fails.
+ *  - **Per-conversation serialisation.** Every read-modify-write method runs
+ *    through a promise chain keyed by `(agentId, sessionId)`, so concurrent
+ *    `append()`s apply in call order instead of racing and dropping messages.
+ *    The chain entry is dropped once it drains, so the map cannot grow forever.
+ *
+ * The on-disk format is unchanged from 0.9.3: a single pretty-printed JSON
+ * `Conversation` document per file. That keeps every existing reader (and the
+ * fixtures) working; the cost is O(n) bytes rewritten per append, which is
+ * accepted for now — correctness first, an append-only log can come later
+ * behind the same class.
  */
-import type { AgentMessage, Conversation, ConversationSummary, ConversationUsage } from '@hamak/ai-agent';
+import type { AgentMessage, CompactionCheckpoint, Conversation, ConversationSummary, ConversationUsage, InterAgentMessage, PendingApproval } from '@hamak/ai-agent';
 import type { IAgentMemory } from '@hamak/ai-agent/spi';
 export declare class FileAgentMemory implements IAgentMemory {
     private readonly root;
+    /**
+     * Tail of the in-flight operation chain per `(agentId, sessionId)`. Never
+     * rejects (failures are swallowed on the chain copy so one failed write does
+     * not poison the queue); the caller still gets the real rejection.
+     */
+    private readonly chains;
     constructor(root: string);
     private dir;
     private file;
+    private key;
+    /**
+     * Run `task` after every previously queued task for this conversation. Errors
+     * propagate to the caller but do not break the chain for later tasks.
+     */
+    private serialize;
     get(agentId: string, sessionId: string): Promise<Conversation | null>;
     load(agentId: string, sessionId: string): Promise<AgentMessage[]>;
+    /**
+     * Write `data` to `file` atomically: temp file in the same directory, fsync,
+     * rename. The temp file is cleaned up on every failure path.
+     */
+    private writeFileAtomic;
     private write;
+    /**
+     * Read-modify-write helper: loads the conversation, hands it to `mutate`, and
+     * writes back whatever `mutate` returns (returning `null` writes nothing).
+     * Always runs inside the per-conversation chain.
+     */
+    private mutate;
     append(agentId: string, sessionId: string, message: AgentMessage): Promise<void>;
     update(agentId: string, sessionId: string, messageId: string, changes: Partial<Pick<AgentMessage, 'content' | 'toolCalls'>>): Promise<void>;
     patch(agentId: string, sessionId: string, changes: Partial<Pick<Conversation, 'title' | 'pinned' | 'systemPrompt'>>): Promise<void>;
+    /** Replace the pending-approval list (ticket 009 §4). */
+    setPendingApprovals(agentId: string, sessionId: string, pending: PendingApproval[]): Promise<void>;
+    /** Record an inter-agent communication edge (ticket 009 §5.3). */
+    appendInterAgentMessage(agentId: string, sessionId: string, message: InterAgentMessage): Promise<void>;
+    /** Replace a conversation wholesale with a domain record (ticket 009 §8). */
+    hydrate(agentId: string, sessionId: string, conversation: Conversation): Promise<void>;
+    /** Replace the cumulative token usage (absolute, so replays stay idempotent). */
     setUsage(agentId: string, sessionId: string, usage: ConversationUsage): Promise<void>;
+    /** Replace the context-compaction checkpoint (absolute, not a delta). */
+    setCompaction(agentId: string, sessionId: string, compaction: CompactionCheckpoint): Promise<void>;
     reset(agentId: string, sessionId: string): Promise<void>;
     list(agentId: string): Promise<ConversationSummary[]>;
 }

package/dist/file-agent-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-agent-memory.d.ts","sourceRoot":"","sources":["../src/file-agent-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE1G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAoBxD,qBAAa,eAAgB,YAAW,YAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAEzC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,IAAI;IAIN,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAUrE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAIzD,KAAK;IAKb,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhF,MAAM,CACV,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,GAC5D,OAAO,CAAC,IAAI,CAAC;IAUV,KAAK,CACT,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,QAAQ,GAAG,cAAc,CAAC,CAAC,GACxE,OAAO,CAAC,IAAI,CAAC;IAMV,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;CAuB5D"}
+{"version":3,"file":"file-agent-memory.d.ts","sourceRoot":"","sources":["../src/file-agent-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAuBxD,qBAAa,eAAgB,YAAW,YAAY;IAQtC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoC;gBAE9B,IAAI,EAAE,MAAM;IAEzC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,GAAG;IAIX;;;OAGG;IACH,OAAO,CAAC,SAAS;IAkBX,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAUrE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAIvE;;;OAGG;YACW,eAAe;YA8Bf,KAAK;IAKnB;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAaR,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhF,MAAM,CACV,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,GAC5D,OAAO,CAAC,IAAI,CAAC;IAWV,KAAK,CACT,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,QAAQ,GAAG,cAAc,CAAC,CAAC,GACxE,OAAO,CAAC,IAAI,CAAC;IAMhB,yDAAyD;IACnD,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,eAAe,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC;IAShB,kEAAkE;IAC5D,uBAAuB,CAC3B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAShB,6EAA6E;IACvE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5F,iFAAiF;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3F,yEAAyE;IACnE,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,oBAAoB,GAC/B,OAAO,CAAC,IAAI,CAAC;IAMV,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;CAuB5D"}

package/dist/file-agent-memory.js

@@ -5,6 +5,23 @@
  *
  * This is the backend analogue of the frontend's `StoreFsMemory` — same
  * `IAgentMemory` contract, different substrate (node `fs` vs the virtual store).
+ *
+ * Durability model (issue #53):
+ *  - **Atomic writes.** Every write goes to a unique `<file>.<pid>.<n>.tmp` in
+ *    the *same* directory, is flushed with `fsync`, and is then `rename`d over
+ *    the target. `rename` within a directory is atomic, so a reader (or a crash)
+ *    never observes a half-written conversation — it sees the previous complete
+ *    file or the new complete file. The temp file is removed if anything fails.
+ *  - **Per-conversation serialisation.** Every read-modify-write method runs
+ *    through a promise chain keyed by `(agentId, sessionId)`, so concurrent
+ *    `append()`s apply in call order instead of racing and dropping messages.
+ *    The chain entry is dropped once it drains, so the map cannot grow forever.
+ *
+ * The on-disk format is unchanged from 0.9.3: a single pretty-printed JSON
+ * `Conversation` document per file. That keeps every existing reader (and the
+ * fixtures) working; the cost is O(n) bytes rewritten per append, which is
+ * accepted for now — correctness first, an append-only log can come later
+ * behind the same class.
  */
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
@@ -25,9 +42,17 @@ function safeSegment(seg) {
     }
     return seg;
 }
+/** Process-wide temp-file counter, so two instances never collide on a name. */
+let tmpCounter = 0;
 export class FileAgentMemory {
     constructor(root) {
         this.root = root;
+        /**
+         * Tail of the in-flight operation chain per `(agentId, sessionId)`. Never
+         * rejects (failures are swallowed on the chain copy so one failed write does
+         * not poison the queue); the caller still gets the real rejection.
+         */
+        this.chains = new Map();
     }
     dir(agentId) {
         return path.join(this.root, safeSegment(agentId));
@@ -35,6 +60,28 @@ export class FileAgentMemory {
     file(agentId, sessionId) {
         return path.join(this.dir(agentId), `${safeSegment(sessionId)}.json`);
     }
+    key(agentId, sessionId) {
+        return `${agentId}\u0000${sessionId}`;
+    }
+    /**
+     * Run `task` after every previously queued task for this conversation. Errors
+     * propagate to the caller but do not break the chain for later tasks.
+     */
+    serialize(agentId, sessionId, task) {
+        // Validate eagerly so traversal attempts reject before touching the queue.
+        this.file(agentId, sessionId);
+        const key = this.key(agentId, sessionId);
+        const prev = this.chains.get(key) ?? Promise.resolve();
+        const run = prev.then(task);
+        const settled = run.then(() => undefined, () => undefined);
+        this.chains.set(key, settled);
+        void settled.then(() => {
+            // Only the last task in the chain clears the entry.
+            if (this.chains.get(key) === settled)
+                this.chains.delete(key);
+        });
+        return run;
+    }
     async get(agentId, sessionId) {
         try {
             const raw = await fs.readFile(this.file(agentId, sessionId), 'utf8');
@@ -49,56 +96,133 @@ export class FileAgentMemory {
     async load(agentId, sessionId) {
         return (await this.get(agentId, sessionId))?.messages ?? [];
     }
+    /**
+     * Write `data` to `file` atomically: temp file in the same directory, fsync,
+     * rename. The temp file is cleaned up on every failure path.
+     */
+    async writeFileAtomic(file, data) {
+        tmpCounter += 1;
+        const tmp = `${file}.${process.pid}.${tmpCounter}.tmp`;
+        try {
+            const handle = await fs.open(tmp, 'w');
+            try {
+                await handle.writeFile(data, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await fs.rename(tmp, file);
+        }
+        catch (err) {
+            await fs.rm(tmp, { force: true }).catch(() => undefined);
+            throw err;
+        }
+        // Best-effort: flush the directory entry so the rename itself is durable.
+        // Not supported everywhere (Windows), hence the swallow.
+        try {
+            const dirHandle = await fs.open(path.dirname(file), 'r');
+            try {
+                await dirHandle.sync();
+            }
+            finally {
+                await dirHandle.close();
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
     async write(agentId, sessionId, conv) {
         await fs.mkdir(this.dir(agentId), { recursive: true });
-        await fs.writeFile(this.file(agentId, sessionId), JSON.stringify(conv, null, 2), 'utf8');
+        await this.writeFileAtomic(this.file(agentId, sessionId), JSON.stringify(conv, null, 2));
+    }
+    /**
+     * Read-modify-write helper: loads the conversation, hands it to `mutate`, and
+     * writes back whatever `mutate` returns (returning `null` writes nothing).
+     * Always runs inside the per-conversation chain.
+     */
+    mutate(agentId, sessionId, mutate) {
+        return this.serialize(agentId, sessionId, async () => {
+            const existing = await this.get(agentId, sessionId);
+            const next = mutate(existing);
+            if (!next)
+                return;
+            await this.write(agentId, sessionId, next);
+        });
     }
     async append(agentId, sessionId, message) {
-        const now = nowIso();
-        const existing = await this.get(agentId, sessionId);
-        if (existing) {
-            existing.messages.push(message);
-            existing.updatedAt = now;
-            if (existing.title === '' && message.role === 'user') {
-                existing.title = deriveTitle(message.content);
+        return this.mutate(agentId, sessionId, (existing) => {
+            const now = nowIso();
+            if (existing) {
+                existing.messages.push(message);
+                existing.updatedAt = now;
+                if (existing.title === '' && message.role === 'user') {
+                    existing.title = deriveTitle(message.content);
+                }
+                return existing;
             }
-            await this.write(agentId, sessionId, existing);
-            return;
-        }
-        await this.write(agentId, sessionId, {
-            schemaVersion: CONVERSATION_SCHEMA_VERSION,
-            id: sessionId,
-            title: message.role === 'user' ? deriveTitle(message.content) : '',
-            messages: [message],
-            createdAt: now,
-            updatedAt: now,
+            return {
+                schemaVersion: CONVERSATION_SCHEMA_VERSION,
+                id: sessionId,
+                title: message.role === 'user' ? deriveTitle(message.content) : '',
+                messages: [message],
+                createdAt: now,
+                updatedAt: now,
+            };
         });
     }
     async update(agentId, sessionId, messageId, changes) {
-        const existing = await this.get(agentId, sessionId);
-        if (!existing)
-            return;
-        const idx = existing.messages.findIndex((m) => m.id === messageId);
-        if (idx === -1)
-            return;
-        existing.messages[idx] = { ...existing.messages[idx], ...changes };
-        existing.updatedAt = nowIso();
-        await this.write(agentId, sessionId, existing);
+        return this.mutate(agentId, sessionId, (existing) => {
+            if (!existing)
+                return null;
+            const idx = existing.messages.findIndex((m) => m.id === messageId);
+            if (idx === -1)
+                return null;
+            existing.messages[idx] = { ...existing.messages[idx], ...changes };
+            existing.updatedAt = nowIso();
+            return existing;
+        });
     }
     async patch(agentId, sessionId, changes) {
-        const existing = await this.get(agentId, sessionId);
-        if (!existing)
-            return;
-        await this.write(agentId, sessionId, { ...existing, ...changes, updatedAt: nowIso() });
+        return this.mutate(agentId, sessionId, (existing) => existing ? { ...existing, ...changes, updatedAt: nowIso() } : null);
+    }
+    /** Replace the pending-approval list (ticket 009 §4). */
+    async setPendingApprovals(agentId, sessionId, pending) {
+        return this.mutate(agentId, sessionId, (existing) => {
+            if (!existing)
+                return null;
+            existing.pendingApprovals = pending;
+            existing.updatedAt = nowIso();
+            return existing;
+        });
+    }
+    /** Record an inter-agent communication edge (ticket 009 §5.3). */
+    async appendInterAgentMessage(agentId, sessionId, message) {
+        return this.mutate(agentId, sessionId, (existing) => {
+            if (!existing)
+                return null;
+            existing.interAgentMessages = [...(existing.interAgentMessages ?? []), message];
+            existing.updatedAt = nowIso();
+            return existing;
+        });
+    }
+    /** Replace a conversation wholesale with a domain record (ticket 009 §8). */
+    async hydrate(agentId, sessionId, conversation) {
+        return this.mutate(agentId, sessionId, () => ({ ...conversation }));
     }
+    /** Replace the cumulative token usage (absolute, so replays stay idempotent). */
     async setUsage(agentId, sessionId, usage) {
-        const existing = await this.get(agentId, sessionId);
-        if (!existing)
-            return;
-        await this.write(agentId, sessionId, { ...existing, usage, updatedAt: nowIso() });
+        return this.mutate(agentId, sessionId, (existing) => existing ? { ...existing, usage, updatedAt: nowIso() } : null);
+    }
+    /** Replace the context-compaction checkpoint (absolute, not a delta). */
+    async setCompaction(agentId, sessionId, compaction) {
+        return this.mutate(agentId, sessionId, (existing) => existing ? { ...existing, compaction, updatedAt: nowIso() } : null);
     }
     async reset(agentId, sessionId) {
-        await fs.rm(this.file(agentId, sessionId), { force: true });
+        return this.serialize(agentId, sessionId, async () => {
+            await fs.rm(this.file(agentId, sessionId), { force: true });
+        });
     }
     async list(agentId) {
         let names;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamak/ai-agent-backend",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "private": false,
   "type": "module",
   "description": "Backend for @hamak/ai-agent: hosted-model providers (Anthropic), durable memory, and an Express agent-chat route",
@@ -21,8 +21,10 @@
   "scripts": {
     "build": "tsc && node ../../../../scripts/fix-esm-extensions.mjs ./dist",
     "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "npm run typecheck && vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "node ../../../../scripts/check-publish-integrity.mjs"
   },
   "exports": {
     ".": {