@animalabs/agent-framework 0.22.0 → 0.22.1

package/dist/test/tool-result-guard.test.js

@@ -6,9 +6,10 @@ import { join } from 'node:path';
 import { PassthroughStrategy } from '@animalabs/context-manager';
 import { Membrane as RealMembrane, NativeFormatter } from '@animalabs/membrane';
 import { AgentFramework } from '../src/index.js';
-import { TOOL_RESULT_GUARD_AUDIT_STATE, TOOL_RESULT_GUARD_NOTICE, withheldResultNotice } from '../src/tool-result-guard.js';
+import { TOOL_RESULT_GUARD_AUDIT_STATE, TOOL_RESULT_GUARD_NOTICE, keptWhenWithheld, withheldResultNotice } from '../src/tool-result-guard.js';
 import { MockYieldingStream, createMockResponse } from './helpers/mock-membrane.js';
 import { WorkspaceModule } from '../src/modules/workspace/index.js';
+import { DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS } from '../src/tool-result-history.js';
 import { JsStore } from '@animalabs/chronicle';
 // What a withheld result settles to with no writable workspace (#277): the
 // neutral notice, then where the original is kept. Written out, not computed
@@ -1503,7 +1504,7 @@ async function compressionRig() {
     const guard = new ToolResultGuard('Claude', cm, true);
     const REAL = 'REAL-ACCEPTED-TOOL-OUTPUT';
     const content = [{ type: 'tool_result', toolUseId: 'tu-1', content: REAL }];
-    const messageId = guard.storeResults(content, [{ toolUseId: 'tu-1', content: REAL }], []);
+    const messageId = guard.storeResults(content, [{ toolUseId: 'tu-1', content: REAL }], [], undefined, undefined);
     // Deferred messages flushed right behind the staged batch push it out of
     // the protected tail.
     for (let i = 0; i < 6; i++)
@@ -2561,7 +2562,7 @@ test('#281: a compile waits for an annotation that began while it waited for ano
         const compiled = r.guard.afterAnnotations(async () => { reads++; return [stub(r.messageId), stub(secondId)]; });
         // A second batch settles while the compile waits for the first annotation.
         r.cm.addMessage('Claude', [{ type: 'tool_use', id: 'tu-2', name: 'search', input: {} }]);
-        secondId = r.guard.storeResults([{ type: 'tool_result', toolUseId: 'tu-2', content: 'SECOND' }], [{ toolUseId: 'tu-2', content: 'SECOND' }], []);
+        secondId = r.guard.storeResults([{ type: 'tool_result', toolUseId: 'tu-2', content: 'SECOND' }], [{ toolUseId: 'tu-2', content: 'SECOND' }], [], undefined, undefined);
         r.guard.submissionResults([{ toolUseId: 'tu-2', content: 'SECOND' }]);
         assert.ok(r.guard.withhold('test-category'));
         first.open();
@@ -2947,7 +2948,7 @@ test('#281: an annotation that starts while modules stop writes no file, and is
     const stopModule = h.module.stop.bind(h.module);
     h.module.stop = async () => {
         // A settlement during shutdown, as a direct-API call that stop doesn't cancel can make.
-        agent.toolResultGuard.storeResults([{ type: 'tool_result', toolUseId: 'late', content: 'late-original' }], [{ toolUseId: 'late', content: 'late-original' }], []);
+        agent.toolResultGuard.storeResults([{ type: 'tool_result', toolUseId: 'late', content: 'late-original' }], [{ toolUseId: 'late', content: 'late-original' }], [], undefined, undefined);
         agent.toolResultGuard.abandon('stopping');
         await stopModule();
     };
@@ -2965,6 +2966,219 @@ test('#281: an annotation that starts while modules stop writes no file, and is
         await restarted.stop();
     }
 });
+test('#277: a write for a branch that waits for its mount while the branch changes is refused, and neither branch gets it', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'af-guard-write-binary-'));
+    dirs.push(dir);
+    mkdirSync(join(dir, 'mount'));
+    const store = JsStore.openOrCreate({ path: join(dir, 'store') });
+    const workspace = new WorkspaceModule({ mounts: [{ name: 'work', path: join(dir, 'mount'), mode: 'read-write', watch: 'never' }] });
+    workspace.initStore(store);
+    try {
+        const tree = 'workspace/work/tree';
+        const source = store.currentBranch().name;
+        const before = store.currentSequence();
+        // Hold the mount's turn, as a pass on it would: the write queues behind it.
+        const internals = workspace;
+        let release;
+        const gate = new Promise((resolve) => { release = resolve; });
+        const held = internals.withMount(internals.mounts.get('work'), () => gate);
+        const writing = workspace.writeBinary('work/tool-results/late.txt', Buffer.from('late'), 'text/plain', { branch: source });
+        store.createBranchAt('elsewhere', source, before);
+        store.switchBranch('elsewhere');
+        release();
+        await held;
+        assert.deepEqual(await writing, { success: false, error: 'the workspace had left the branch this file is for', isError: true,
+            data: { branchLeft: true } });
+        assert.equal(store.treeGet(tree, 'tool-results/late.txt'), null, 'nothing lands on the branch switched to');
+        store.switchBranch(source);
+        assert.equal(store.treeGet(tree, 'tool-results/late.txt'), null, 'nor on the branch the write named');
+    }
+    finally {
+        store.close();
+    }
+});
+// ---------------------------------------------------------------------------
+// #277's second half: a withheld result keeps the file lists its tool marked
+// (ToolResult.keepWhenWithheld) inline in its stub. materialize, sync and
+// delete mark theirs; nothing else does.
+// ---------------------------------------------------------------------------
+const LISTS = ' Kept from its result: ';
+/** The file lists a stub kept, parsed; undefined when it kept none. */
+const keptLists = (stub) => stub.includes(LISTS) ? JSON.parse(stub.slice(stub.indexOf(LISTS) + LISTS.length)) : undefined;
+const toolUse = (id, name, input = {}) => createMockResponse([{ type: 'tool_use', id, name, input }], 'tool_use');
+test('#277: a stub keeps the file lists after where the original is, for each place it can be', () => {
+    const notice = 'Tool result withheld by the guard. The tool has already executed.';
+    const lists = '{"materialized":[{"mount":"work","path":"LOG.md"}]}';
+    assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt' }, true, lists), `${notice} Its result is in workspace file work/tool-results/x.txt. Kept from its result: ${lists}`);
+    assert.equal(withheldResultNotice({ path: 'work/tool-results/x.txt', error: 'disk full' }, true, lists), `${notice} Writing its result to workspace file work/tool-results/x.txt failed, ` +
+        `so it is kept only in the guard's audit record (framework/tool-result-guard), for an operator. Kept from its result: ${lists}`);
+    assert.equal(withheldResultNotice({ path: 'work/tool-results/y.txt', unfinished: true }, true, lists), `${notice} Its result was still being written to workspace file work/tool-results/y.txt when this note was made; ` +
+        `if that file is missing, it is kept in the guard's audit record (framework/tool-result-guard), for an operator. ` +
+        `Kept from its result: ${lists}`);
+    assert.equal(withheldResultNotice(null, false, lists), `${notice} Its result went to the guard's audit record (framework/tool-result-guard), for an operator, ` +
+        `though saving that record had failed when the result arrived. Kept from its result: ${lists}`);
+    assert.equal(withheldResultNotice(null, true, undefined), AUDIT_STUB, 'nothing kept: the stub is as before');
+});
+test('#277: a result keeps the fields its tool marked, in the order marked, cut at the inline cap', () => {
+    const data = { materialized: [{ mount: 'work', path: 'LOG.md' }], count: 1, deleted: [{ mount: 'work', path: 'old.txt' }],
+        skipped: [{ mount: 'work', reason: 'a.txt: divergent' }] };
+    assert.equal(keptWhenWithheld({ success: true, data, keepWhenWithheld: ['deleted', 'materialized'] }, undefined), '{"deleted":[{"mount":"work","path":"old.txt"}],"materialized":[{"mount":"work","path":"LOG.md"}]}');
+    assert.equal(keptWhenWithheld({ success: true, data: { materialized: [], count: 0 }, keepWhenWithheld: ['deleted', 'materialized'] }, undefined), '{"materialized":[]}', 'a marked field the result lacks is left out; an empty list is kept');
+    for (const result of [
+        { success: true, data },
+        { success: true, data, keepWhenWithheld: [] },
+        { success: true, data, keepWhenWithheld: ['absent'] },
+        { success: true, data: 'text', keepWhenWithheld: ['length'] },
+        { success: true, data: [{ path: 'a' }], keepWhenWithheld: ['0'] },
+        { success: false, isError: true, error: 'failed', data: { path: 'work/a.txt' }, keepWhenWithheld: ['path'] },
+        // A failure is success false, whatever isError says.
+        { success: false, isError: false, error: 'failed', data: { path: 'work/a.txt' }, keepWhenWithheld: ['path'] },
+        // No data at all, with marks.
+        { success: true, data: null, keepWhenWithheld: ['path'] },
+        { success: true, keepWhenWithheld: ['path'] },
+    ])
+        assert.equal(keptWhenWithheld(result, undefined), undefined, `keeps nothing: ${JSON.stringify(result)}`);
+    const long = { written: Array.from({ length: 200 }, (_, i) => `file-${i}.txt`) };
+    const cut = keptWhenWithheld({ success: true, data: long, keepWhenWithheld: ['written'] }, 1000);
+    const whole = JSON.stringify(long);
+    assert.ok(whole.length > 1000);
+    // The note says what was cut and where the rest is, not "original was N",
+    // which would read as the whole result's size.
+    assert.equal(cut, `${whole.slice(0, 1000)} [cut at the inline cap: 1000 of these fields' ${whole.length} characters; ` +
+        'the whole result is where this note says]');
+    // A cut never leaves half a surrogate pair.
+    // '{"name":"' is 9 characters and each emoji 2, so a cap of 14 falls inside the third.
+    const emoji = keptWhenWithheld({ success: true, data: { name: '\u{1F600}'.repeat(10) }, keepWhenWithheld: ['name'] }, 14);
+    const loneSurrogate = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+    assert.doesNotMatch(emoji, loneSurrogate, `well-formed: ${JSON.stringify(emoji)}`);
+    assert.match(emoji, /^\{"name":"\u{1F600}\u{1F600} \[cut at the inline cap: 13 of these fields' 31 characters;/u);
+});
+test('#277: a withheld batch keeps what each marked result listed; an unmarked one keeps nothing, and its file has everything', async () => {
+    const h = await workspaceHarness([[calls('marked', 'plain'), refused()], [answer()]]);
+    h.module.results.marked = { success: true, data: { written: ['LOG.md'], detail: 'payload-marked' }, keepWhenWithheld: ['written'] };
+    try {
+        await h.run();
+        const [marked, plain] = toolResults(h.framework).map((block) => String(block.content));
+        assert.deepEqual(keptLists(marked), { written: ['LOG.md'] });
+        assert.doesNotMatch(marked, /payload-marked/, 'only the marked field is kept');
+        assert.match(marked, /^Tool result withheld by the guard\. The tool has already executed\. Its result is in workspace file work\/tool-results\/\S+-0-marked\.txt\. Kept from its result: /);
+        assert.equal(keptLists(plain), undefined);
+        assert.match(plain, /Its result is in workspace file work\/tool-results\/\S+-1-plain\.txt\.$/);
+        const file = await h.workspace.readBinary(/workspace file (\S+\.txt)\./.exec(marked)[1]);
+        assert.match(file.data.toString('utf8'), /payload-marked/, 'the file holds the whole result');
+        const retried = h.membrane.requests[1].messages.flatMap((m) => m.content).filter((b) => b.type === 'tool_result');
+        assert.deepEqual(retried.map((b) => b.content), [marked, plain], 'the retry already carries the lists');
+        assert.doesNotMatch(marked, /refus|test-category/, "#159's line: no refusal or category in the context");
+    }
+    finally {
+        await h.framework.stop();
+    }
+});
+test('#277: a marked result skipped for a branch change keeps its fields in the stub that names the audit record', async () => {
+    const h = await workspaceHarness([[calls('marked', 'plain'), refused()], [answer()]]);
+    h.module.results.marked = { success: true, data: { written: ['LOG.md'], detail: 'payload-marked' }, keepWhenWithheld: ['written'] };
+    // Declined where it commits, and the store is back on the batch's branch by
+    // the edit, as after an undo and a redo.
+    h.framework.writeToolResultFile = async () => ({ path: 'work/tool-results/declined.txt', branchLeft: true });
+    try {
+        await bounded(h.run(), 'the run');
+        const [marked, plain] = toolResults(h.framework).map((block) => String(block.content));
+        assert.equal(plain, AUDIT_STUB);
+        assert.ok(marked.startsWith(`${AUDIT_STUB} Kept from its result: `), marked);
+        assert.deepEqual(keptLists(marked), { written: ['LOG.md'] });
+    }
+    finally {
+        await h.framework.stop();
+    }
+});
+test('#277: with no writable workspace the stub still keeps the file lists, cut at the agent\'s inline cap', async () => {
+    const written = Array.from({ length: 200 }, (_, i) => `file-${i}.txt`);
+    const h = await harness([[calls('marked'), refused()], [answer()]], { toolResultGuard: true }, { marked: { success: true, data: { written }, keepWhenWithheld: ['written'] } });
+    try {
+        const spill = [...h.framework.collectAgentSettingsExtensions().values()].find((ext) => ext.keys.includes('tool_result_inline_max_chars'));
+        spill.update('assistant', { tool_result_inline_max_chars: 1000 });
+        await h.run();
+        const stub = String(toolResults(h.framework)[0].content);
+        const whole = JSON.stringify({ written });
+        assert.equal(stub, `${AUDIT_STUB}${LISTS}${whole.slice(0, 1000)} [cut at the inline cap: 1000 of these fields' ` +
+            `${whole.length} characters; the whole result is where this note says]`);
+    }
+    finally {
+        await h.framework.stop();
+    }
+});
+test('#277: direct API: a withheld result keeps its file lists, cut at the house default cap it was stored under', async () => {
+    const h = await harness([], { toolResultGuard: true });
+    const responses = [calls('marked'), refused(), answer()];
+    h.membrane.stream = async () => {
+        const response = responses.shift();
+        assert.ok(response);
+        return response;
+    };
+    try {
+        const agent = h.framework.getAgent('assistant');
+        agent.getContextManager().addMessage('user', [{ type: 'text', text: 'read' }]);
+        await agent.runInference(h.framework.getAllTools());
+        const written = Array.from({ length: 3000 }, (_, i) => `file-${i}.txt`);
+        agent.provideToolResult('marked', { success: true, data: { written }, keepWhenWithheld: ['written'] });
+        await agent.runInference(h.framework.getAllTools());
+        const stub = String(toolResults(h.framework)[0].content);
+        const whole = JSON.stringify({ written });
+        assert.ok(whole.length > DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS);
+        assert.equal(stub, `${AUDIT_STUB}${LISTS}${whole.slice(0, DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS)}` +
+            ` [cut at the inline cap: ${DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS} of these fields' ${whole.length} characters; ` +
+            'the whole result is where this note says]');
+    }
+    finally {
+        await h.framework.stop();
+    }
+});
+test('#283: a withheld materialize keeps the deletions it made; sync keeps a root it accepted ahead of its results', async () => {
+    const h = await workspaceHarness([[toolUse('m', 'workspace--materialize', { applyDeletions: true }), refused()], [answer()]]);
+    const call = (name, input = {}) => h.workspace.handleToolCall({ id: name, name, input });
+    try {
+        // A file on disk that the workspace then deletes: the agent's materialize removes it.
+        assert.equal((await h.workspace.writeBinary('work/old.txt', Buffer.from('old'), 'text/plain')).success, true);
+        assert.equal((await call('materialize')).success, true);
+        assert.equal((await call('delete', { path: 'work/old.txt' })).success, true);
+        await h.run();
+        const [materialize] = toolResults(h.framework).map((block) => String(block.content));
+        assert.deepEqual(keptLists(materialize), { deleted: [{ mount: 'work', path: 'old.txt' }], materialized: [] }, materialize);
+        // sync marks a root it accepted first, so a long results list can't cut it away.
+        const synced = await call('sync');
+        assert.deepEqual(synced.keepWhenWithheld, ['rootsAccepted', 'results']);
+    }
+    finally {
+        await h.framework.stop();
+    }
+});
+test('#277: withheld materialize, sync and delete keep the files they acted on in their stubs', async () => {
+    const h = await workspaceHarness([
+        [toolUse('m', 'workspace--materialize'), refused()], [answer()],
+        [toolUse('s', 'workspace--sync'), refused()], [answer()],
+        [toolUse('d', 'workspace--delete', { path: 'work/LOG.md' }), refused()], [answer()],
+    ]);
+    try {
+        // A workspace draft disk doesn't have yet: the materialize writes it.
+        assert.equal((await h.workspace.writeBinary('work/LOG.md', Buffer.from('log'), 'text/plain')).success, true);
+        await h.run();
+        // A file disk has and the workspace doesn't: the sync takes it in.
+        const mountDir = /^(.*)\/LOG\.md$/.exec(h.workspace.resolveAbsolutePath('work/LOG.md'))[1];
+        writeFileSync(join(mountDir, 'disk.txt'), 'from disk');
+        await h.run();
+        await h.run();
+        const [materialize, sync, del] = toolResults(h.framework).map((block) => String(block.content));
+        assert.deepEqual(keptLists(materialize), { materialized: [{ mount: 'work', path: 'LOG.md' }] }, materialize);
+        const synced = keptLists(sync);
+        assert.deepEqual(synced.results.map((r) => [r.mount, r.synced]), [['work', ['disk.txt']]], sync);
+        assert.deepEqual(keptLists(del), { path: 'work/LOG.md', deleted: true }, del);
+        for (const stub of [materialize, sync, del])
+            assert.match(stub, /^Tool result withheld by the guard\. The tool has already executed\. Its result is in workspace file /);
+    }
+    finally {
+        await h.framework.stop();
+    }
+});
 test('an unexpected annotation exception releases its compression hold', async () => {
     const r = await compressionRig();
     const branch = r.cm.currentBranch.bind(r.cm);
@@ -3099,7 +3313,7 @@ test("a batch's deadline is taken when it is queued, not when the batches ahead
         await until(() => entered === 1, 'the first annotation is writing');
         // A second batch queued behind the first, still writing.
         r.cm.addMessage('Claude', [{ type: 'tool_use', id: 'tu-2', name: 'search', input: {} }]);
-        r.guard.storeResults([{ type: 'tool_result', toolUseId: 'tu-2', content: 'SECOND' }], [{ toolUseId: 'tu-2', content: 'SECOND' }], []);
+        r.guard.storeResults([{ type: 'tool_result', toolUseId: 'tu-2', content: 'SECOND' }], [{ toolUseId: 'tu-2', content: 'SECOND' }], [], undefined, undefined);
         r.guard.submissionResults([{ toolUseId: 'tu-2', content: 'SECOND' }]);
         assert.ok(r.guard.withhold('test-category'));
         assert.equal(taken, 2, "the second batch's deadline was taken when it was queued");
@@ -3196,7 +3410,7 @@ test('stop then start reopens withheld spills', async () => {
         await framework.stop();
         framework.start();
         const guard = framework.getAgent('assistant').toolResultGuard;
-        guard.storeResults([{ type: 'tool_result', toolUseId: 'one', content: 'original' }], [{ toolUseId: 'one', content: 'original' }], []);
+        guard.storeResults([{ type: 'tool_result', toolUseId: 'one', content: 'original' }], [{ toolUseId: 'one', content: 'original' }], [], undefined, undefined);
         guard.abandon('test');
         await guard.whenAnnotated();
         assert.equal(writes, 1);
@@ -3278,7 +3492,7 @@ test('slow successful writes share one batch deadline', async (t) => {
     const guard = h.framework.getAgent('assistant').toolResultGuard;
     try {
         t.mock.timers.enable({ apis: ['Date', 'setTimeout'], now: Date.now() });
-        guard.storeResults(['one', 'two', 'three'].map((id) => ({ type: 'tool_result', toolUseId: id, content: id })), ['one', 'two', 'three'].map((id) => ({ toolUseId: id, content: id })), []);
+        guard.storeResults(['one', 'two', 'three'].map((id) => ({ type: 'tool_result', toolUseId: id, content: id })), ['one', 'two', 'three'].map((id) => ({ toolUseId: id, content: id })), [], undefined, undefined);
         guard.abandon('test');
         let annotated = false;
         void guard.whenAnnotated().then(() => { annotated = true; });