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

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

@@ -0,0 +1,130 @@
+/**
+ * @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 StateSnapshotProcessorOptionsSchema = {
+    type: 'object',
+    properties: {
+        target: {
+            type: 'string',
+            enum: ['incremental', 'freeNTokens', 'max'],
+            nullable: true,
+        },
+        freeTokensTarget: { type: 'number', nullable: true },
+        model: { type: 'string', nullable: true },
+        systemInstruction: { type: 'string', nullable: true },
+    },
+    required: [],
+};
+export function createStateSnapshotProcessor(id, env, options) {
+    const generator = new SnapshotGenerator(env);
+    return {
+        id,
+        name: 'StateSnapshotProcessor',
+        process: async ({ targets, inbox }) => {
+            if (targets.length === 0) {
+                return targets;
+            }
+            // Determine what mode we are looking for: 'incremental' -> 'point-in-time', 'max' -> 'accumulate'
+            const strategy = options.target ?? 'max';
+            const expectedType = strategy === 'incremental' ? 'point-in-time' : 'accumulate';
+            // 1. Check Inbox for a completed Snapshot (The Fast Path)
+            const proposedSnapshots = inbox.getMessages('PROPOSED_SNAPSHOT');
+            if (proposedSnapshots.length > 0) {
+                // Filter for the snapshot type that matches our processor mode
+                const matchingSnapshots = proposedSnapshots.filter((s) => s.payload.type === expectedType);
+                // Sort by newest timestamp first (we want the most accumulated snapshot)
+                const sorted = [...matchingSnapshots].sort((a, b) => b.timestamp - a.timestamp);
+                for (const proposed of sorted) {
+                    const { consumedIds, newText } = proposed.payload;
+                    // Verify all consumed IDs still exist sequentially in targets
+                    const targetIds = new Set(targets.map((t) => t.id));
+                    const isValid = consumedIds.every((id) => targetIds.has(id));
+                    if (isValid) {
+                        // If valid, apply it!
+                        const newId = randomUUID();
+                        const snapshotNode = {
+                            id: newId,
+                            logicalParentId: newId,
+                            type: 'SNAPSHOT',
+                            timestamp: Date.now(),
+                            text: newText,
+                            abstractsIds: consumedIds,
+                        };
+                        // Remove the consumed nodes and insert the snapshot at the earliest index
+                        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, snapshotNode);
+                        }
+                        else {
+                            returnedNodes.unshift(snapshotNode);
+                        }
+                        inbox.consume(proposed.id);
+                        return returnedNodes;
+                    }
+                }
+            }
+            // 2. The Synchronous Backstop (The Slow Path)
+            let targetTokensToRemove = 0;
+            if (strategy === 'incremental') {
+                targetTokensToRemove = Infinity; // incremental implies removing as much as possible if no state is passed
+            }
+            else if (strategy === 'freeNTokens') {
+                targetTokensToRemove = options.freeTokensTarget ?? Infinity;
+            }
+            else if (strategy === 'max') {
+                targetTokensToRemove = Infinity;
+            }
+            let deficitAccumulator = 0;
+            const nodesToSummarize = [];
+            // Scan oldest to newest
+            for (const node of targets) {
+                if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+                    // Keep system prompt if it's the very first node
+                    // In a real system, system prompt is protected, but we double check
+                    continue;
+                }
+                nodesToSummarize.push(node);
+                deficitAccumulator += env.tokenCalculator.getTokenCost(node);
+                if (deficitAccumulator >= targetTokensToRemove)
+                    break;
+            }
+            if (nodesToSummarize.length < 2)
+                return targets; // Not enough context
+            try {
+                const snapshotText = await generator.synthesizeSnapshot(nodesToSummarize, options.systemInstruction);
+                const newId = randomUUID();
+                const snapshotNode = {
+                    id: newId,
+                    logicalParentId: newId,
+                    type: 'SNAPSHOT',
+                    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, snapshotNode);
+                }
+                else {
+                    returnedNodes.unshift(snapshotNode);
+                }
+                return returnedNodes;
+            }
+            catch (e) {
+                debugLogger.error('StateSnapshotProcessor failed sync backstop', e);
+                return targets;
+            }
+        },
+    };
+}
+//# sourceMappingURL=stateSnapshotProcessor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stateSnapshotProcessor.js","sourceRoot":"","sources":["../../../../src/context/processors/stateSnapshotProcessor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAOzD,MAAM,CAAC,MAAM,mCAAmC,GAC9C;IACE,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,aAAa,EAAE,aAAa,EAAE,KAAK,CAAC;YAC3C,QAAQ,EAAE,IAAI;SACf;QACD,gBAAgB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACpD,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACzC,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;KACtD;IACD,QAAQ,EAAE,EAAE;CACb,CAAC;AAEJ,MAAM,UAAU,4BAA4B,CAC1C,EAAU,EACV,GAAuB,EACvB,OAAsC;IAEtC,MAAM,SAAS,GAAG,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAE7C,OAAO;QACL,EAAE;QACF,IAAI,EAAE,wBAAwB;QAC9B,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAe,EAAE,EAAE;YACjD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,OAAO,CAAC;YACjB,CAAC;YAED,kGAAkG;YAClG,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;YACzC,MAAM,YAAY,GAChB,QAAQ,KAAK,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,YAAY,CAAC;YAE9D,0DAA0D;YAC1D,MAAM,iBAAiB,GAAG,KAAK,CAAC,WAAW,CAIxC,mBAAmB,CAAC,CAAC;YAExB,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACjC,+DAA+D;gBAC/D,MAAM,iBAAiB,GAAG,iBAAiB,CAAC,MAAM,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,YAAY,CACvC,CAAC;gBAEF,yEAAyE;gBACzE,MAAM,MAAM,GAAG,CAAC,GAAG,iBAAiB,CAAC,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CACpC,CAAC;gBAEF,KAAK,MAAM,QAAQ,IAAI,MAAM,EAAE,CAAC;oBAC9B,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC;oBAElD,8DAA8D;oBAC9D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBACpD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;oBAE7D,IAAI,OAAO,EAAE,CAAC;wBACZ,sBAAsB;wBACtB,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;wBAE3B,MAAM,YAAY,GAAa;4BAC7B,EAAE,EAAE,KAAK;4BACT,eAAe,EAAE,KAAK;4BACtB,IAAI,EAAE,UAAU;4BAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;4BACrB,IAAI,EAAE,OAAO;4BACb,YAAY,EAAE,WAAW;yBAC1B,CAAC;wBAEF,0EAA0E;wBAC1E,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CACnC,CAAC;wBACF,MAAM,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3B,CAAC;wBAEF,IAAI,eAAe,KAAK,CAAC,CAAC,EAAE,CAAC;4BAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;4BACzC,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;wBAC7C,CAAC;6BAAM,CAAC;4BACN,aAAa,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;wBACtC,CAAC;wBAED,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;wBAC3B,OAAO,aAAa,CAAC;oBACvB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,8CAA8C;YAC9C,IAAI,oBAAoB,GAAG,CAAC,CAAC;YAE7B,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;gBAC/B,oBAAoB,GAAG,QAAQ,CAAC,CAAC,yEAAyE;YAC5G,CAAC;iBAAM,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;gBACtC,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,IAAI,QAAQ,CAAC;YAC9D,CAAC;iBAAM,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;gBAC9B,oBAAoB,GAAG,QAAQ,CAAC;YAClC,CAAC;YAED,IAAI,kBAAkB,GAAG,CAAC,CAAC;YAC3B,MAAM,gBAAgB,GAAmB,EAAE,CAAC;YAE5C,wBAAwB;YACxB,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;gBAC3B,IAAI,IAAI,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;oBAC7D,iDAAiD;oBACjD,oEAAoE;oBACpE,SAAS;gBACX,CAAC;gBAED,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC5B,kBAAkB,IAAI,GAAG,CAAC,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;gBAE7D,IAAI,kBAAkB,IAAI,oBAAoB;oBAAE,MAAM;YACxD,CAAC;YAED,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,OAAO,CAAC,CAAC,qBAAqB;YAEtE,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,MAAM,SAAS,CAAC,kBAAkB,CACrD,gBAAgB,EAChB,OAAO,CAAC,iBAAiB,CAC1B,CAAC;gBACF,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;gBAC3B,MAAM,YAAY,GAAa;oBAC7B,EAAE,EAAE,KAAK;oBACT,eAAe,EAAE,KAAK;oBACtB,IAAI,EAAE,UAAU;oBAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;oBACrB,IAAI,EAAE,YAAY;oBAClB,YAAY,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAChD,CAAC;gBAEF,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACtD,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CACnC,CAAC;gBACF,MAAM,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3B,CAAC;gBAEF,IAAI,eAAe,KAAK,CAAC,CAAC,EAAE,CAAC;oBAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;oBACzC,aAAa,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;gBAC7C,CAAC;qBAAM,CAAC;oBACN,aAAa,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;gBACtC,CAAC;gBAED,OAAO,aAAa,CAAC;YACvB,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,WAAW,CAAC,KAAK,CAAC,6CAA6C,EAAE,CAAC,CAAC,CAAC;gBACpE,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

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

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

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

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createStateSnapshotProcessor } from './stateSnapshotProcessor.js';
+import { createMockEnvironment, createDummyNode, createMockProcessArgs, } from '../testing/contextTestUtils.js';
+describe('StateSnapshotProcessor', () => {
+    it('should ignore if budget is satisfied', async () => {
+        const env = createMockEnvironment();
+        const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, {
+            target: 'incremental',
+        });
+        const targets = [createDummyNode('ep1', 'USER_PROMPT')];
+        const result = await processor.process(createMockProcessArgs(targets));
+        expect(result).toBe(targets); // Strict equality
+    });
+    it('should apply a valid snapshot from the Inbox (Fast Path)', async () => {
+        const env = createMockEnvironment();
+        const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, {
+            target: 'incremental',
+        });
+        const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+        const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+        const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+        const targets = [nodeA, nodeB, nodeC];
+        // The async background pipeline created a snapshot of A and B
+        const messages = [
+            {
+                id: 'msg-1',
+                topic: 'PROPOSED_SNAPSHOT',
+                timestamp: Date.now(),
+                payload: {
+                    consumedIds: ['node-A', 'node-B'],
+                    newText: '<compressed A and B>',
+                    type: 'point-in-time',
+                },
+            },
+        ];
+        const processArgs = createMockProcessArgs(targets, [], messages);
+        const result = await processor.process(processArgs);
+        // Should remove A and B, insert Snapshot, keep C
+        expect(result.length).toBe(2);
+        expect(result[0].type).toBe('SNAPSHOT');
+        expect(result[1].id).toBe('node-C');
+        // Should consume the message
+        expect(processArgs.inbox.getConsumedIds().has('msg-1')).toBe(true);
+    });
+    it('should reject a snapshot if the nodes were modified/deleted (Cache Invalidated)', async () => {
+        const env = createMockEnvironment();
+        const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, {
+            target: 'incremental',
+        });
+        // Make deficit 0 so we don't fall through to the sync backstop and fail the test that way
+        // node-A is MISSING (user deleted it)
+        const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+        const targets = [nodeB];
+        const messages = [
+            {
+                id: 'msg-1',
+                topic: 'PROPOSED_SNAPSHOT',
+                timestamp: Date.now(),
+                payload: {
+                    consumedIds: ['node-A', 'node-B'],
+                    newText: '<compressed A and B>',
+                },
+            },
+        ];
+        const processArgs = createMockProcessArgs(targets, [], messages);
+        const result = await processor.process(processArgs);
+        // Because deficit is 0, and Inbox was rejected, nothing should change
+        expect(result.length).toBe(1);
+        expect(result[0].id).toBe('node-B');
+        expect(processArgs.inbox.getConsumedIds().has('msg-1')).toBe(false);
+    });
+    it('should fall back to sync backstop if inbox is empty', async () => {
+        const env = createMockEnvironment();
+        const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, { target: 'max' }); // Summarize all
+        const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+        const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+        const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+        const targets = [nodeA, nodeB, nodeC];
+        const result = await processor.process(createMockProcessArgs(targets));
+        // Should synthesize a new snapshot synchronously
+        expect(env.llmClient.generateContent).toHaveBeenCalled();
+        expect(result.length).toBe(2); // nodeA is skipped as "system prompt", snapshot + nodeA
+        expect(result[1].type).toBe('SNAPSHOT');
+    });
+});
+//# sourceMappingURL=stateSnapshotProcessor.test.js.map

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

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

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

@@ -0,0 +1,8 @@
+import type { JSONSchemaType } from 'ajv';
+import type { ContextProcessor } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+export interface ToolMaskingProcessorOptions {
+    stringLengthThresholdTokens: number;
+}
+export declare const ToolMaskingProcessorOptionsSchema: JSONSchemaType<ToolMaskingProcessorOptions>;
+export declare function createToolMaskingProcessor(id: string, env: ContextEnvironment, options: ToolMaskingProcessorOptions): ContextProcessor;

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

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { sanitizeFilenamePart } from '../../utils/fileUtils.js';
+import { ACTIVATE_SKILL_TOOL_NAME, MEMORY_TOOL_NAME, ASK_USER_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME, EXIT_PLAN_MODE_TOOL_NAME, } from '../../tools/tool-names.js';
+export const ToolMaskingProcessorOptionsSchema = {
+    type: 'object',
+    properties: {
+        stringLengthThresholdTokens: { type: 'number' },
+    },
+    required: ['stringLengthThresholdTokens'],
+};
+const UNMASKABLE_TOOLS = new Set([
+    ACTIVATE_SKILL_TOOL_NAME,
+    MEMORY_TOOL_NAME,
+    ASK_USER_TOOL_NAME,
+    ENTER_PLAN_MODE_TOOL_NAME,
+    EXIT_PLAN_MODE_TOOL_NAME,
+]);
+function isMaskableValue(val) {
+    if (val === null ||
+        typeof val === 'string' ||
+        typeof val === 'number' ||
+        typeof val === 'boolean') {
+        return true;
+    }
+    if (Array.isArray(val)) {
+        return val.every(isMaskableValue);
+    }
+    if (typeof val === 'object') {
+        return Object.values(val).every(isMaskableValue);
+    }
+    return false;
+}
+function isMaskableRecord(val) {
+    return (typeof val === 'object' &&
+        val !== null &&
+        !Array.isArray(val) &&
+        isMaskableValue(val));
+}
+export function createToolMaskingProcessor(id, env, options) {
+    const isAlreadyMasked = (text) => text.includes('<tool_output_masked>');
+    return {
+        id,
+        name: 'ToolMaskingProcessor',
+        process: async ({ targets }) => {
+            const maskingConfig = options;
+            if (!maskingConfig)
+                return targets;
+            if (targets.length === 0)
+                return targets;
+            const limitChars = env.tokenCalculator.tokensToChars(maskingConfig.stringLengthThresholdTokens);
+            let toolOutputsDir = path.join(env.projectTempDir, 'tool-outputs');
+            const sessionId = env.sessionId;
+            if (sessionId) {
+                toolOutputsDir = path.join(toolOutputsDir, `session-${sanitizeFilenamePart(sessionId)}`);
+            }
+            let directoryCreated = false;
+            const handleMasking = async (content, toolName, callId, nodeType) => {
+                if (!directoryCreated) {
+                    await fs.mkdir(toolOutputsDir, { recursive: true });
+                    directoryCreated = true;
+                }
+                const fileName = `${sanitizeFilenamePart(toolName).toLowerCase()}_${sanitizeFilenamePart(callId).toLowerCase()}_${nodeType}_${randomUUID()}.txt`;
+                const filePath = path.join(toolOutputsDir, fileName);
+                await fs.writeFile(filePath, content);
+                const fileSizeMB = (Buffer.byteLength(content, 'utf8') /
+                    1024 /
+                    1024).toFixed(2);
+                const totalLines = content.split('\n').length;
+                return `<tool_output_masked>\n[Tool ${nodeType} string (${fileSizeMB}MB, ${totalLines} lines) masked to preserve context window. Full string saved to: ${filePath}]\n</tool_output_masked>`;
+            };
+            const returnedNodes = [];
+            for (const node of targets) {
+                switch (node.type) {
+                    case 'TOOL_EXECUTION': {
+                        const toolName = node.toolName;
+                        if (toolName && UNMASKABLE_TOOLS.has(toolName)) {
+                            returnedNodes.push(node);
+                            break;
+                        }
+                        const callId = node.id || Date.now().toString();
+                        const maskAsync = async (obj, nodeType) => {
+                            if (typeof obj === 'string') {
+                                if (obj.length > limitChars && !isAlreadyMasked(obj)) {
+                                    const newString = await handleMasking(obj, toolName || 'unknown', callId, nodeType);
+                                    return { masked: newString, changed: true };
+                                }
+                                return { masked: obj, changed: false };
+                            }
+                            if (Array.isArray(obj)) {
+                                let changed = false;
+                                const masked = [];
+                                for (const item of obj) {
+                                    const res = await maskAsync(item, nodeType);
+                                    if (res.changed)
+                                        changed = true;
+                                    masked.push(res.masked);
+                                }
+                                return { masked, changed };
+                            }
+                            if (typeof obj === 'object' && obj !== null) {
+                                let changed = false;
+                                const masked = {};
+                                for (const [key, value] of Object.entries(obj)) {
+                                    const res = await maskAsync(value, nodeType);
+                                    if (res.changed)
+                                        changed = true;
+                                    masked[key] = res.masked;
+                                }
+                                return { masked, changed };
+                            }
+                            return { masked: obj, changed: false };
+                        };
+                        const rawIntent = node.intent;
+                        const rawObs = node.observation;
+                        if (!isMaskableRecord(rawIntent) || !isMaskableValue(rawObs)) {
+                            returnedNodes.push(node);
+                            break;
+                        }
+                        const intentRes = await maskAsync(rawIntent, 'intent');
+                        const obsRes = await maskAsync(rawObs, 'observation');
+                        if (intentRes.changed || obsRes.changed) {
+                            const maskedIntent = isMaskableRecord(intentRes.masked)
+                                ? intentRes.masked
+                                : undefined;
+                            // Handle observation explicitly as string vs object
+                            const maskedObs = typeof obsRes.masked === 'string'
+                                ? { message: obsRes.masked }
+                                : isMaskableRecord(obsRes.masked)
+                                    ? obsRes.masked
+                                    : undefined;
+                            const newIntentTokens = env.tokenCalculator.estimateTokensForParts([
+                                {
+                                    functionCall: {
+                                        name: toolName || 'unknown',
+                                        args: maskedIntent,
+                                        id: callId,
+                                    },
+                                },
+                            ]);
+                            let obsPart = {};
+                            if (maskedObs) {
+                                obsPart = {
+                                    functionResponse: {
+                                        name: toolName || 'unknown',
+                                        response: maskedObs,
+                                        id: callId,
+                                    },
+                                };
+                            }
+                            const newObsTokens = env.tokenCalculator.estimateTokensForParts([
+                                obsPart,
+                            ]);
+                            const tokensSaved = env.tokenCalculator.getTokenCost(node) -
+                                (newIntentTokens + newObsTokens);
+                            if (tokensSaved > 0) {
+                                const maskedNode = {
+                                    ...node,
+                                    id: randomUUID(), // Modified, so generate new ID
+                                    intent: maskedIntent ?? node.intent,
+                                    observation: maskedObs ?? node.observation,
+                                    tokens: {
+                                        intent: newIntentTokens,
+                                        observation: newObsTokens,
+                                    },
+                                    replacesId: node.id,
+                                };
+                                returnedNodes.push(maskedNode);
+                            }
+                            else {
+                                returnedNodes.push(node);
+                            }
+                        }
+                        else {
+                            returnedNodes.push(node);
+                        }
+                        break;
+                    }
+                    default:
+                        returnedNodes.push(node);
+                        break;
+                }
+            }
+            return returnedNodes;
+        },
+    };
+}
+//# sourceMappingURL=toolMaskingProcessor.js.map

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

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

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

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

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

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createToolMaskingProcessor } from './toolMaskingProcessor.js';
+import { createMockProcessArgs, createMockEnvironment, createDummyToolNode, } from '../testing/contextTestUtils.js';
+describe('ToolMaskingProcessor', () => {
+    it('should write large strings to disk and replace them with a masked pointer', async () => {
+        const env = createMockEnvironment();
+        // env uses charsPerToken=1 natively.
+        // original string lengths > stringLengthThresholdTokens (which is 10) will be masked
+        const processor = createToolMaskingProcessor('ToolMaskingProcessor', env, {
+            stringLengthThresholdTokens: 10,
+        });
+        const longString = 'A'.repeat(500); // 500 chars
+        const toolStep = createDummyToolNode('ep1', 50, 500, {
+            observation: {
+                result: longString,
+                metadata: 'short', // 5 chars, will not be masked
+            },
+        });
+        const result = await processor.process(createMockProcessArgs([toolStep]));
+        expect(result.length).toBe(1);
+        const masked = result[0];
+        // It should have generated a new ID because it modified it
+        expect(masked.id).not.toBe(toolStep.id);
+        // It should have masked the observation
+        const obs = masked.observation;
+        expect(obs.result).toContain('<tool_output_masked>');
+        expect(obs.metadata).toBe('short'); // Untouched
+    });
+    it('should skip unmaskable tools', async () => {
+        const env = createMockEnvironment();
+        const processor = createToolMaskingProcessor('ToolMaskingProcessor', env, {
+            stringLengthThresholdTokens: 10,
+        });
+        const toolStep = createDummyToolNode('ep1', 10, 10, {
+            toolName: 'activate_skill',
+            observation: {
+                result: 'this is a really long string that normally would get masked but wont because of the tool name',
+            },
+        });
+        const result = await processor.process(createMockProcessArgs([toolStep]));
+        // Returned the exact same object reference
+        expect(result[0]).toBe(toolStep);
+    });
+});
+//# sourceMappingURL=toolMaskingProcessor.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toolMaskingProcessor.test.js","sourceRoot":"","sources":["../../../../src/context/processors/toolMaskingProcessor.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,gCAAgC,CAAC;AAGxC,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,2EAA2E,EAAE,KAAK,IAAI,EAAE;QACzF,MAAM,GAAG,GAAG,qBAAqB,EAAE,CAAC;QACpC,qCAAqC;QACrC,qFAAqF;QAErF,MAAM,SAAS,GAAG,0BAA0B,CAAC,sBAAsB,EAAE,GAAG,EAAE;YACxE,2BAA2B,EAAE,EAAE;SAChC,CAAC,CAAC;QAEH,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY;QAEhD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE;YACnD,WAAW,EAAE;gBACX,MAAM,EAAE,UAAU;gBAClB,QAAQ,EAAE,OAAO,EAAE,8BAA8B;aAClD;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAE1E,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAkB,CAAC;QAE1C,2DAA2D;QAC3D,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAExC,wCAAwC;QACxC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAmD,CAAC;QACvE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;QAC5C,MAAM,GAAG,GAAG,qBAAqB,EAAE,CAAC;QAEpC,MAAM,SAAS,GAAG,0BAA0B,CAAC,sBAAsB,EAAE,GAAG,EAAE;YACxE,2BAA2B,EAAE,EAAE;SAChC,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE;YAClD,QAAQ,EAAE,gBAAgB;YAC1B,WAAW,EAAE;gBACX,MAAM,EACJ,+FAA+F;aAClG;SACF,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAE1E,2CAA2C;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/context/system-tests/lifecycle.golden.test.d.ts

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