@machina.ai/cell-cli-core 1.38.1-rc2 → 1.40.1-rc2

package/dist/src/context/processors/nodeTruncationProcessor.js

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import { truncateProportionally } from '../truncation.js';
+export const NodeTruncationProcessorOptionsSchema = {
+    type: 'object',
+    properties: {
+        maxTokensPerNode: { type: 'number' },
+    },
+    required: ['maxTokensPerNode'],
+};
+export function createNodeTruncationProcessor(id, env, options) {
+    const tryApplySquash = (text, limitChars) => {
+        const originalLength = text.length;
+        if (originalLength <= limitChars)
+            return null;
+        const newText = truncateProportionally(text, limitChars, `\n\n[... OMITTED ${originalLength - limitChars} chars ...]\n\n`);
+        if (newText !== text) {
+            // Using accurate TokenCalculator instead of simple math
+            const newTokens = env.tokenCalculator.estimateTokensForString(newText);
+            const oldTokens = env.tokenCalculator.estimateTokensForString(text);
+            const tokensSaved = oldTokens - newTokens;
+            if (tokensSaved > 0) {
+                return { text: newText, newTokens, oldTokens, tokensSaved };
+            }
+        }
+        return null;
+    };
+    return {
+        id,
+        name: 'NodeTruncationProcessor',
+        process: async ({ targets }) => {
+            if (targets.length === 0) {
+                return targets;
+            }
+            const { maxTokensPerNode } = options;
+            const limitChars = env.tokenCalculator.tokensToChars(maxTokensPerNode);
+            const returnedNodes = [];
+            for (const node of targets) {
+                switch (node.type) {
+                    case 'USER_PROMPT': {
+                        let modified = false;
+                        const newParts = [...node.semanticParts];
+                        for (let j = 0; j < node.semanticParts.length; j++) {
+                            const part = node.semanticParts[j];
+                            if (part.type === 'text') {
+                                const squashResult = tryApplySquash(part.text, limitChars);
+                                if (squashResult) {
+                                    newParts[j] = { type: 'text', text: squashResult.text };
+                                    modified = true;
+                                }
+                            }
+                        }
+                        if (modified) {
+                            returnedNodes.push({
+                                ...node,
+                                id: randomUUID(),
+                                semanticParts: newParts,
+                                replacesId: node.id,
+                            });
+                        }
+                        else {
+                            returnedNodes.push(node);
+                        }
+                        break;
+                    }
+                    case 'AGENT_THOUGHT': {
+                        const squashResult = tryApplySquash(node.text, limitChars);
+                        if (squashResult) {
+                            returnedNodes.push({
+                                ...node,
+                                id: randomUUID(),
+                                text: squashResult.text,
+                                replacesId: node.id,
+                            });
+                        }
+                        else {
+                            returnedNodes.push(node);
+                        }
+                        break;
+                    }
+                    case 'AGENT_YIELD': {
+                        const squashResult = tryApplySquash(node.text, limitChars);
+                        if (squashResult) {
+                            returnedNodes.push({
+                                ...node,
+                                id: randomUUID(),
+                                text: squashResult.text,
+                                replacesId: node.id,
+                            });
+                        }
+                        else {
+                            returnedNodes.push(node);
+                        }
+                        break;
+                    }
+                    default:
+                        returnedNodes.push(node);
+                        break;
+                }
+            }
+            return returnedNodes;
+        },
+    };
+}
+//# sourceMappingURL=nodeTruncationProcessor.js.map

package/dist/src/context/processors/nodeTruncationProcessor.js.map

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

package/dist/src/context/processors/nodeTruncationProcessor.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/context/processors/nodeTruncationProcessor.test.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createNodeTruncationProcessor } from './nodeTruncationProcessor.js';
+import { createMockProcessArgs, createMockEnvironment, createDummyNode, } from '../testing/contextTestUtils.js';
+describe('NodeTruncationProcessor', () => {
+    it('should truncate nodes that exceed maxTokensPerNode', async () => {
+        // env.tokenCalculator uses charsPerToken=1 natively.
+        const env = createMockEnvironment();
+        const processor = createNodeTruncationProcessor('NodeTruncationProcessor', env, {
+            maxTokensPerNode: 10, // 10 chars limit
+        });
+        const longText = 'A'.repeat(50); // 50 tokens
+        const prompt = createDummyNode('ep1', 'USER_PROMPT', 50, {
+            semanticParts: [{ type: 'text', text: longText }],
+        }, 'prompt-id');
+        const thought = createDummyNode('ep1', 'AGENT_THOUGHT', 50, {
+            text: longText,
+        }, 'thought-id');
+        const yieldNode = createDummyNode('ep1', 'AGENT_YIELD', 50, {
+            text: longText,
+        }, 'yield-id');
+        const targets = [prompt, thought, yieldNode];
+        const result = await processor.process(createMockProcessArgs(targets));
+        expect(result.length).toBe(3);
+        // 1. User Prompt
+        const squashedPrompt = result[0];
+        expect(squashedPrompt.id).not.toBe(prompt.id);
+        expect(squashedPrompt.semanticParts[0].type).toBe('text');
+        assert(squashedPrompt.semanticParts[0].type === 'text');
+        expect(squashedPrompt.semanticParts[0].text).toContain('[... OMITTED');
+        // 2. Agent Thought
+        const squashedThought = result[1];
+        expect(squashedThought.id).not.toBe(thought.id);
+        expect(squashedThought.text).toContain('[... OMITTED');
+        // 3. Agent Yield
+        const squashedYield = result[2];
+        expect(squashedYield.id).not.toBe(yieldNode.id);
+        expect(squashedYield.text).toContain('[... OMITTED');
+    });
+    it('should ignore nodes that are below maxTokensPerNode', async () => {
+        const env = createMockEnvironment();
+        const processor = createNodeTruncationProcessor('NodeTruncationProcessor', env, {
+            maxTokensPerNode: 100, // 100 chars limit
+        });
+        const shortText = 'Short text'; // 10 chars
+        const prompt = createDummyNode('ep1', 'USER_PROMPT', 10, {
+            semanticParts: [{ type: 'text', text: shortText }],
+        }, 'prompt-id');
+        const thought = createDummyNode('ep1', 'AGENT_THOUGHT', 13, {
+            text: 'Short thought', // 13 chars
+        }, 'thought-id');
+        const targets = [prompt, thought];
+        const result = await processor.process(createMockProcessArgs(targets));
+        expect(result.length).toBe(2);
+        // 1. User Prompt (untouched)
+        const squashedPrompt = result[0];
+        expect(squashedPrompt.id).toBe(prompt.id);
+        assert(squashedPrompt.semanticParts[0].type === 'text');
+        expect(squashedPrompt.semanticParts[0].text).not.toContain('[... OMITTED');
+        // 2. Agent Thought (untouched)
+        const untouchedThought = result[1];
+        expect(untouchedThought.id).toBe(thought.id);
+        expect(untouchedThought.text).not.toContain('[... OMITTED');
+    });
+});
+//# sourceMappingURL=nodeTruncationProcessor.test.js.map

package/dist/src/context/processors/nodeTruncationProcessor.test.js.map

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

package/dist/src/context/processors/rollingSummaryProcessor.d.ts

@@ -0,0 +1,8 @@
+import type { JSONSchemaType } from 'ajv';
+import type { ContextProcessor, BackstopTargetOptions } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+export interface RollingSummaryProcessorOptions extends BackstopTargetOptions {
+    systemInstruction?: string;
+}
+export declare const RollingSummaryProcessorOptionsSchema: JSONSchemaType<RollingSummaryProcessorOptions>;
+export declare function createRollingSummaryProcessor(id: string, env: ContextEnvironment, options: RollingSummaryProcessorOptions): ContextProcessor;

package/dist/src/context/processors/rollingSummaryProcessor.js

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { LlmRole } from '../../telemetry/llmRole.js';
+export const RollingSummaryProcessorOptionsSchema = {
+    type: 'object',
+    properties: {
+        target: {
+            type: 'string',
+            enum: ['incremental', 'freeNTokens', 'max'],
+            nullable: true,
+        },
+        freeTokensTarget: { type: 'number', nullable: true },
+        maxRollingSummaries: { type: 'number', nullable: true },
+        systemInstruction: { type: 'string', nullable: true },
+    },
+    required: [],
+};
+export function createRollingSummaryProcessor(id, env, options) {
+    const generateRollingSummary = async (nodes) => {
+        let transcript = '';
+        for (const node of nodes) {
+            let nodeContent = '';
+            if ('text' in node && typeof node.text === 'string') {
+                nodeContent = node.text;
+            }
+            else if ('semanticParts' in node) {
+                nodeContent = JSON.stringify(node.semanticParts);
+            }
+            else if ('observation' in node) {
+                nodeContent =
+                    typeof node.observation === 'string'
+                        ? node.observation
+                        : JSON.stringify(node.observation);
+            }
+            transcript += `[${node.type}]: ${nodeContent}\n`;
+        }
+        const systemPrompt = options.systemInstruction ??
+            `You are an expert context compressor. Your job is to drastically shorten the provided conversational transcript while preserving the absolute core semantic meaning, facts, and intent. Omit all conversational filler, pleasantries, or redundant information. Return ONLY the compressed summary.`;
+        const response = await env.llmClient.generateContent({
+            role: LlmRole.UTILITY_COMPRESSOR,
+            modelConfigKey: { model: 'gemini-3-flash-base' },
+            promptId: env.promptId,
+            abortSignal: new AbortController().signal,
+            contents: [{ role: 'user', parts: [{ text: transcript }] }],
+            systemInstruction: { role: 'system', parts: [{ text: systemPrompt }] },
+        });
+        const candidate = response.candidates?.[0];
+        const textPart = candidate?.content?.parts?.[0];
+        return textPart?.text || '';
+    };
+    return {
+        id,
+        name: 'RollingSummaryProcessor',
+        process: async ({ targets }) => {
+            if (targets.length === 0)
+                return targets;
+            const strategy = options.target ?? 'max';
+            const nodesToSummarize = [];
+            if (strategy === 'incremental') {
+                // 'incremental' simply summarizes the minimum viable chunk (the oldest 2 nodes), ignoring token math.
+                for (const node of targets) {
+                    if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+                        continue; // Keep system prompt
+                    }
+                    nodesToSummarize.push(node);
+                    if (nodesToSummarize.length >= 2)
+                        break; // We have enough for a minimum rolling summary
+                }
+            }
+            else {
+                let targetTokensToRemove = 0;
+                if (strategy === 'freeNTokens') {
+                    targetTokensToRemove = options.freeTokensTarget ?? Infinity;
+                }
+                else if (strategy === 'max') {
+                    targetTokensToRemove = Infinity;
+                }
+                if (targetTokensToRemove > 0) {
+                    let deficitAccumulator = 0;
+                    for (const node of targets) {
+                        if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+                            continue; // Keep system prompt
+                        }
+                        nodesToSummarize.push(node);
+                        deficitAccumulator += env.tokenCalculator.getTokenCost(node);
+                        if (deficitAccumulator >= targetTokensToRemove)
+                            break;
+                    }
+                }
+            }
+            if (nodesToSummarize.length < 2)
+                return targets; // Not enough context to summarize
+            try {
+                // Synthesize the rolling summary synchronously
+                const snapshotText = await generateRollingSummary(nodesToSummarize);
+                const newId = randomUUID();
+                const summaryNode = {
+                    id: newId,
+                    logicalParentId: newId,
+                    type: 'ROLLING_SUMMARY',
+                    timestamp: Date.now(),
+                    text: snapshotText,
+                    abstractsIds: nodesToSummarize.map((n) => n.id),
+                };
+                const consumedIds = nodesToSummarize.map((n) => n.id);
+                const returnedNodes = targets.filter((t) => !consumedIds.includes(t.id));
+                const firstRemovedIdx = targets.findIndex((t) => consumedIds.includes(t.id));
+                if (firstRemovedIdx !== -1) {
+                    const idx = Math.max(0, firstRemovedIdx);
+                    returnedNodes.splice(idx, 0, summaryNode);
+                }
+                else {
+                    returnedNodes.unshift(summaryNode);
+                }
+                return returnedNodes;
+            }
+            catch (e) {
+                debugLogger.error('RollingSummaryProcessor failed sync backstop', e);
+                return targets;
+            }
+        },
+    };
+}
+//# sourceMappingURL=rollingSummaryProcessor.js.map

package/dist/src/context/processors/rollingSummaryProcessor.js.map

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

package/dist/src/context/processors/rollingSummaryProcessor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/context/processors/rollingSummaryProcessor.test.js

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createRollingSummaryProcessor } from './rollingSummaryProcessor.js';
+import { createMockProcessArgs, createMockEnvironment, createDummyNode, } from '../testing/contextTestUtils.js';
+describe('RollingSummaryProcessor', () => {
+    it('should initialize with correct default options', () => {
+        const env = createMockEnvironment();
+        const processor = createRollingSummaryProcessor('RollingSummaryProcessor', env, {
+            target: 'incremental',
+        });
+        expect(processor.id).toBe('RollingSummaryProcessor');
+    });
+    it('should summarize older nodes when the deficit exceeds the threshold', async () => {
+        // env.tokenCalculator uses charsPerToken=1 based on createMockEnvironment
+        const env = createMockEnvironment();
+        // We want to free exactly 100 tokens.
+        // We will supply nodes that cost 50 tokens each.
+        const processor = createRollingSummaryProcessor('RollingSummaryProcessor', env, {
+            target: 'freeNTokens',
+            freeTokensTarget: 100,
+        });
+        const text50 = 'A'.repeat(50);
+        const targets = [
+            createDummyNode('ep1', 'USER_PROMPT', 50, { semanticParts: [{ type: 'text', text: text50 }] }, 'id1'),
+            createDummyNode('ep1', 'AGENT_THOUGHT', 50, { text: text50 }, 'id2'),
+            createDummyNode('ep1', 'AGENT_YIELD', 50, { text: text50 }, 'id3'),
+        ];
+        const result = await processor.process(createMockProcessArgs(targets));
+        // 3 nodes at 50 cost each.
+        // The first node (id1) is the initial USER_PROMPT and is always skipped by RollingSummaryProcessor.
+        // Node id2 adds 50 deficit. Node id3 adds 50 deficit. Total = 100 deficit, which hits the target break point.
+        // Thus, id2 and id3 are summarized into a new ROLLING_SUMMARY node.
+        expect(result.length).toBe(2);
+        expect(result[0].type).toBe('USER_PROMPT');
+        expect(result[1].type).toBe('ROLLING_SUMMARY');
+    });
+    it('should preserve targets if deficit does not trigger summary', async () => {
+        const env = createMockEnvironment();
+        // We want to free 100 tokens, but our nodes will only cost 10 tokens each.
+        const processor = createRollingSummaryProcessor('RollingSummaryProcessor', env, {
+            target: 'freeNTokens',
+            freeTokensTarget: 100,
+        });
+        const text10 = 'A'.repeat(10);
+        const targets = [
+            createDummyNode('ep1', 'USER_PROMPT', 10, { semanticParts: [{ type: 'text', text: text10 }] }, 'id1'),
+            createDummyNode('ep1', 'AGENT_THOUGHT', 10, { text: text10 }, 'id2'),
+        ];
+        const result = await processor.process(createMockProcessArgs(targets));
+        // Deficit accumulator reaches 10. This is < 100 limit, and total summarizable nodes < 2 anyway.
+        expect(result.length).toBe(2);
+        expect(result[0].type).toBe('USER_PROMPT');
+        expect(result[1].type).toBe('AGENT_THOUGHT');
+    });
+});
+//# sourceMappingURL=rollingSummaryProcessor.test.js.map

package/dist/src/context/processors/rollingSummaryProcessor.test.js.map

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

package/dist/src/context/processors/stateSnapshotAsyncProcessor.d.ts

@@ -0,0 +1,9 @@
+import type { JSONSchemaType } from 'ajv';
+import type { AsyncContextProcessor } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+export interface StateSnapshotAsyncProcessorOptions {
+    type?: 'accumulate' | 'point-in-time';
+    systemInstruction?: string;
+}
+export declare const StateSnapshotAsyncProcessorOptionsSchema: JSONSchemaType<StateSnapshotAsyncProcessorOptions>;
+export declare function createStateSnapshotAsyncProcessor(id: string, env: ContextEnvironment, options: StateSnapshotAsyncProcessorOptions): AsyncContextProcessor;

package/dist/src/context/processors/stateSnapshotAsyncProcessor.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import { SnapshotGenerator } from '../utils/snapshotGenerator.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+export const StateSnapshotAsyncProcessorOptionsSchema = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            enum: ['accumulate', 'point-in-time'],
+            nullable: true,
+        },
+        systemInstruction: { type: 'string', nullable: true },
+    },
+    required: [],
+};
+export function createStateSnapshotAsyncProcessor(id, env, options) {
+    const generator = new SnapshotGenerator(env);
+    return {
+        id,
+        name: 'StateSnapshotAsyncProcessor',
+        process: async ({ targets, inbox }) => {
+            if (targets.length === 0)
+                return;
+            try {
+                let nodesToSummarize = [...targets];
+                let previousConsumedIds = [];
+                const processorType = options.type ?? 'point-in-time';
+                if (processorType === 'accumulate') {
+                    // Look for the most recent unconsumed accumulate snapshot in the inbox
+                    const proposedSnapshots = inbox.getMessages('PROPOSED_SNAPSHOT');
+                    const accumulateSnapshots = proposedSnapshots.filter((s) => s.payload.type === 'accumulate');
+                    if (accumulateSnapshots.length > 0) {
+                        // Sort to find the most recent
+                        const latest = [...accumulateSnapshots].sort((a, b) => b.timestamp - a.timestamp)[0];
+                        // Consume the old draft so the inbox doesn't fill up with stale drafts
+                        inbox.consume(latest.id);
+                        // And we must persist its consumption back to the live inbox immediately,
+                        // because we are effectively "taking" it from the shelf to modify.
+                        env.inbox.drainConsumed(new Set([latest.id]));
+                        previousConsumedIds = latest.payload.consumedIds;
+                        // Prepend a synthetic node representing the previous rolling state
+                        const previousStateNode = {
+                            id: randomUUID(),
+                            logicalParentId: '',
+                            type: 'SNAPSHOT',
+                            timestamp: latest.timestamp,
+                            text: latest.payload.newText,
+                        };
+                        nodesToSummarize = [previousStateNode, ...targets];
+                    }
+                }
+                const snapshotText = await generator.synthesizeSnapshot(nodesToSummarize, options.systemInstruction);
+                const newConsumedIds = [
+                    ...previousConsumedIds,
+                    ...targets.map((t) => t.id),
+                ];
+                // In V2, async pipelines communicate their work to the inbox, and the processor picks it up.
+                env.inbox.publish('PROPOSED_SNAPSHOT', {
+                    newText: snapshotText,
+                    consumedIds: newConsumedIds,
+                    type: processorType,
+                });
+            }
+            catch (e) {
+                debugLogger.error('StateSnapshotAsyncProcessor failed to generate snapshot', e);
+            }
+        },
+    };
+}
+//# sourceMappingURL=stateSnapshotAsyncProcessor.js.map

package/dist/src/context/processors/stateSnapshotAsyncProcessor.js.map

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

package/dist/src/context/processors/stateSnapshotAsyncProcessor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/context/processors/stateSnapshotAsyncProcessor.test.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createStateSnapshotAsyncProcessor } from './stateSnapshotAsyncProcessor.js';
+import { createMockEnvironment, createDummyNode, createMockProcessArgs, } from '../testing/contextTestUtils.js';
+describe('StateSnapshotAsyncProcessor', () => {
+    it('should generate a snapshot and publish it to the inbox', async () => {
+        const env = createMockEnvironment();
+        // Spy on the publish method
+        const publishSpy = vi.spyOn(env.inbox, 'publish');
+        const worker = createStateSnapshotAsyncProcessor('StateSnapshotAsyncProcessor', env, { type: 'point-in-time' });
+        const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+        const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+        const targets = [nodeA, nodeB];
+        await worker.process(createMockProcessArgs(targets, targets, []));
+        // Ensure generateContent was called
+        expect(env.llmClient.generateContent).toHaveBeenCalled();
+        // Verify it published to the inbox
+        expect(publishSpy).toHaveBeenCalledWith('PROPOSED_SNAPSHOT', expect.objectContaining({
+            newText: 'Mock LLM summary response',
+            consumedIds: ['node-A', 'node-B'],
+            type: 'point-in-time',
+        }));
+    });
+    it('should pull previous accumulate snapshot from inbox and append new targets', async () => {
+        const env = createMockEnvironment();
+        const publishSpy = vi.spyOn(env.inbox, 'publish');
+        const drainSpy = vi.spyOn(env.inbox, 'drainConsumed');
+        const worker = createStateSnapshotAsyncProcessor('StateSnapshotAsyncProcessor', env, { type: 'accumulate' });
+        const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+        const targets = [nodeC];
+        const inboxMessages = [
+            {
+                id: 'draft-1',
+                topic: 'PROPOSED_SNAPSHOT',
+                timestamp: Date.now() - 1000,
+                payload: {
+                    consumedIds: ['node-A', 'node-B'],
+                    newText: '<old snapshot>',
+                    type: 'accumulate',
+                },
+            },
+        ];
+        const args = createMockProcessArgs(targets, targets, inboxMessages);
+        await worker.process(args);
+        // The old draft should be consumed
+        expect(args.inbox.getConsumedIds().has('draft-1')).toBe(true);
+        expect(drainSpy).toHaveBeenCalledWith(expect.any(Set));
+        // The new publish should contain ALL consumed IDs (old + new)
+        expect(publishSpy).toHaveBeenCalledWith('PROPOSED_SNAPSHOT', expect.objectContaining({
+            newText: 'Mock LLM summary response',
+            consumedIds: ['node-A', 'node-B', 'node-C'], // Aggregated!
+            type: 'accumulate',
+        }));
+        // Verify the LLM was called with the old snapshot prepended
+        expect(env.llmClient.generateContent).toHaveBeenCalledWith(expect.objectContaining({
+            contents: expect.arrayContaining([
+                expect.objectContaining({
+                    parts: expect.arrayContaining([
+                        expect.objectContaining({
+                            text: expect.stringContaining('<old snapshot>'),
+                        }),
+                    ]),
+                }),
+            ]),
+        }));
+    });
+    it('should ignore empty targets', async () => {
+        const env = createMockEnvironment();
+        const publishSpy = vi.spyOn(env.inbox, 'publish');
+        const worker = createStateSnapshotAsyncProcessor('StateSnapshotAsyncProcessor', env, { type: 'accumulate' });
+        await worker.process(createMockProcessArgs([], [], []));
+        expect(env.llmClient.generateContent).not.toHaveBeenCalled();
+        expect(publishSpy).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=stateSnapshotAsyncProcessor.test.js.map

package/dist/src/context/processors/stateSnapshotAsyncProcessor.test.js.map

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

package/dist/src/context/processors/stateSnapshotProcessor.d.ts

@@ -0,0 +1,9 @@
+import type { JSONSchemaType } from 'ajv';
+import type { ContextProcessor, BackstopTargetOptions } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+export interface StateSnapshotProcessorOptions extends BackstopTargetOptions {
+    model?: string;
+    systemInstruction?: string;
+}
+export declare const StateSnapshotProcessorOptionsSchema: JSONSchemaType<StateSnapshotProcessorOptions>;
+export declare function createStateSnapshotProcessor(id: string, env: ContextEnvironment, options: StateSnapshotProcessorOptions): ContextProcessor;