@namzu/sdk 2.0.0 → 3.0.0

package/dist/runtime/query/__tests__/wiring-seams.test.js

@@ -0,0 +1,237 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import { MockLLMProvider } from '../../../provider/mock.js';
+import { ToolRegistry } from '../../../registry/tool/execute.js';
+import { DiskCheckpointStore } from '../../../store/run/checkpoint-disk.js';
+import { createUserMessage } from '../../../types/message/index.js';
+import { findPendingCheckpoint } from '../checkpoint.js';
+import { drainQuery } from '../index.js';
+/**
+ * Four defects that every unit test in this repo missed for the same
+ * reason: the tests construct the internal class directly, so they prove
+ * the helper works and prove nothing about whether `query()` ever reaches
+ * it.
+ *
+ * Each test here goes through the public entry point and would have caught
+ * its defect. That is the only property that makes them worth having.
+ */
+const dirs = [];
+afterEach(async () => {
+    await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })));
+    dirs.length = 0;
+});
+async function workdir() {
+    const dir = await mkdtemp(join(tmpdir(), 'namzu-seam-'));
+    dirs.push(dir);
+    return dir;
+}
+function countingTool(name, calls) {
+    return {
+        name,
+        description: `${name} tool`,
+        inputSchema: z.object({ id: z.number() }),
+        isDestructive: () => true,
+        execute: (input) => {
+            calls.push(`${name}:${input.id}`);
+            return Promise.resolve({ success: true, output: 'ok' });
+        },
+    };
+}
+function baseParams(opts) {
+    return {
+        provider: opts.provider,
+        tools: opts.tools,
+        ...(opts.resumeHandler ? { resumeHandler: opts.resumeHandler } : {}),
+        runConfig: {
+            model: 'mock-model',
+            timeoutMs: 10_000,
+            tokenBudget: 100_000,
+            maxIterations: 4,
+            maxResponseTokens: 256,
+        },
+        agentId: 'agent_seam',
+        agentName: 'Seam',
+        workingDirectory: opts.dir,
+        sessionId: 'ses_seam',
+        threadId: 'thd_seam',
+        projectId: 'prj_seam',
+        tenantId: 'tnt_seam',
+    };
+}
+describe('query() actually reaches repairToolCall', () => {
+    it('repairs a malformed call issued through the real entry point', async () => {
+        // The bug: `repairToolCall` was spread into `ToolingBootstrap.init`,
+        // whose config type has no such field and whose `init` enumerates
+        // what it forwards. Object spread bypasses excess-property checking,
+        // so `query({ repairToolCall })` type-checked and did nothing.
+        const dir = await workdir();
+        const calls = [];
+        const tools = new ToolRegistry();
+        tools.register(countingTool('delete_row', calls));
+        const repair = vi.fn(() => ({ arguments: '{"id":42}' }));
+        const provider = new MockLLMProvider({
+            turns: [{ toolCalls: [{ name: 'delete_row', rawArguments: '{"id": 4' }] }, { text: 'done' }],
+        });
+        await drainQuery({
+            ...baseParams({ dir, tools, provider }),
+            messages: [createUserMessage('delete row 42')],
+            repairToolCall: repair,
+        });
+        expect(repair).toHaveBeenCalled();
+        expect(calls).toEqual(['delete_row:42']);
+    });
+});
+describe('a post_tool_use retry works on a tool that did not opt into retries', () => {
+    it('honors the hook once, then stops', async () => {
+        // The bug: `post.retry` was read inside a loop bounded by the tool's
+        // `maxRetries`, which defaults to 0 — so the loop body never ran and
+        // the hook's answer was silently discarded. `retry` had also been
+        // removed from the unsupported-action throw, so plugin authors got
+        // silence instead of an error.
+        const dir = await workdir();
+        const calls = [];
+        const tools = new ToolRegistry();
+        tools.register(countingTool('flaky', calls));
+        let asked = 0;
+        const pluginManager = {
+            executeHooks: (event) => {
+                if (event !== 'post_tool_use')
+                    return Promise.resolve([]);
+                asked++;
+                // Ask for exactly one retry, then let it settle.
+                return Promise.resolve(asked === 1
+                    ? [{ action: 'retry' }]
+                    : [{ action: 'continue' }]);
+            },
+        };
+        const provider = new MockLLMProvider({
+            turns: [{ toolCalls: [{ name: 'flaky', args: { id: 1 } }] }, { text: 'done' }],
+        });
+        await drainQuery({
+            ...baseParams({ dir, tools, provider }),
+            messages: [createUserMessage('go')],
+            pluginManager: pluginManager,
+        });
+        // Ran twice: the original call plus the hook-requested retry.
+        expect(calls).toEqual(['flaky:1', 'flaky:1']);
+    });
+    it('a hook that always asks for a retry cannot spin the executor', async () => {
+        const dir = await workdir();
+        const calls = [];
+        const tools = new ToolRegistry();
+        tools.register(countingTool('flaky', calls));
+        const pluginManager = {
+            executeHooks: (event) => Promise.resolve(event === 'post_tool_use'
+                ? [{ action: 'retry' }]
+                : []),
+        };
+        const provider = new MockLLMProvider({
+            turns: [{ toolCalls: [{ name: 'flaky', args: { id: 1 } }] }, { text: 'done' }],
+        });
+        await drainQuery({
+            ...baseParams({ dir, tools, provider }),
+            messages: [createUserMessage('go')],
+            pluginManager: pluginManager,
+        });
+        // Bounded by HOOK_RETRY_BUDGET, not unbounded.
+        expect(calls).toHaveLength(2);
+    });
+});
+describe('a cross-process resume clears the park it acted on', () => {
+    it('stops reporting pending once the approved batch has run', async () => {
+        // The bug: `applyPendingResume` executed the batch and returned. The
+        // checkpoint kept `pending` with no `resolvedAt`, so an approval
+        // queue built on `findPendingCheckpoint` re-served a destructive call
+        // that had already run — the exact failure recording the park exists
+        // to prevent.
+        const dir = await workdir();
+        const calls = [];
+        const tools = new ToolRegistry();
+        tools.register(countingTool('delete_row', calls));
+        const store = new DiskCheckpointStore({ baseDir: join(dir, 'runs') });
+        const scope = {
+            tenantId: 'tnt_seam',
+            projectId: 'prj_seam',
+            sessionId: 'ses_seam',
+            runId: 'run_seam',
+        };
+        const pauseOnReview = (request) => Promise.resolve(request.type === 'tool_review'
+            ? { action: 'pause', reason: 'ask a human' }
+            : { action: 'continue' });
+        const parked = await drainQuery({
+            ...baseParams({
+                dir,
+                tools,
+                provider: new MockLLMProvider({
+                    turns: [{ toolCalls: [{ name: 'delete_row', args: { id: 9 } }] }],
+                }),
+                resumeHandler: pauseOnReview,
+            }),
+            checkpointStore: store,
+            runId: scope.runId,
+            messages: [createUserMessage('delete row 9')],
+        });
+        const pending = await findPendingCheckpoint(store, { ...scope, runId: parked.id });
+        expect(pending).not.toBeNull();
+        await drainQuery({
+            ...baseParams({
+                dir,
+                tools,
+                provider: new MockLLMProvider({ turns: [{ text: 'gone' }] }),
+                resumeHandler: pauseOnReview,
+            }),
+            checkpointStore: store,
+            runId: scope.runId,
+            messages: [],
+            resumeFromCheckpoint: pending?.id,
+            pendingDecision: { action: 'approve_tools' },
+        });
+        expect(calls).toEqual(['delete_row:9']);
+        // The queue must not offer this decision again.
+        expect(await findPendingCheckpoint(store, { ...scope, runId: parked.id })).toBeNull();
+    });
+});
+describe('configuring an output guardrail does not rewrite the run outcome', () => {
+    it('leaves a cancelled run cancelled', async () => {
+        // The bug: the guardrail branch called `markCompleted()` purely to
+        // materialize the produced text, so merely ADDING a safety check
+        // turned a cancelled run into a completed one.
+        const dir = await workdir();
+        const tools = new ToolRegistry();
+        const controller = new AbortController();
+        const provider = new MockLLMProvider({
+            turns: [{ toolCalls: [{ name: 'noop', args: {} }] }, { text: 'never' }],
+        });
+        const cancelOnReview = () => {
+            controller.abort();
+            return Promise.resolve({ action: 'abort', reason: 'user stopped' });
+        };
+        const result = await drainQuery({
+            ...baseParams({ dir, tools, provider, resumeHandler: cancelOnReview }),
+            messages: [createUserMessage('go')],
+            signal: controller.signal,
+            outputGuardrails: [() => ({ action: 'pass' })],
+        });
+        expect(result.status).toBe('cancelled');
+        expect(result.stopReason).toBe('cancelled');
+    });
+    it('still settles a normal run as completed', async () => {
+        const dir = await workdir();
+        const tools = new ToolRegistry();
+        const result = await drainQuery({
+            ...baseParams({
+                dir,
+                tools,
+                provider: new MockLLMProvider({ turns: [{ text: 'all good' }] }),
+            }),
+            messages: [createUserMessage('go')],
+            outputGuardrails: [() => ({ action: 'pass' })],
+        });
+        expect(result.status).toBe('completed');
+        expect(result.result).toBe('all good');
+    });
+});
+//# sourceMappingURL=wiring-seams.test.js.map

package/dist/runtime/query/__tests__/wiring-seams.test.js.map

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

package/dist/runtime/query/checkpoint.d.ts

@@ -1,5 +1,7 @@
+import type { WorkingStateSnapshot } from '../../compaction/wire.js';
 import type { RunPersistence } from '../../manager/run/persistence.js';
-import type { ActiveNodeInfo, BranchStackEntry, CheckpointId, CheckpointSummary, IterationCheckpoint } from '../../types/hitl/index.js';
+import type { SerializedSpanContext } from '../../telemetry/attributes.js';
+import type { CheckpointId, CheckpointSummary, HITLDecisionRequest, HITLResumeDecision, IterationCheckpoint, PendingDecision } from '../../types/hitl/index.js';
 import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js';
 import type { EmergencySaveData } from '../../types/run/emergency.js';
 import type { CheckpointListEntry } from '../../types/run/replay.js';
@@ -14,18 +16,65 @@ export declare function toCheckpointListEntry(cp: IterationCheckpoint): Checkpoi
  * shape so `replay({ fromCheckpoint: 'emergency' })` can consume it through
  * the same restore path as any other checkpoint.
  *
- * The projection is lossy: `costInfo`, `guardState.elapsedMs`,
- * `toolResultHashes`, `branchStack`, and `activeNode` are not captured at
- * emergency-save time and default to zero/empty values. The synthetic
+ * The projection is lossy: `costInfo`, `guardState.elapsedMs` and
+ * `toolResultHashes` are not captured at emergency-save time and default
+ * to zero/empty values. The synthetic
  * checkpoint id is derived deterministically from the emergency save id so
  * re-projecting the same dump yields the same {@link CheckpointId}.
  *
  * See ses_005-deterministic-replay design §2 + §5.2.
  */
 export declare function projectEmergencyToCheckpoint(dump: EmergencySaveData): IterationCheckpoint;
+/**
+ * The newest checkpoint of a run that is still awaiting a human decision,
+ * or `null` when the run is not parked.
+ *
+ * Standalone (not a `CheckpointManager` method) so a host can ask the
+ * question without constructing a run: an approval-queue worker in a
+ * different process has a store and a scope, and nothing else.
+ */
+export declare function findPendingCheckpoint(store: CheckpointStore, scope: CheckpointRunScope, options?: {
+    readonly now?: number;
+}): Promise<IterationCheckpoint | null>;
+/** Whether a park's absolute deadline has passed. No deadline never expires. */
+export declare function isExpiredPark(pending: PendingDecision, now?: number): boolean;
+/**
+ * Every outstanding park in a run, expired ones included, so a host can
+ * sweep them.
+ *
+ * The out-of-process timer stays a host concern — consistent with the same
+ * decision made for retention — but a host cannot sweep what it cannot
+ * enumerate, and this is the read that makes a sweep a few lines rather
+ * than a re-implementation of the store contract.
+ */
+export declare function listExpiredParks(store: CheckpointStore, scope: CheckpointRunScope, options?: {
+    readonly now?: number;
+}): Promise<IterationCheckpoint[]>;
 export declare class CheckpointManager {
     private store;
     private scope;
+    /**
+     * Compaction's state source, when the run has one.
+     *
+     * Every checkpoint snapshots it, so a resumed run can carry forward the
+     * state its earlier summary was built from. Without that the next
+     * compaction supersedes that summary with one covering only post-resume
+     * activity, and the record of everything before the resume is gone.
+     */
+    private workingStateSource?;
+    /**
+     * The most recent checkpoint this manager wrote, if any.
+     *
+     * A run that fails on a transient error needs to name the state a host
+     * should resume from. Re-listing the store to find it would be a disk
+     * read on the failure path, at the moment the run is least able to
+     * afford one; the id is already in hand.
+     */
+    private lastCreatedId?;
+    /** See {@link setTraceSource}. */
+    private traceSource?;
+    /** See {@link setParkTtl}. */
+    private parkTtlMs?;
     /**
      * @param store scope-keyed checkpoint persistence. The default query
      *   pipeline passes the run's disk-backed store
@@ -34,6 +83,14 @@ export declare class CheckpointManager {
      * @param scope the run every operation of this manager is keyed to.
      */
     constructor(store: CheckpointStore, scope: CheckpointRunScope);
+    /** Wire compaction's state in, so every checkpoint carries a snapshot. */
+    setWorkingStateSource(source: () => WorkingStateSnapshot | undefined): void;
+    /**
+     * The run's root span, so every checkpoint records the trace it was
+     * taken inside and a resume can join it rather than starting a second,
+     * unlinked one.
+     */
+    setTraceSource(source: () => SerializedSpanContext | undefined): void;
     create(runMgr: RunPersistence, iteration: number, extra?: {
         toolResults?: Array<{
             toolCallId: string;
@@ -41,9 +98,70 @@ export declare class CheckpointManager {
             input: unknown;
             output: string;
         }>;
-        branchStack?: BranchStackEntry[];
-        activeNode?: ActiveNodeInfo;
+        workingState?: WorkingStateSnapshot;
     }): Promise<IterationCheckpoint>;
+    /** See {@link lastCreatedId}. */
+    get lastCheckpointId(): CheckpointId | undefined;
+    /**
+     * The trace a checkpoint was taken inside, for parenting a resumed run.
+     *
+     * Read separately and BEFORE the run's root span, because a span's
+     * parent can only be set at creation and the root is minted before the
+     * restore branch runs.
+     *
+     * Never throws. Telemetry continuity is worth a disk read; it is not
+     * worth failing a resume over, and the restore path immediately after
+     * will report a genuinely unreadable checkpoint far better than a
+     * tracing helper could.
+     */
+    readTraceContext(checkpointId: CheckpointId): Promise<SerializedSpanContext | undefined>;
+    /**
+     * Record that the run parked at `checkpoint` awaiting a human, and
+     * return the updated checkpoint.
+     *
+     * A park used to exist only as a suspended `await`: the checkpoint
+     * written just before it was indistinguishable from any mid-run
+     * checkpoint, so a host could not tell from durable state that a
+     * decision was outstanding — and a process boundary lost the request
+     * entirely. Writing the request down is what lets an approval queue be
+     * rebuilt, and what lets a resumed run apply the answer to the exact
+     * tool calls the human saw.
+     *
+     * Called after `create` rather than as an argument to it because the
+     * request carries the checkpoint's own id.
+     */
+    park(checkpoint: IterationCheckpoint, request: HITLDecisionRequest, options?: {
+        readonly ttlMs?: number;
+    }): Promise<IterationCheckpoint>;
+    /** Default time-to-live applied to every park this manager records. */
+    setParkTtl(ttlMs: number | undefined): void;
+    /**
+     * Mark an expired park as no longer outstanding.
+     *
+     * Recorded rather than deleted: the checkpoint showing what was asked
+     * and that nobody answered in time is the evidence an approval gate is
+     * worth having, and the same reasoning already keeps a resolved
+     * decision on the record.
+     */
+    expire(checkpointId: CheckpointId): Promise<IterationCheckpoint | null>;
+    /**
+     * Record the answer, so an outstanding park stops looking outstanding.
+     *
+     * The decision is kept rather than erased: a checkpoint that shows both
+     * what was asked and what was answered is the evidence trail an
+     * approval gate is worth having. A no-op when the checkpoint is gone
+     * (pruned) or was never parked.
+     */
+    unpark(checkpointId: CheckpointId, decision: HITLResumeDecision): Promise<IterationCheckpoint | null>;
+    /**
+     * The run's outstanding park, if it has one — the newest checkpoint
+     * whose `pending` has no `resolvedAt`.
+     *
+     * This is the read a host's approval queue is built from, and it works
+     * across a process boundary because it consults the store rather than
+     * in-memory state.
+     */
+    findPending(): Promise<IterationCheckpoint | null>;
     restore(checkpointId: CheckpointId): Promise<IterationCheckpoint>;
     list(): Promise<IterationCheckpoint[]>;
     /**

package/dist/runtime/query/checkpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,MAAM,2BAA2B,CAAA;AAElC,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAKpE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,mBAAmB,GAAG,mBAAmB,CAQlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAezF;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,KAAK,CAAoB;IAEjC;;;;;;OAMG;gBACS,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,kBAAkB;IAKvD,MAAM,CACX,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE;QACP,WAAW,CAAC,EAAE,KAAK,CAAC;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;QAC7F,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAA;QAChC,UAAU,CAAC,EAAE,cAAc,CAAA;KAC3B,GACC,OAAO,CAAC,mBAAmB,CAAC;IAsBzB,OAAO,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQjE,IAAI,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAI5C;;;;;OAKG;IACG,WAAW,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAK7C,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW5C,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,iBAAiB;CAajF"}
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/checkpoint.ts"],"names":[],"mappings":"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"}