@namzu/sdk 0.4.1 → 0.4.3

package/dist/runtime/query/replay/__tests__/mutate.test.js

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import { MutationNotApplicableError } from '../../../../types/run/replay.js';
+import { applyMutations } from '../mutate.js';
+function assistantWithCalls(toolCallIds) {
+    return {
+        role: 'assistant',
+        content: null,
+        toolCalls: toolCallIds.map((id) => ({
+            id,
+            type: 'function',
+            function: { name: 'noop', arguments: '{}' },
+        })),
+    };
+}
+describe('applyMutations / injectToolResponse', () => {
+    it('appends a ToolMessage when the toolCallId is pending', () => {
+        const messages = [
+            { role: 'user', content: 'do stuff' },
+            assistantWithCalls(['call_a', 'call_b']),
+            { role: 'tool', content: 'a done', toolCallId: 'call_a' },
+        ];
+        const mutations = [
+            {
+                type: 'injectToolResponse',
+                toolCallId: 'call_b',
+                response: { success: true, output: 'mocked-b', data: { x: 1 } },
+            },
+        ];
+        const result = applyMutations(messages, mutations);
+        expect(result).toHaveLength(4);
+        const last = result[3];
+        expect(last.role).toBe('tool');
+        expect(last.toolCallId).toBe('call_b');
+        expect(last.content).toBe('mocked-b');
+    });
+    it('throws MutationNotApplicableError when no pending tool calls exist', () => {
+        const messages = [
+            { role: 'user', content: 'hi' },
+            { role: 'assistant', content: 'hello' },
+        ];
+        expect(() => applyMutations(messages, [
+            {
+                type: 'injectToolResponse',
+                toolCallId: 'call_missing',
+                response: { success: true, output: 'x' },
+            },
+        ])).toThrow(MutationNotApplicableError);
+    });
+    it('throws with availableToolCallIds populated when toolCallId is not pending', () => {
+        const messages = [
+            { role: 'user', content: 'do stuff' },
+            assistantWithCalls(['call_a', 'call_b']),
+        ];
+        try {
+            applyMutations(messages, [
+                {
+                    type: 'injectToolResponse',
+                    toolCallId: 'call_z',
+                    response: { success: true, output: 'x' },
+                },
+            ]);
+            expect.fail('expected MutationNotApplicableError');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(MutationNotApplicableError);
+            const e = err;
+            expect(e.availableToolCallIds).toEqual(['call_a', 'call_b']);
+        }
+    });
+    it('considers a tool call satisfied only when a subsequent ToolMessage responds to it', () => {
+        const messages = [
+            { role: 'user', content: 'do stuff' },
+            assistantWithCalls(['call_a', 'call_b', 'call_c']),
+            { role: 'tool', content: 'a done', toolCallId: 'call_a' },
+            { role: 'tool', content: 'c done', toolCallId: 'call_c' },
+        ];
+        try {
+            applyMutations(messages, [
+                {
+                    type: 'injectToolResponse',
+                    toolCallId: 'call_a',
+                    response: { success: true, output: 're-answered' },
+                },
+            ]);
+            expect.fail('expected MutationNotApplicableError — call_a already satisfied');
+        }
+        catch (err) {
+            const e = err;
+            expect(e.availableToolCallIds).toEqual(['call_b']);
+        }
+    });
+    it('applies mutations in order so a later mutation sees earlier ones', () => {
+        const messages = [
+            { role: 'user', content: 'two calls pending' },
+            assistantWithCalls(['call_x', 'call_y']),
+        ];
+        const result = applyMutations(messages, [
+            {
+                type: 'injectToolResponse',
+                toolCallId: 'call_x',
+                response: { success: true, output: 'x-result' },
+            },
+            {
+                type: 'injectToolResponse',
+                toolCallId: 'call_y',
+                response: { success: true, output: 'y-result' },
+            },
+        ]);
+        expect(result).toHaveLength(4);
+        expect(result[2].toolCallId).toBe('call_x');
+        expect(result[3].toolCallId).toBe('call_y');
+    });
+    it('returns the original messages unchanged when the mutation list is empty', () => {
+        const messages = [
+            { role: 'user', content: 'no-op' },
+            { role: 'assistant', content: 'ok' },
+        ];
+        const result = applyMutations(messages, []);
+        expect(result).toEqual(messages);
+        expect(result).not.toBe(messages);
+    });
+});
+//# sourceMappingURL=mutate.test.js.map

package/dist/runtime/query/replay/__tests__/mutate.test.js.map

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

package/dist/runtime/query/replay/__tests__/prepare.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prepare.test.d.ts.map

package/dist/runtime/query/replay/__tests__/prepare.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.test.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/query/replay/__tests__/prepare.test.ts"],"names":[],"mappings":""}

package/dist/runtime/query/replay/__tests__/prepare.test.js

@@ -0,0 +1,171 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { prepareReplayState } from '../prepare.js';
+const RUN_ID = 'run_source';
+function makeCheckpoint(overrides) {
+    return {
+        id: 'cp_default',
+        runId: RUN_ID,
+        iteration: 1,
+        messages: [{ role: 'user', content: 'hi' }],
+        tokenUsage: {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        },
+        costInfo: { inputCostPer1M: 0, outputCostPer1M: 0, totalCost: 0, cacheDiscount: 0 },
+        guardState: { iterationCount: 1, elapsedMs: 0 },
+        createdAt: Date.now(),
+        ...overrides,
+    };
+}
+async function seedCheckpoint(baseDir, cp) {
+    const cpDir = join(baseDir, cp.runId, 'checkpoints');
+    await mkdir(cpDir, { recursive: true });
+    await writeFile(join(cpDir, `${cp.id}.json`), JSON.stringify(cp), 'utf-8');
+}
+async function seedEmergency(emergencyDir, dump) {
+    await mkdir(emergencyDir, { recursive: true });
+    await writeFile(join(emergencyDir, `${dump.runId}.json`), JSON.stringify(dump), 'utf-8');
+}
+describe('prepareReplayState', () => {
+    let baseDir;
+    let emergencyDir;
+    beforeEach(async () => {
+        const wrapper = await mkdtemp(join(tmpdir(), 'namzu-prepare-replay-'));
+        baseDir = join(wrapper, 'runs');
+        emergencyDir = join(wrapper, 'emergency');
+        await mkdir(baseDir, { recursive: true });
+    });
+    afterEach(async () => {
+        // Per-test tmpdir isolation; vitest cleans tmpdir between runs.
+    });
+    it('resolves a specific CheckpointId and returns the checkpoint messages', async () => {
+        const cp = makeCheckpoint({
+            id: 'cp_one',
+            iteration: 3,
+            messages: [
+                { role: 'user', content: 'start' },
+                { role: 'assistant', content: 'ok' },
+            ],
+        });
+        await seedCheckpoint(baseDir, cp);
+        const prepared = await prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'cp_one',
+        });
+        expect(prepared.sourceCheckpoint.id).toBe('cp_one');
+        expect(prepared.messages).toEqual(cp.messages);
+        expect(prepared.attribution.sourceRunId).toBe(RUN_ID);
+        expect(prepared.attribution.fromCheckpointId).toBe('cp_one');
+        expect(prepared.attribution.mutations).toEqual([]);
+        expect(prepared.attribution.replayedAt).toBeGreaterThan(0);
+    });
+    it("resolves 'latest' to the checkpoint with the highest iteration", async () => {
+        await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_a', iteration: 1 }));
+        await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_b', iteration: 5 }));
+        await seedCheckpoint(baseDir, makeCheckpoint({ id: 'cp_c', iteration: 3 }));
+        const prepared = await prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'latest',
+        });
+        expect(prepared.sourceCheckpoint.id).toBe('cp_b');
+        expect(prepared.sourceCheckpoint.iteration).toBe(5);
+    });
+    it("throws when 'latest' is requested but no checkpoints exist", async () => {
+        await expect(prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'latest',
+        })).rejects.toThrow(/No checkpoints found/);
+    });
+    it('throws when a specific CheckpointId does not resolve', async () => {
+        await expect(prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'cp_missing',
+        })).rejects.toThrow(/not found/);
+    });
+    it('applies injectToolResponse mutations at the fork point', async () => {
+        const assistantMsg = {
+            role: 'assistant',
+            content: null,
+            toolCalls: [{ id: 'call_a', type: 'function', function: { name: 'noop', arguments: '{}' } }],
+        };
+        const cp = makeCheckpoint({
+            id: 'cp_with_tool',
+            messages: [{ role: 'user', content: 'run tool' }, assistantMsg],
+        });
+        await seedCheckpoint(baseDir, cp);
+        const mutations = [
+            {
+                type: 'injectToolResponse',
+                toolCallId: 'call_a',
+                response: { success: true, output: 'mocked-a' },
+            },
+        ];
+        const prepared = await prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'cp_with_tool',
+            mutate: mutations,
+        });
+        expect(prepared.messages).toHaveLength(3);
+        const appended = prepared.messages[2];
+        expect(appended.role).toBe('tool');
+        expect(appended.toolCallId).toBe('call_a');
+        expect(appended.content).toBe('mocked-a');
+        expect(prepared.attribution.mutations).toEqual(mutations);
+    });
+    it("resolves 'emergency' via the emergency dump and projects it to a checkpoint", async () => {
+        const dump = {
+            id: 'esave_xyz',
+            runId: RUN_ID,
+            messages: [{ role: 'user', content: 'before crash' }],
+            tokenUsage: {
+                promptTokens: 4,
+                completionTokens: 2,
+                totalTokens: 6,
+                cachedTokens: 0,
+                cacheWriteTokens: 0,
+            },
+            currentIteration: 9,
+            startedAt: 1_000,
+            savedAt: 2_000,
+            processSignal: 'SIGTERM',
+        };
+        await seedEmergency(emergencyDir, dump);
+        const prepared = await prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'emergency',
+            emergencyDir,
+        });
+        expect(prepared.sourceCheckpoint.id).toBe('cp_emergency_xyz');
+        expect(prepared.sourceCheckpoint.iteration).toBe(9);
+        expect(prepared.messages).toEqual(dump.messages);
+        expect(prepared.attribution.fromCheckpointId).toBe('cp_emergency_xyz');
+    });
+    it("throws when 'emergency' is requested without emergencyDir", async () => {
+        await expect(prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'emergency',
+        })).rejects.toThrow(/emergencyDir/);
+    });
+    it("throws when 'emergency' dump file is missing", async () => {
+        await expect(prepareReplayState({
+            baseDir,
+            runId: RUN_ID,
+            fromCheckpoint: 'emergency',
+            emergencyDir,
+        })).rejects.toThrow(/No emergency dump/);
+    });
+});
+//# sourceMappingURL=prepare.test.js.map

package/dist/runtime/query/replay/__tests__/prepare.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.test.js","sourceRoot":"","sources":["../../../../../src/runtime/query/replay/__tests__/prepare.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAMpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAElD,MAAM,MAAM,GAAG,YAAqB,CAAA;AAEpC,SAAS,cAAc,CAAC,SAAuC;IAC9D,OAAO;QACN,EAAE,EAAE,YAA4B;QAChC,KAAK,EAAE,MAAM;QACb,SAAS,EAAE,CAAC;QACZ,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3C,UAAU,EAAE;YACX,YAAY,EAAE,CAAC;YACf,gBAAgB,EAAE,CAAC;YACnB,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,gBAAgB,EAAE,CAAC;SACnB;QACD,QAAQ,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE;QACnF,UAAU,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;QAC/C,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,GAAG,SAAS;KACZ,CAAA;AACF,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,OAAe,EAAE,EAAuB;IACrE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;IACpD,MAAM,KAAK,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACvC,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAA;AAC3E,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,YAAoB,EAAE,IAAuB;IACzE,MAAM,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC9C,MAAM,SAAS,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,KAAK,OAAO,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAA;AACzF,CAAC;AAED,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IACnC,IAAI,OAAe,CAAA;IACnB,IAAI,YAAoB,CAAA;IAExB,UAAU,CAAC,KAAK,IAAI,EAAE;QACrB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC,CAAC,CAAA;QACtE,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC/B,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAA;QACzC,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,SAAS,CAAC,KAAK,IAAI,EAAE;QACpB,gEAAgE;IACjE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sEAAsE,EAAE,KAAK,IAAI,EAAE;QACrF,MAAM,EAAE,GAAG,cAAc,CAAC;YACzB,EAAE,EAAE,QAAwB;YAC5B,SAAS,EAAE,CAAC;YACZ,QAAQ,EAAE;gBACT,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE;gBAClC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE;aACpC;SACD,CAAC,CAAA;QACF,MAAM,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;QAEjC,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC;YACzC,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,QAAwB;SACxC,CAAC,CAAA;QAEF,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACnD,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAA;QAC9C,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACrD,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC5D,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAClD,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;QAC/E,MAAM,cAAc,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,EAAE,EAAE,MAAsB,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QAC3F,MAAM,cAAc,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,EAAE,EAAE,MAAsB,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QAC3F,MAAM,cAAc,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,EAAE,EAAE,MAAsB,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QAE3F,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC;YACzC,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,QAAQ;SACxB,CAAC,CAAA;QAEF,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACjD,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACpD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;QAC3E,MAAM,MAAM,CACX,kBAAkB,CAAC;YAClB,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,QAAQ;SACxB,CAAC,CACF,CAAC,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sDAAsD,EAAE,KAAK,IAAI,EAAE;QACrE,MAAM,MAAM,CACX,kBAAkB,CAAC;YAClB,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,YAA4B;SAC5C,CAAC,CACF,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,YAAY,GAAqB;YACtC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;SAC5F,CAAA;QACD,MAAM,EAAE,GAAG,cAAc,CAAC;YACzB,EAAE,EAAE,cAA8B;YAClC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,YAAY,CAAC;SAC/D,CAAC,CAAA;QACF,MAAM,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;QAEjC,MAAM,SAAS,GAAe;YAC7B;gBACC,IAAI,EAAE,oBAAoB;gBAC1B,UAAU,EAAE,QAAsB;gBAClC,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE;aAC/C;SACD,CAAA;QAED,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC;YACzC,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,cAA8B;YAC9C,MAAM,EAAE,SAAS;SACjB,CAAC,CAAA;QAEF,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;QACzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAgB,CAAA;QACpD,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAClC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC1C,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACzC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC1D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6EAA6E,EAAE,KAAK,IAAI,EAAE;QAC5F,MAAM,IAAI,GAAsB;YAC/B,EAAE,EAAE,WAA8B;YAClC,KAAK,EAAE,MAAM;YACb,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;YACrD,UAAU,EAAE;gBACX,YAAY,EAAE,CAAC;gBACf,gBAAgB,EAAE,CAAC;gBACnB,WAAW,EAAE,CAAC;gBACd,YAAY,EAAE,CAAC;gBACf,gBAAgB,EAAE,CAAC;aACnB;YACD,gBAAgB,EAAE,CAAC;YACnB,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,KAAK;YACd,aAAa,EAAE,SAAS;SACxB,CAAA;QACD,MAAM,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,CAAA;QAEvC,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC;YACzC,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,WAAW;YAC3B,YAAY;SACZ,CAAC,CAAA;QAEF,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;QAC7D,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACnD,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAChD,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QAC1E,MAAM,MAAM,CACX,kBAAkB,CAAC;YAClB,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,WAAW;SAC3B,CAAC,CACF,CAAC,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,CAAA;IAClC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;QAC7D,MAAM,MAAM,CACX,kBAAkB,CAAC;YAClB,OAAO;YACP,KAAK,EAAE,MAAM;YACb,cAAc,EAAE,WAAW;YAC3B,YAAY;SACZ,CAAC,CACF,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACvC,CAAC,CAAC,CAAA;AACH,CAAC,CAAC,CAAA"}

package/dist/runtime/query/replay/list.d.ts

@@ -0,0 +1,24 @@
+import type { RunId } from '../../../types/ids/index.js';
+import type { CheckpointListEntry } from '../../../types/run/replay.js';
+import type { Logger } from '../../../utils/logger.js';
+export interface ListCheckpointsInput {
+    /** Directory that contains `<runId>/` for the target run. */
+    baseDir: string;
+    /** Run whose checkpoints should be listed. */
+    runId: RunId;
+    logger?: Logger;
+}
+/**
+ * Read-only listing of a run's checkpoints for use with {@link
+ * import('./prepare.js').prepareReplayState}. Returns the public
+ * {@link CheckpointListEntry} projection — just enough for a caller to
+ * pick a fork point — not the full `IterationCheckpoint` payload.
+ *
+ * Entries are returned in the order the underlying store returns them
+ * (disk store sorts by `createdAt` ascending). Callers that want a
+ * specific order should sort client-side.
+ *
+ * See ses_005-deterministic-replay/design.md §3.1.
+ */
+export declare function listCheckpoints(input: ListCheckpointsInput): Promise<CheckpointListEntry[]>;
+//# sourceMappingURL=list.d.ts.map

package/dist/runtime/query/replay/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../src/runtime/query/replay/list.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAA;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAGtD,MAAM,WAAW,oBAAoB;IACpC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAKjG"}

package/dist/runtime/query/replay/list.js

@@ -0,0 +1,21 @@
+import { RunDiskStore } from '../../../store/run/disk.js';
+import { CheckpointManager } from '../checkpoint.js';
+/**
+ * Read-only listing of a run's checkpoints for use with {@link
+ * import('./prepare.js').prepareReplayState}. Returns the public
+ * {@link CheckpointListEntry} projection — just enough for a caller to
+ * pick a fork point — not the full `IterationCheckpoint` payload.
+ *
+ * Entries are returned in the order the underlying store returns them
+ * (disk store sorts by `createdAt` ascending). Callers that want a
+ * specific order should sort client-side.
+ *
+ * See ses_005-deterministic-replay/design.md §3.1.
+ */
+export async function listCheckpoints(input) {
+    const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger });
+    await store.initRun(input.runId);
+    const mgr = new CheckpointManager(store);
+    return mgr.listEntries();
+}
+//# sourceMappingURL=list.js.map

package/dist/runtime/query/replay/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../src/runtime/query/replay/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAIzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAUpD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAA2B;IAChE,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;IAChF,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAChC,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACxC,OAAO,GAAG,CAAC,WAAW,EAAE,CAAA;AACzB,CAAC"}

package/dist/runtime/query/replay/mutate.d.ts

@@ -0,0 +1,17 @@
+import { type Message } from '../../../types/message/index.js';
+import { type Mutation } from '../../../types/run/replay.js';
+/**
+ * Apply an ordered list of {@link Mutation} to a checkpoint's message
+ * history at the fork point, producing a new message array that the
+ * resumed iteration loop consumes. Pure function; does not touch the run
+ * store, does not emit events.
+ *
+ * Throws {@link MutationNotApplicableError} when an `injectToolResponse`
+ * mutation targets a tool call id that is not pending at the fork point —
+ * the error payload carries the list of ids that *are* pending so the
+ * caller can recover without guessing.
+ *
+ * See ses_005-deterministic-replay design §3.3.
+ */
+export declare function applyMutations(messages: readonly Message[], mutations: readonly Mutation[]): Message[];
+//# sourceMappingURL=mutate.d.ts.map

package/dist/runtime/query/replay/mutate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutate.d.ts","sourceRoot":"","sources":["../../../../src/runtime/query/replay/mutate.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,OAAO,EAGZ,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAAE,KAAK,QAAQ,EAA8B,MAAM,8BAA8B,CAAA;AA8BxF;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,SAAS,EAAE,SAAS,QAAQ,EAAE,GAC5B,OAAO,EAAE,CAMX"}

package/dist/runtime/query/replay/mutate.js

@@ -0,0 +1,62 @@
+import { createToolMessage, } from '../../../types/message/index.js';
+import { MutationNotApplicableError } from '../../../types/run/replay.js';
+/**
+ * Returns the tool calls on the most recent assistant message that do not
+ * yet have a matching {@link import('../../../types/message/index.js').ToolMessage}
+ * response further down the message list. These are the fork-point "pending"
+ * tool calls that mutations may target.
+ */
+function findPendingToolCalls(messages) {
+    let lastAssistantIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg && msg.role === 'assistant' && (msg.toolCalls?.length ?? 0) > 0) {
+            lastAssistantIdx = i;
+            break;
+        }
+    }
+    if (lastAssistantIdx === -1)
+        return [];
+    const assistant = messages[lastAssistantIdx];
+    const satisfied = new Set();
+    for (let i = lastAssistantIdx + 1; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg && msg.role === 'tool') {
+            satisfied.add(msg.toolCallId);
+        }
+    }
+    return (assistant.toolCalls ?? []).filter((tc) => !satisfied.has(tc.id));
+}
+/**
+ * Apply an ordered list of {@link Mutation} to a checkpoint's message
+ * history at the fork point, producing a new message array that the
+ * resumed iteration loop consumes. Pure function; does not touch the run
+ * store, does not emit events.
+ *
+ * Throws {@link MutationNotApplicableError} when an `injectToolResponse`
+ * mutation targets a tool call id that is not pending at the fork point —
+ * the error payload carries the list of ids that *are* pending so the
+ * caller can recover without guessing.
+ *
+ * See ses_005-deterministic-replay design §3.3.
+ */
+export function applyMutations(messages, mutations) {
+    let current = [...messages];
+    for (const m of mutations) {
+        current = applyOne(current, m);
+    }
+    return current;
+}
+function applyOne(messages, mutation) {
+    switch (mutation.type) {
+        case 'injectToolResponse': {
+            const pending = findPendingToolCalls(messages);
+            const match = pending.find((tc) => tc.id === mutation.toolCallId);
+            if (!match) {
+                throw new MutationNotApplicableError(`No pending tool call ${mutation.toolCallId} at fork point`, pending.map((tc) => tc.id));
+            }
+            return [...messages, createToolMessage(mutation.response.output, mutation.toolCallId)];
+        }
+    }
+}
+//# sourceMappingURL=mutate.js.map

package/dist/runtime/query/replay/mutate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutate.js","sourceRoot":"","sources":["../../../../src/runtime/query/replay/mutate.ts"],"names":[],"mappings":"AACA,OAAO,EAIN,iBAAiB,GACjB,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAAiB,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AAExF;;;;;GAKG;AACH,SAAS,oBAAoB,CAAC,QAA4B;IACzD,IAAI,gBAAgB,GAAG,CAAC,CAAC,CAAA;IACzB,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;QACvB,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YACzE,gBAAgB,GAAG,CAAC,CAAA;YACpB,MAAK;QACN,CAAC;IACF,CAAC;IACD,IAAI,gBAAgB,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,CAAA;IAEtC,MAAM,SAAS,GAAG,QAAQ,CAAC,gBAAgB,CAAqB,CAAA;IAChE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,KAAK,IAAI,CAAC,GAAG,gBAAgB,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7D,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;QACvB,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAChC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QAC9B,CAAC;IACF,CAAC;IACD,OAAO,CAAC,SAAS,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC7B,QAA4B,EAC5B,SAA8B;IAE9B,IAAI,OAAO,GAAc,CAAC,GAAG,QAAQ,CAAC,CAAA;IACtC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC3B,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC/B,CAAC;IACD,OAAO,OAAO,CAAA;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,QAAmB,EAAE,QAAkB;IACxD,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,oBAAoB,CAAC,CAAC,CAAC;YAC3B,MAAM,OAAO,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAA;YAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,QAAQ,CAAC,UAAU,CAAC,CAAA;YACjE,IAAI,CAAC,KAAK,EAAE,CAAC;gBACZ,MAAM,IAAI,0BAA0B,CACnC,wBAAwB,QAAQ,CAAC,UAAU,gBAAgB,EAC3D,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAgB,CAAC,CACxC,CAAA;YACF,CAAC;YACD,OAAO,CAAC,GAAG,QAAQ,EAAE,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAA;QACvF,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/runtime/query/replay/prepare.d.ts

@@ -0,0 +1,56 @@
+import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js';
+import type { RunId } from '../../../types/ids/index.js';
+import type { Message } from '../../../types/message/index.js';
+import type { Mutation, ReplayAttribution } from '../../../types/run/replay.js';
+import type { Logger } from '../../../utils/logger.js';
+export type CheckpointSelector = CheckpointId | 'latest' | 'emergency';
+export interface PrepareReplayInput {
+    /** Directory that contains `<runId>/` for the source run. */
+    baseDir: string;
+    /** Source run to fork from. */
+    runId: RunId;
+    /** Which checkpoint to fork at. */
+    fromCheckpoint: CheckpointSelector;
+    /** Optional mutations applied at the fork point before the caller hands state to `query()`. */
+    mutate?: Mutation[];
+    /**
+     * Directory that holds emergency dumps. Required only when `fromCheckpoint`
+     * is `'emergency'`; conventionally sibling of `baseDir` (the `.namzu/emergency`
+     * folder), but left explicit so callers with non-default layouts can redirect.
+     */
+    emergencyDir?: string;
+    logger?: Logger;
+}
+export interface PreparedReplayState {
+    /**
+     * Message history at the fork point, with mutations applied. Seed this
+     * as the new run's initial messages and pass `sourceCheckpoint.id` as
+     * `resumeFromCheckpoint` when you call `query()`.
+     */
+    messages: Message[];
+    /** The checkpoint the replay forks from (already projected if emergency). */
+    sourceCheckpoint: IterationCheckpoint;
+    /**
+     * Attribution to stamp on the replay run once it is created. The caller
+     * sets `Run.replayOf = buildAttribution(prepared, replayedAt)` on the
+     * new `RunPersistence` before persisting the first time.
+     */
+    attribution: ReplayAttribution;
+}
+/**
+ * Produce the state materials needed to execute a replay run — the mutated
+ * message history, the resolved source checkpoint, and the replay
+ * attribution record. Pure read; does not touch the run store beyond
+ * reading the source run's checkpoint files.
+ *
+ * This is the state-preparation half of the replay primitive. The
+ * caller is expected to thread the returned `messages` +
+ * `sourceCheckpoint.id` into `query({ resumeFromCheckpoint, messages,
+ * ... })` and stamp `Run.replayOf = prepared.attribution` on the resulting
+ * run. The end-to-end `replay()` entry that does all of this in one call
+ * is a follow-up session (`ReplayEnvironment` shape).
+ *
+ * See `ses_005-deterministic-replay/design.md` §3.1.
+ */
+export declare function prepareReplayState(input: PrepareReplayInput): Promise<PreparedReplayState>;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/runtime/query/replay/prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../../src/runtime/query/replay/prepare.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AACrF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAA;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAA;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAC/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAItD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEtE,MAAM,WAAW,kBAAkB;IAClC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,+BAA+B;IAC/B,KAAK,EAAE,KAAK,CAAA;IACZ,mCAAmC;IACnC,cAAc,EAAE,kBAAkB,CAAA;IAClC,+FAA+F;IAC/F,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,6EAA6E;IAC7E,gBAAgB,EAAE,mBAAmB,CAAA;IACrC;;;;OAIG;IACH,WAAW,EAAE,iBAAiB,CAAA;CAC9B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAahG"}

package/dist/runtime/query/replay/prepare.js

@@ -0,0 +1,65 @@
+import { join } from 'node:path';
+import { EmergencySaveManager } from '../../../manager/run/emergency.js';
+import { RunDiskStore } from '../../../store/run/disk.js';
+import { projectEmergencyToCheckpoint } from '../checkpoint.js';
+import { applyMutations } from './mutate.js';
+/**
+ * Produce the state materials needed to execute a replay run — the mutated
+ * message history, the resolved source checkpoint, and the replay
+ * attribution record. Pure read; does not touch the run store beyond
+ * reading the source run's checkpoint files.
+ *
+ * This is the state-preparation half of the replay primitive. The
+ * caller is expected to thread the returned `messages` +
+ * `sourceCheckpoint.id` into `query({ resumeFromCheckpoint, messages,
+ * ... })` and stamp `Run.replayOf = prepared.attribution` on the resulting
+ * run. The end-to-end `replay()` entry that does all of this in one call
+ * is a follow-up session (`ReplayEnvironment` shape).
+ *
+ * See `ses_005-deterministic-replay/design.md` §3.1.
+ */
+export async function prepareReplayState(input) {
+    const sourceCheckpoint = await resolveCheckpoint(input);
+    const mutations = input.mutate ?? [];
+    const messages = applyMutations(sourceCheckpoint.messages, mutations);
+    const attribution = {
+        sourceRunId: input.runId,
+        fromCheckpointId: sourceCheckpoint.id,
+        mutations,
+        replayedAt: Date.now(),
+    };
+    return { messages, sourceCheckpoint, attribution };
+}
+async function resolveCheckpoint(input) {
+    if (input.fromCheckpoint === 'emergency') {
+        return resolveEmergency(input);
+    }
+    const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger });
+    await store.initRun(input.runId);
+    if (input.fromCheckpoint === 'latest') {
+        const all = await store.listCheckpoints();
+        if (all.length === 0) {
+            throw new Error(`No checkpoints found for run ${input.runId} in ${input.baseDir}`);
+        }
+        return [...all].sort((a, b) => b.iteration - a.iteration)[0];
+    }
+    const checkpoint = await store.readCheckpoint(input.fromCheckpoint);
+    if (!checkpoint) {
+        throw new Error(`Checkpoint ${input.fromCheckpoint} not found for run ${input.runId}`);
+    }
+    return checkpoint;
+}
+async function resolveEmergency(input) {
+    if (!input.emergencyDir) {
+        throw new Error("fromCheckpoint: 'emergency' requires an `emergencyDir` — conventionally sibling of baseDir");
+    }
+    const path = join(input.emergencyDir, `${input.runId}.json`);
+    try {
+        const dump = EmergencySaveManager.loadSave(path);
+        return projectEmergencyToCheckpoint(dump);
+    }
+    catch (err) {
+        throw new Error(`No emergency dump found for run ${input.runId} at ${path}`, { cause: err });
+    }
+}
+//# sourceMappingURL=prepare.js.map

package/dist/runtime/query/replay/prepare.js.map

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

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

@@ -2,7 +2,7 @@ import { type Span } from '@opentelemetry/api';
 import type { PlanManager } from '../../manager/plan/lifecycle.js';
 import type { RunPersistence } from '../../manager/run/persistence.js';
 import type { ActivityStore } from '../../store/activity/memory.js';
-import type { AgentRun, RunEvent } from '../../types/run/index.js';
+import type { Run, RunEvent } from '../../types/run/index.js';
 import type { Logger } from '../../utils/logger.js';
 import type { EmitEvent } from './events.js';
 export interface ResultAssemblerConfig {
@@ -19,6 +19,6 @@ export declare class ResultAssembler {
     completeRun(rootSpan: Span): AsyncGenerator<RunEvent>;
     completeSession(rootSpan: Span): AsyncGenerator<RunEvent>;
     handleError(err: unknown, rootSpan: Span): AsyncGenerator<RunEvent>;
-    finalize(): Promise<AgentRun>;
+    finalize(): Promise<Run>;
 }
 //# sourceMappingURL=result.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAkB,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAEnE,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAElE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,cAAc,CAAA;IACtB,WAAW,EAAE,WAAW,CAAA;IACxB,aAAa,EAAE,aAAa,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,SAAS,CAAA;IACpB,YAAY,EAAE,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAA;CACvC;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,MAAM,CAAuB;gBAEzB,MAAM,EAAE,qBAAqB;IAIlC,WAAW,CAAC,QAAQ,EAAE,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC;IA8BrD,eAAe,CAAC,QAAQ,EAAE,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC;IAIzD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC;IA6BpE,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;CAInC"}
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAkB,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAA;AAEnE,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAE7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,cAAc,CAAA;IACtB,WAAW,EAAE,WAAW,CAAA;IACxB,aAAa,EAAE,aAAa,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,SAAS,CAAA;IACpB,YAAY,EAAE,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAA;CACvC;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,MAAM,CAAuB;gBAEzB,MAAM,EAAE,qBAAqB;IAIlC,WAAW,CAAC,QAAQ,EAAE,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC;IA8BrD,eAAe,CAAC,QAAQ,EAAE,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC;IAIzD,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC;IA6BpE,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC;CAI9B"}