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

package/dist/src/context/config/registry.js

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Registry for validating declarative sidecar configuration schemas.
+ * (Dynamic instantiation has been replaced by static ContextProfiles)
+ */
+export class ContextProcessorRegistry {
+    processors = new Map();
+    registerProcessor(def) {
+        // Erasing the type.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        this.processors.set(def.id, def);
+    }
+    getSchema(id) {
+        return this.processors.get(id)?.schema;
+    }
+    getSchemaDefs() {
+        const defs = [];
+        for (const def of this.processors.values()) {
+            if (def.schema)
+                defs.push({ id: def.id, schema: def.schema });
+        }
+        return defs;
+    }
+    clear() {
+        this.processors.clear();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/context/config/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/context/config/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH;;;GAGG;AACH,MAAM,OAAO,wBAAwB;IAClB,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAC;IAErE,iBAAiB,CAAI,GAA2B;QAC9C,oBAAoB;QACpB,uEAAuE;QACvE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAA8C,CAAC,CAAC;IAC9E,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACzC,CAAC;IAED,aAAa;QACX,MAAM,IAAI,GAAG,EAAE,CAAC;QAChB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,GAAG,CAAC,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/src/context/config/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProcessorRegistry } from './registry.js';
+export declare function getContextManagementConfigSchema(registry: ContextProcessorRegistry): {
+    $schema: string;
+    title: string;
+    description: string;
+    type: string;
+    properties: {
+        budget: {
+            type: string;
+            description: string;
+            required: string[];
+            properties: {
+                retainedTokens: {
+                    type: string;
+                    description: string;
+                };
+                maxTokens: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+        processorOptions: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                oneOf: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        options: import("ajv").JSONSchemaType<unknown>;
+                    };
+                }[];
+            };
+        };
+    };
+};

package/dist/src/context/config/schema.js

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function getContextManagementConfigSchema(registry) {
+    // We use a registry to deeply validate processor overrides.
+    // We do this by generating a `oneOf` list that matches the `type` discriminator
+    // to the specific processor `options` schema.
+    const processorOptionSchemas = registry.getSchemaDefs().map((def) => ({
+        type: 'object',
+        required: ['type', 'options'],
+        properties: {
+            type: { const: def.id },
+            options: def.schema,
+        },
+    }));
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'ContextManagementConfig',
+        description: 'The Hyperparameter schema for a Context Profile.',
+        type: 'object',
+        properties: {
+            budget: {
+                type: 'object',
+                description: 'Defines the token ceilings and limits for the pipeline.',
+                required: ['retainedTokens', 'maxTokens'],
+                properties: {
+                    retainedTokens: {
+                        type: 'number',
+                        description: 'The ideal token count the pipeline tries to shrink down to.',
+                    },
+                    maxTokens: {
+                        type: 'number',
+                        description: 'The absolute maximum token count allowed before synchronous truncation kicks in.',
+                    },
+                },
+            },
+            processorOptions: {
+                type: 'object',
+                description: 'Named hyperparameter configurations for ContextProcessors and AsyncProcessors.',
+                additionalProperties: { oneOf: processorOptionSchemas },
+            },
+        },
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/context/config/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../../src/context/config/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,UAAU,gCAAgC,CAC9C,QAAkC;IAElC,4DAA4D;IAC5D,gFAAgF;IAChF,8CAA8C;IAC9C,MAAM,sBAAsB,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpE,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;QAC7B,UAAU,EAAE;YACV,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE;YACvB,OAAO,EAAE,GAAG,CAAC,MAAM;SACpB;KACF,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,OAAO,EAAE,yCAAyC;QAClD,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,kDAAkD;QAC/D,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,yDAAyD;gBACtE,QAAQ,EAAE,CAAC,gBAAgB,EAAE,WAAW,CAAC;gBACzC,UAAU,EAAE;oBACV,cAAc,EAAE;wBACd,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,6DAA6D;qBAChE;oBACD,SAAS,EAAE;wBACT,IAAI,EAAE,QAAQ;wBACd,WAAW,EACT,kFAAkF;qBACrF;iBACF;aACF;YACD,gBAAgB,EAAE;gBAChB,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,gFAAgF;gBAClF,oBAAoB,EAAE,EAAE,KAAK,EAAE,sBAAsB,EAAE;aACxD;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/src/context/config/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProcessor, AsyncContextProcessor } from '../pipeline.js';
+export type PipelineTrigger = 'new_message' | 'retained_exceeded' | 'gc_backstop' | 'nodes_added' | 'nodes_aged_out' | {
+    type: 'timer';
+    intervalMs: number;
+};
+export interface PipelineDef {
+    name: string;
+    triggers: PipelineTrigger[];
+    processors: ContextProcessor[];
+}
+export interface AsyncPipelineDef {
+    name: string;
+    triggers: PipelineTrigger[];
+    processors: AsyncContextProcessor[];
+}
+export interface ContextBudget {
+    retainedTokens: number;
+    maxTokens: number;
+}
+/**
+ * The Data-Driven Schema for the Context Manager.
+ */
+export interface ContextManagementConfig {
+    /** Defines the token ceilings and limits for the pipeline. */
+    budget: ContextBudget;
+    /**
+     * Dynamic hyperparameter overrides for individual ContextProcessors and AsyncProcessors.
+     * Keys are named identifiers (e.g. "gentleTruncation").
+     */
+    processorOptions?: Record<string, {
+        type: string;
+        options: unknown;
+    }>;
+}

package/dist/src/context/config/types.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/context/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/context/config/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/src/context/contextManager.barrier.test.d.ts

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

package/dist/src/context/contextManager.barrier.test.js

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { testTruncateProfile } from './testing/testProfile.js';
+import { createSyntheticHistory, createMockContextConfig, setupContextComponentTest, } from './testing/contextTestUtils.js';
+describe('ContextManager Sync Pressure Barrier Tests', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('should instantly truncate history when maxTokens is exceeded using truncate strategy', async () => {
+        // 1. Setup
+        const config = createMockContextConfig();
+        const { chatHistory, contextManager } = setupContextComponentTest(config, testTruncateProfile);
+        // 2. Add System Prompt (Episode 0 - Protected)
+        chatHistory.set([
+            { role: 'user', parts: [{ text: 'System prompt' }] },
+            { role: 'model', parts: [{ text: 'Understood.' }] },
+        ]);
+        // 3. Add massive history that blows past the 150k maxTokens limit
+        // 20 turns * 10,000 tokens/turn = ~200,000 tokens
+        const massiveHistory = createSyntheticHistory(20, 35000);
+        chatHistory.set([...chatHistory.get(), ...massiveHistory]);
+        // 4. Add the Latest Turn (Protected)
+        chatHistory.set([
+            ...chatHistory.get(),
+            { role: 'user', parts: [{ text: 'Final question.' }] },
+            { role: 'model', parts: [{ text: 'Final answer.' }] },
+        ]);
+        const rawHistoryLength = chatHistory.get().length;
+        // 5. Project History (Triggers Sync Barrier)
+        const projection = await contextManager.renderHistory();
+        // 6. Assertions
+        // The barrier should have dropped several older episodes to get under 150k.
+        expect(projection.length).toBeLessThan(rawHistoryLength);
+        // Verify Episode 0 (System) is perfectly preserved at the front
+        expect(projection[0].role).toBe('user');
+        expect(projection[0].parts[0].text).toBe('System prompt');
+        // Filter out synthetic Yield nodes (they are model responses without actual tool/text bodies)
+        const contentNodes = projection.filter((p) => p.parts && p.parts.some((part) => part.text && part.text !== 'Yield'));
+        // Verify the latest turn is perfectly preserved at the back
+        const lastUser = contentNodes[contentNodes.length - 2];
+        const lastModel = contentNodes[contentNodes.length - 1];
+        expect(lastUser.role).toBe('user');
+        expect(lastUser.parts[0].text).toBe('Final question.');
+        expect(lastModel.role).toBe('model');
+        expect(lastModel.parts[0].text).toBe('Final answer.');
+    });
+});
+//# sourceMappingURL=contextManager.barrier.test.js.map

package/dist/src/context/contextManager.barrier.test.js.map

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

package/dist/src/context/contextManager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content } from '@google/genai';
+import type { AgentChatHistory } from '../core/agentChatHistory.js';
+import type { ConcreteNode } from './graph/types.js';
+import type { ContextTracer } from './tracer.js';
+import type { ContextEnvironment } from './pipeline/environment.js';
+import type { ContextProfile } from './config/profiles.js';
+import type { PipelineOrchestrator } from './pipeline/orchestrator.js';
+export declare class ContextManager {
+    private readonly sidecar;
+    private readonly env;
+    private readonly tracer;
+    private buffer;
+    private readonly eventBus;
+    private readonly orchestrator;
+    private readonly historyObserver;
+    constructor(sidecar: ContextProfile, env: ContextEnvironment, tracer: ContextTracer, orchestrator: PipelineOrchestrator, chatHistory: AgentChatHistory);
+    /**
+     * Safely stops background async pipelines and clears event listeners.
+     */
+    shutdown(): void;
+    /**
+     * Evaluates if the current working buffer exceeds configured budget thresholds,
+     * firing consolidation events if necessary.
+     */
+    private evaluateTriggers;
+    /**
+     * Retrieves the raw, uncompressed Episodic Context Graph graph.
+     * Useful for internal tool rendering (like the trace viewer).
+     * Note: This is an expensive, deep clone operation.
+     */
+    getPristineGraph(): readonly ConcreteNode[];
+    /**
+     * Generates a virtual view of the pristine graph, substituting in variants
+     * up to the configured token budget.
+     * This is the view that will eventually be projected back to the LLM.
+     */
+    getNodes(): readonly ConcreteNode[];
+    /**
+     * Executes the final 'gc_backstop' pipeline if necessary, enforcing the token budget,
+     * and maps the Episodic Context Graph back into a raw Gemini Content[] array for transmission.
+     * This is the primary method called by the agent framework before sending a request.
+     */
+    renderHistory(activeTaskIds?: Set<string>): Promise<Content[]>;
+}

package/dist/src/context/contextManager.js

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { HistoryObserver } from './historyObserver.js';
+import { render } from './graph/render.js';
+import { ContextWorkingBufferImpl } from './pipeline/contextWorkingBuffer.js';
+export class ContextManager {
+    sidecar;
+    env;
+    tracer;
+    // The master state containing the pristine graph and current active graph.
+    buffer = ContextWorkingBufferImpl.initialize([]);
+    eventBus;
+    // Internal sub-components
+    orchestrator;
+    historyObserver;
+    constructor(sidecar, env, tracer, orchestrator, chatHistory) {
+        this.sidecar = sidecar;
+        this.env = env;
+        this.tracer = tracer;
+        this.eventBus = env.eventBus;
+        this.orchestrator = orchestrator;
+        this.historyObserver = new HistoryObserver(chatHistory, this.env.eventBus, this.tracer, this.env.tokenCalculator, this.env.graphMapper);
+        this.historyObserver.start();
+        this.eventBus.onPristineHistoryUpdated((event) => {
+            const existingIds = new Set(this.buffer.nodes.map((n) => n.id));
+            const newIds = new Set(event.nodes.map((n) => n.id));
+            const addedNodes = event.nodes.filter((n) => !existingIds.has(n.id));
+            // Prune any pristine nodes that were dropped from the upstream history
+            this.buffer = this.buffer.prunePristineNodes(newIds);
+            if (addedNodes.length > 0) {
+                this.buffer = this.buffer.appendPristineNodes(addedNodes);
+            }
+            this.evaluateTriggers(event.newNodes);
+        });
+    }
+    /**
+     * Safely stops background async pipelines and clears event listeners.
+     */
+    shutdown() {
+        this.orchestrator.shutdown();
+        this.historyObserver.stop();
+    }
+    /**
+     * Evaluates if the current working buffer exceeds configured budget thresholds,
+     * firing consolidation events if necessary.
+     */
+    evaluateTriggers(newNodes) {
+        if (!this.sidecar.config.budget)
+            return;
+        if (newNodes.size > 0) {
+            this.eventBus.emitChunkReceived({
+                nodes: this.buffer.nodes,
+                targetNodeIds: newNodes,
+            });
+        }
+        const currentTokens = this.env.tokenCalculator.calculateConcreteListTokens(this.buffer.nodes);
+        if (currentTokens > this.sidecar.config.budget.retainedTokens) {
+            const agedOutNodes = new Set();
+            let rollingTokens = 0;
+            // Walk backwards finding nodes that fall out of the retained budget
+            for (let i = this.buffer.nodes.length - 1; i >= 0; i--) {
+                const node = this.buffer.nodes[i];
+                rollingTokens += this.env.tokenCalculator.calculateConcreteListTokens([
+                    node,
+                ]);
+                if (rollingTokens > this.sidecar.config.budget.retainedTokens) {
+                    agedOutNodes.add(node.id);
+                }
+            }
+            if (agedOutNodes.size > 0) {
+                this.env.tokenCalculator.garbageCollectCache(new Set(this.buffer.nodes.map((n) => n.id)));
+                this.eventBus.emitConsolidationNeeded({
+                    nodes: this.buffer.nodes,
+                    targetDeficit: currentTokens - this.sidecar.config.budget.retainedTokens,
+                    targetNodeIds: agedOutNodes,
+                });
+            }
+        }
+    }
+    /**
+     * Retrieves the raw, uncompressed Episodic Context Graph graph.
+     * Useful for internal tool rendering (like the trace viewer).
+     * Note: This is an expensive, deep clone operation.
+     */
+    getPristineGraph() {
+        const pristineSet = new Map();
+        for (const node of this.buffer.nodes) {
+            const roots = this.buffer.getPristineNodes(node.id);
+            for (const root of roots) {
+                pristineSet.set(root.id, root);
+            }
+        }
+        // We sort them by timestamp to ensure they are returned in chronological order
+        return Array.from(pristineSet.values()).sort((a, b) => a.timestamp - b.timestamp);
+    }
+    /**
+     * Generates a virtual view of the pristine graph, substituting in variants
+     * up to the configured token budget.
+     * This is the view that will eventually be projected back to the LLM.
+     */
+    getNodes() {
+        return [...this.buffer.nodes];
+    }
+    /**
+     * Executes the final 'gc_backstop' pipeline if necessary, enforcing the token budget,
+     * and maps the Episodic Context Graph back into a raw Gemini Content[] array for transmission.
+     * This is the primary method called by the agent framework before sending a request.
+     */
+    async renderHistory(activeTaskIds = new Set()) {
+        this.tracer.logEvent('ContextManager', 'Starting rendering of LLM context');
+        // Apply final GC Backstop pressure barrier synchronously before mapping
+        const finalHistory = await render(this.buffer.nodes, this.orchestrator, this.sidecar, this.tracer, this.env, activeTaskIds);
+        this.tracer.logEvent('ContextManager', 'Finished rendering');
+        return finalHistory;
+    }
+}
+//# sourceMappingURL=contextManager.js.map

package/dist/src/context/contextManager.js.map

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

package/dist/src/context/eventBus.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { EventEmitter } from 'node:events';
+import type { ConcreteNode } from './graph/types.js';
+export interface PristineHistoryUpdatedEvent {
+    nodes: readonly ConcreteNode[];
+    newNodes: Set<string>;
+}
+export interface ContextConsolidationEvent {
+    nodes: readonly ConcreteNode[];
+    targetDeficit: number;
+    targetNodeIds: Set<string>;
+}
+export interface ChunkReceivedEvent {
+    nodes: readonly ConcreteNode[];
+    targetNodeIds: Set<string>;
+}
+export declare class ContextEventBus extends EventEmitter {
+    emitPristineHistoryUpdated(event: PristineHistoryUpdatedEvent): void;
+    onPristineHistoryUpdated(listener: (event: PristineHistoryUpdatedEvent) => void): void;
+    emitChunkReceived(event: ChunkReceivedEvent): void;
+    onChunkReceived(listener: (event: ChunkReceivedEvent) => void): void;
+    emitConsolidationNeeded(event: ContextConsolidationEvent): void;
+    onConsolidationNeeded(listener: (event: ContextConsolidationEvent) => void): void;
+}

package/dist/src/context/eventBus.js

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { EventEmitter } from 'node:events';
+export class ContextEventBus extends EventEmitter {
+    emitPristineHistoryUpdated(event) {
+        this.emit('PRISTINE_HISTORY_UPDATED', event);
+    }
+    onPristineHistoryUpdated(listener) {
+        this.on('PRISTINE_HISTORY_UPDATED', listener);
+    }
+    emitChunkReceived(event) {
+        this.emit('IR_CHUNK_RECEIVED', event);
+    }
+    onChunkReceived(listener) {
+        this.on('IR_CHUNK_RECEIVED', listener);
+    }
+    emitConsolidationNeeded(event) {
+        this.emit('BUDGET_RETAINED_CROSSED', event);
+    }
+    onConsolidationNeeded(listener) {
+        this.on('BUDGET_RETAINED_CROSSED', listener);
+    }
+}
+//# sourceMappingURL=eventBus.js.map

package/dist/src/context/eventBus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.js","sourceRoot":"","sources":["../../../src/context/eventBus.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAmB3C,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/C,0BAA0B,CAAC,KAAkC;QAC3D,IAAI,CAAC,IAAI,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,wBAAwB,CACtB,QAAsD;QAEtD,IAAI,CAAC,EAAE,CAAC,0BAA0B,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED,iBAAiB,CAAC,KAAyB;QACzC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,eAAe,CAAC,QAA6C;QAC3D,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,uBAAuB,CAAC,KAAgC;QACtD,IAAI,CAAC,IAAI,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,qBAAqB,CAAC,QAAoD;QACxE,IAAI,CAAC,EAAE,CAAC,yBAAyB,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/dist/src/context/graph/behaviorRegistry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content, Part } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+export interface NodeSerializationWriter {
+    appendContent(content: Content): void;
+    appendModelPart(part: Part): void;
+    appendUserPart(part: Part): void;
+    flushModelParts(): void;
+}
+export interface NodeBehavior<T extends ConcreteNode = ConcreteNode> {
+    readonly type: T['type'];
+    /** Serializes the node into the Gemini Content structure. */
+    serialize(node: T, writer: NodeSerializationWriter): void;
+    /**
+     * Generates a structural representation of the node for the purpose
+     * of estimating its token cost.
+     */
+    getEstimatableParts(node: T): Part[];
+}
+export declare class NodeBehaviorRegistry {
+    private readonly behaviors;
+    register<T extends ConcreteNode>(behavior: NodeBehavior<T>): void;
+    get(type: string): NodeBehavior<ConcreteNode>;
+}

package/dist/src/context/graph/behaviorRegistry.js

@@ -0,0 +1,14 @@
+export class NodeBehaviorRegistry {
+    behaviors = new Map();
+    register(behavior) {
+        this.behaviors.set(behavior.type, behavior);
+    }
+    get(type) {
+        const behavior = this.behaviors.get(type);
+        if (!behavior) {
+            throw new Error(`Unregistered Node type: ${type}`);
+        }
+        return behavior;
+    }
+}
+//# sourceMappingURL=behaviorRegistry.js.map

package/dist/src/context/graph/behaviorRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviorRegistry.js","sourceRoot":"","sources":["../../../../src/context/graph/behaviorRegistry.ts"],"names":[],"mappings":"AA4BA,MAAM,OAAO,oBAAoB;IACd,SAAS,GAAG,IAAI,GAAG,EAAsC,CAAC;IAE3E,QAAQ,CAAyB,QAAyB;QACxD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,GAAG,CAAC,IAAY;QACd,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/src/context/graph/builtinBehaviors.d.ts

@@ -0,0 +1,11 @@
+import type { NodeBehavior, NodeBehaviorRegistry } from './behaviorRegistry.js';
+import type { UserPrompt, AgentThought, ToolExecution, MaskedTool, AgentYield, Snapshot, RollingSummary, SystemEvent } from './types.js';
+export declare const UserPromptBehavior: NodeBehavior<UserPrompt>;
+export declare const AgentThoughtBehavior: NodeBehavior<AgentThought>;
+export declare const ToolExecutionBehavior: NodeBehavior<ToolExecution>;
+export declare const MaskedToolBehavior: NodeBehavior<MaskedTool>;
+export declare const AgentYieldBehavior: NodeBehavior<AgentYield>;
+export declare const SystemEventBehavior: NodeBehavior<SystemEvent>;
+export declare const SnapshotBehavior: NodeBehavior<Snapshot>;
+export declare const RollingSummaryBehavior: NodeBehavior<RollingSummary>;
+export declare function registerBuiltInBehaviors(registry: NodeBehaviorRegistry): void;