@machina.ai/cell-cli-core 1.41.1-rc2 → 1.45.1-rc2

package/dist/src/context/utils/formatNodesForLlm.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Maps common tool names to semantic wrappers that improve LLM reading comprehension.
+ */
+function getSemanticToolWrapper(toolName) {
+    if (toolName.includes('search') || toolName.includes('grep'))
+        return `SEARCH RESULTS`;
+    if (toolName.includes('list') || toolName.includes('dir'))
+        return `WORKSPACE STRUCTURE`;
+    if (toolName.includes('shell') || toolName.includes('cmd'))
+        return `SHELL EXECUTION`;
+    if (toolName.includes('read') || toolName.includes('fetch'))
+        return `FILE/WEB CONTENT`;
+    return `TOOL RESPONSE`;
+}
+/**
+ * Formats a sequence of Context Graph nodes into a dense, human/LLM-readable text transcript.
+ * This is used by summarization processors (like SnapshotGenerator and RollingSummaryProcessor)
+ * to serialize the graph before passing it to an LLM.
+ */
+export function formatNodesForLlm(nodes, options = {}) {
+    const maxToolChars = options.maxToolResponseChars ?? 2000;
+    let transcript = '';
+    // Extract unique chronological turn IDs
+    const uniqueTurns = Array.from(new Set(nodes.map((n) => n.turnId).filter(Boolean)));
+    for (const node of nodes) {
+        const payload = node.payload;
+        let nodeContent = '';
+        if (payload.text) {
+            nodeContent = payload.text;
+        }
+        else if (payload.functionCall) {
+            nodeContent = `CALL: ${payload.functionCall.name}(${JSON.stringify(payload.functionCall.args)})`;
+        }
+        else if (payload.functionResponse) {
+            const toolName = payload.functionResponse.name || 'unknown_tool';
+            const rawResponse = JSON.stringify(payload.functionResponse.response);
+            const semanticWrapper = getSemanticToolWrapper(toolName);
+            let formattedResponse = rawResponse;
+            if (rawResponse.length > maxToolChars) {
+                const half = Math.floor(maxToolChars / 2);
+                const truncatedCount = rawResponse.length - maxToolChars;
+                formattedResponse = `${rawResponse.substring(0, half)}... [TRUNCATED ${truncatedCount} chars] ...${rawResponse.substring(rawResponse.length - half)}`;
+            }
+            nodeContent = `[${semanticWrapper} (${toolName})]: ${formattedResponse}`;
+        }
+        else {
+            // Fallback for unexpected node shapes
+            nodeContent = JSON.stringify(payload);
+        }
+        const role = (node.role || 'system').toUpperCase();
+        // Calculate relative turn index (e.g., -2, -1, 0)
+        let turnMarker = '';
+        if (node.turnId) {
+            const idx = uniqueTurns.indexOf(node.turnId);
+            if (idx !== -1) {
+                const relativeIdx = idx - (uniqueTurns.length - 1);
+                turnMarker = `[Turn ${relativeIdx}] `;
+            }
+        }
+        transcript += `${turnMarker}[${role}] [${node.type}]: ${nodeContent}\n`;
+    }
+    return transcript;
+}
+//# sourceMappingURL=formatNodesForLlm.js.map

package/dist/src/context/utils/formatNodesForLlm.js.map

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

package/dist/src/context/utils/formatNodesForLlm.test.d.ts

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

package/dist/src/context/utils/formatNodesForLlm.test.js

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { formatNodesForLlm } from './formatNodesForLlm.js';
+import { NodeType } from '../graph/types.js';
+describe('formatNodesForLlm', () => {
+    it('should format standard user and model text messages with relative turns', () => {
+        const nodes = [
+            {
+                id: '1',
+                turnId: 'turn-a',
+                type: NodeType.USER_PROMPT,
+                timestamp: 1000,
+                role: 'user',
+                payload: { text: 'Hello AI' },
+            },
+            {
+                id: '2',
+                turnId: 'turn-b',
+                type: NodeType.AGENT_THOUGHT,
+                timestamp: 1001,
+                role: 'model',
+                payload: { text: 'Hello User' },
+            },
+        ];
+        const result = formatNodesForLlm(nodes);
+        // turn-a is idx 0 (relative: -1)
+        // turn-b is idx 1 (relative: 0)
+        expect(result).toContain('[Turn -1] [USER] [USER_PROMPT]: Hello AI');
+        expect(result).toContain('[Turn 0] [MODEL] [AGENT_THOUGHT]: Hello User');
+    });
+    it('should format tool calls correctly', () => {
+        const nodes = [
+            {
+                id: '1',
+                turnId: '1',
+                type: NodeType.TOOL_EXECUTION,
+                timestamp: 1000,
+                role: 'model',
+                payload: {
+                    functionCall: { name: 'run_shell_command', args: { cmd: 'ls' } },
+                },
+            },
+        ];
+        const result = formatNodesForLlm(nodes);
+        expect(result).toContain('[Turn 0] [MODEL] [TOOL_EXECUTION]: CALL: run_shell_command({"cmd":"ls"})');
+    });
+    it('should format tool responses with semantic wrappers', () => {
+        const nodes = [
+            {
+                id: '1',
+                turnId: '1',
+                type: NodeType.TOOL_EXECUTION,
+                timestamp: 1000,
+                role: 'user',
+                payload: {
+                    functionResponse: {
+                        name: 'run_shell_command',
+                        response: { output: 'file.txt' },
+                    },
+                },
+            },
+        ];
+        const result = formatNodesForLlm(nodes);
+        expect(result).toContain('[Turn 0] [USER] [TOOL_EXECUTION]: [SHELL EXECUTION (run_shell_command)]: {"output":"file.txt"}');
+    });
+    it('should truncate massive tool responses and retain the semantic wrapper', () => {
+        // Generate a 3000 character string (exceeds the default 2000 limit)
+        const massiveOutput = 'A'.repeat(1500) + 'B'.repeat(1500);
+        const nodes = [
+            {
+                id: '1',
+                turnId: '1',
+                type: NodeType.TOOL_EXECUTION,
+                timestamp: 1000,
+                role: 'user',
+                payload: {
+                    functionResponse: {
+                        name: 'read_file',
+                        response: { output: massiveOutput },
+                    },
+                },
+            },
+        ];
+        const result = formatNodesForLlm(nodes, { maxToolResponseChars: 2000 });
+        expect(result).toContain('[FILE/WEB CONTENT (read_file)]: {"output":"AAAA');
+        expect(result).toContain('[TRUNCATED');
+        expect(result).toContain('chars] ...BBBB');
+        expect(result.length).toBeLessThan(2500); // Ensure it was actually truncated
+    });
+    it('should fallback to SYSTEM role if role is undefined', () => {
+        const nodes = [
+            {
+                id: '1',
+                turnId: '1',
+                type: NodeType.SNAPSHOT,
+                timestamp: 1000,
+                // @ts-expect-error testing undefined role
+                role: undefined,
+                payload: { text: 'Summary of past' },
+            },
+        ];
+        const result = formatNodesForLlm(nodes);
+        expect(result).toContain('[Turn 0] [SYSTEM] [SNAPSHOT]: Summary of past');
+    });
+});
+//# sourceMappingURL=formatNodesForLlm.test.js.map

package/dist/src/context/utils/formatNodesForLlm.test.js.map

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

package/dist/src/context/utils/invariantChecker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ConcreteNode } from '../graph/types.js';
+/**
+ * Validates structural and logical invariants of the Episodic Context Graph.
+ * Primarily used in debug mode to identify "smelly" states before they reach the LLM.
+ */
+export declare function checkContextInvariants(nodes: readonly ConcreteNode[], context: string): void;

package/dist/src/context/utils/invariantChecker.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { debugLogger } from '../../utils/debugLogger.js';
+/**
+ * Validates structural and logical invariants of the Episodic Context Graph.
+ * Primarily used in debug mode to identify "smelly" states before they reach the LLM.
+ */
+export function checkContextInvariants(nodes, context) {
+    const seenIds = new Set();
+    const duplicates = new Set();
+    for (const node of nodes) {
+        if (seenIds.has(node.id)) {
+            duplicates.add(node.id);
+        }
+        seenIds.add(node.id);
+    }
+    if (duplicates.size > 0) {
+        debugLogger.warn(`[InvariantCheck][${context}] Detected ${duplicates.size} duplicate nodes by ID: ${Array.from(duplicates).join(', ')}`);
+    }
+    // Check for orphan logic (nodes without turn association)
+    const orphans = nodes.filter((n) => !n.turnId);
+    if (orphans.length > 0) {
+        debugLogger.warn(`[InvariantCheck][${context}] Detected ${orphans.length} nodes without turnId.`);
+    }
+    // Check for timestamp linearity
+    for (let i = 1; i < nodes.length; i++) {
+        if (nodes[i].timestamp < nodes[i - 1].timestamp) {
+            debugLogger.warn(`[InvariantCheck][${context}] Non-linear timestamps detected at index ${i}.`);
+            break;
+        }
+    }
+}
+//# sourceMappingURL=invariantChecker.js.map

package/dist/src/context/utils/invariantChecker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariantChecker.js","sourceRoot":"","sources":["../../../../src/context/utils/invariantChecker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAA8B,EAC9B,OAAe;IAEf,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IAED,IAAI,UAAU,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACxB,WAAW,CAAC,IAAI,CACd,oBAAoB,OAAO,cAAc,UAAU,CAAC,IAAI,2BAA2B,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvH,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,WAAW,CAAC,IAAI,CACd,oBAAoB,OAAO,cAAc,OAAO,CAAC,MAAM,wBAAwB,CAChF,CAAC;IACJ,CAAC;IAED,gCAAgC;IAChC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;YAChD,WAAW,CAAC,IAAI,CACd,oBAAoB,OAAO,6CAA6C,CAAC,GAAG,CAC7E,CAAC;YACF,MAAM;QACR,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/src/context/utils/snapshotGenerator.d.ts

@@ -5,8 +5,50 @@
  */
 import type { ConcreteNode } from '../graph/types.js';
 import type { ContextEnvironment } from '../pipeline/environment.js';
+export interface SnapshotState {
+    active_tasks: Array<{
+        id: string;
+        description: string;
+    }>;
+    discovered_facts: string[];
+    constraints_and_preferences: string[];
+    recent_arc: string[];
+}
+export declare function isSnapshotState(text: string): boolean;
+export interface BaselineSnapshotInfo {
+    text: string;
+    abstractsIds: string[];
+    id: string;
+    timestamp: number;
+}
+/**
+ * Global Lookback: Scans the target nodes in reverse to find the absolute
+ * most recent valid Snapshot node to use as a Delta baseline.
+ */
+export declare function findLatestSnapshotBaseline(targets: readonly ConcreteNode[]): BaselineSnapshotInfo | undefined;
 export declare class SnapshotGenerator {
     private readonly env;
     constructor(env: ContextEnvironment);
-    synthesizeSnapshot(nodes: readonly ConcreteNode[], systemInstruction?: string): Promise<string>;
+    synthesizeSnapshot(nodes: readonly ConcreteNode[], previousStateJson?: string, options?: {
+        maxSummaryTurns?: number;
+        maxStateTokens?: number;
+    }): Promise<string>;
+}
+/**
+ * Shared logic for working with Snapshot node state.
+ */
+export declare class SnapshotStateHelper {
+    /**
+     * Flatten nested abstract IDs to only the "pristine" (non-snapshot) IDs.
+     */
+    static flattenAbstracts(nodes: ConcreteNode[], abstractsIds: readonly string[]): string[];
+    /**
+     * Helper to extract state from the most recent snapshot in a list of nodes.
+     */
+    static exportState(nodes: ConcreteNode[]): {
+        snapshot?: {
+            text: string;
+            consumedIds: string[];
+        };
+    };
 }