@noetic-tools/core 0.0.1

package/dist/memory/layer-usage.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '../types/common';
+import type { Context, LastLayerUsage } from '../types/context';
+import type { RecallLayerOutput } from '../types/runtime';
+interface ComputeLayerUsageParams {
+    ctx: Context;
+    modelId: string;
+    instructions?: string;
+    tools?: ReadonlyArray<Tool>;
+    /** Per-layer recall output assembled into the context view for this LLM call. */
+    recallResults: ReadonlyArray<RecallLayerOutput>;
+}
+export declare function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, }: ComputeLayerUsageParams): LastLayerUsage;
+/** Commit computed usage to the Context, replacing any prior snapshot. */
+export declare function commitLayerUsage(ctx: Context, usage: LastLayerUsage): void;
+export {};

package/dist/memory/layer-usage.js

@@ -0,0 +1,48 @@
+import { estimateTokens } from '../interpreter/message-helpers';
+import { isContextImpl } from '../interpreter/typeguards';
+//#endregion
+//#region Helpers
+function estimateJsonTokens(value) {
+    try {
+        return estimateTokens(JSON.stringify(value));
+    }
+    catch {
+        return 0;
+    }
+}
+//#endregion
+//#region Public API
+export function computeLayerUsage({ ctx, modelId, instructions, tools, recallResults, }) {
+    const layers = recallResults
+        .map((r) => ({
+        layerId: r.layerId,
+        tokenCount: r.tokenCount,
+        items: r.items,
+    }))
+        .sort((a, b) => a.layerId.localeCompare(b.layerId));
+    let historyTokens = 0;
+    for (const item of ctx.itemLog.items) {
+        historyTokens += estimateJsonTokens(item);
+    }
+    const systemPromptTokens = instructions ? estimateTokens(instructions) : 0;
+    const toolsTokens = tools && tools.length > 0 ? estimateJsonTokens(tools) : 0;
+    const layerTotal = layers.reduce((sum, l) => sum + l.tokenCount, 0);
+    const totalUsedTokens = systemPromptTokens + toolsTokens + historyTokens + layerTotal;
+    return {
+        executionId: ctx.id,
+        modelId,
+        layers,
+        systemPromptTokens,
+        toolsTokens,
+        historyTokens,
+        totalUsedTokens,
+    };
+}
+/** Commit computed usage to the Context, replacing any prior snapshot. */
+export function commitLayerUsage(ctx, usage) {
+    if (!isContextImpl(ctx)) {
+        return;
+    }
+    ctx.lastLayerUsage = usage;
+}
+//#endregion

package/dist/memory/layers/durable-task-state.d.ts

@@ -0,0 +1,79 @@
+import type { ZodType } from 'zod';
+export interface DurableTaskState {
+    checkpoints: Array<{
+        timestamp: number;
+        depth: number;
+    }>;
+    files: string[];
+    data: Record<string, unknown>;
+}
+export interface DurableTaskStateSerializer {
+    serialize(state: DurableTaskState): string;
+    deserialize(data: string): DurableTaskState;
+}
+export interface DurableTaskStateConfig {
+    baseDir?: string;
+    gitCommit?: boolean;
+    schema?: ZodType;
+    serializer?: DurableTaskStateSerializer;
+}
+/**
+ * Creates a memory layer that persists task checkpoints, files, and arbitrary data across iterations.
+ *
+ * @public
+ * @param _config - Optional configuration for base directory, git commit behavior, schema, and serializer.
+ * @returns A `MemoryLayer` scoped to the execution with durable task state.
+ */
+export declare function durableTaskState(_config?: DurableTaskStateConfig): {
+    id: "durable-task-state";
+    name: string;
+    slot: number;
+    scope: "execution";
+    budget: {
+        min: number;
+        max: number;
+    };
+    timeouts: {
+        store: number;
+    };
+    hooks: {
+        init({ storage }: import("../..").InitParams): Promise<{
+            state: DurableTaskState;
+        }>;
+        recall({ state }: import("../..").RecallParams<DurableTaskState>): Promise<{
+            items: import("../..").InputMessageItem[];
+            tokenCount: number;
+        } | null>;
+        store({ state, ctx }: import("../..").StoreParams<DurableTaskState>): Promise<{
+            state: DurableTaskState;
+        }>;
+        onSpawn({ parentState }: import("../..").SpawnParams<DurableTaskState>): Promise<{
+            childState: DurableTaskState;
+            items: never[];
+        }>;
+        onReturn({ childState, parentState }: import("../..").ReturnParams<DurableTaskState>): Promise<{
+            parentState: {
+                checkpoints: {
+                    timestamp: number;
+                    depth: number;
+                }[];
+                files: string[];
+                data: {
+                    [x: string]: unknown;
+                };
+            };
+        }>;
+        onComplete({ state, outcome }: import("../..").CompleteParams<DurableTaskState>): Promise<{
+            state: {
+                data: {
+                    __outcome: import("../..").ExecutionOutcome;
+                };
+                checkpoints: {
+                    timestamp: number;
+                    depth: number;
+                }[];
+                files: string[];
+            };
+        } | undefined>;
+    };
+};

package/dist/memory/layers/durable-task-state.js

@@ -0,0 +1,118 @@
+import { createMessage, estimateTokens } from '../../interpreter/message-helpers';
+import { Slot } from '../../types/memory';
+/**
+ * Creates a memory layer that persists task checkpoints, files, and arbitrary data across iterations.
+ *
+ * @public
+ * @param _config - Optional configuration for base directory, git commit behavior, schema, and serializer.
+ * @returns A `MemoryLayer` scoped to the execution with durable task state.
+ */
+export function durableTaskState(_config) {
+    return {
+        id: 'durable-task-state',
+        name: 'Durable Task State',
+        slot: Slot.WORKING_MEMORY + 10, // 110
+        scope: 'execution',
+        budget: {
+            min: 100,
+            max: 800,
+        },
+        timeouts: {
+            store: 30_000,
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                return {
+                    state: saved ?? {
+                        checkpoints: [],
+                        files: [],
+                        data: {},
+                    },
+                };
+            },
+            async recall({ state }) {
+                if (!state) {
+                    return null;
+                }
+                const text = `<task_state>\n${JSON.stringify(state, null, 2)}\n</task_state>`;
+                return {
+                    items: [
+                        createMessage(text, 'developer'),
+                    ],
+                    tokenCount: estimateTokens(text),
+                };
+            },
+            async store({ state, ctx }) {
+                const currentState = state ?? {
+                    checkpoints: [],
+                    files: [],
+                    data: {},
+                };
+                // Add a checkpoint for each store call
+                const newState = {
+                    ...currentState,
+                    checkpoints: [
+                        ...currentState.checkpoints,
+                        {
+                            timestamp: Date.now(),
+                            depth: ctx.depth,
+                        },
+                    ],
+                };
+                return {
+                    state: newState,
+                };
+            },
+            async onSpawn({ parentState }) {
+                // ALWAYS provides child state (unlike other layers)
+                return {
+                    childState: structuredClone(parentState),
+                    items: [],
+                };
+            },
+            async onReturn({ childState, parentState }) {
+                // Merge child artifacts back to parent
+                return {
+                    parentState: {
+                        checkpoints: [
+                            ...parentState.checkpoints,
+                            ...childState.checkpoints,
+                        ],
+                        files: [
+                            ...new Set([
+                                ...parentState.files,
+                                ...childState.files,
+                            ]),
+                        ],
+                        data: {
+                            ...parentState.data,
+                            ...childState.data,
+                        },
+                    },
+                };
+            },
+            async onComplete({ state, outcome }) {
+                if (!state) {
+                    return;
+                }
+                return {
+                    state: {
+                        ...state,
+                        data: {
+                            ...state.data,
+                            __outcome: outcome,
+                        },
+                        checkpoints: [
+                            ...state.checkpoints,
+                            {
+                                timestamp: Date.now(),
+                                depth: 0,
+                            },
+                        ],
+                    },
+                };
+            },
+        },
+    };
+}

package/dist/memory/layers/file-reference.d.ts

@@ -0,0 +1,55 @@
+import type { MemoryLayer } from '../../types/memory';
+interface TrackedFile {
+    /** Absolute path to the file */
+    absolutePath: string;
+    /** Original reference path (as written by user) */
+    referencePath: string;
+    /** File content (null if deleted or error) */
+    content: string | null;
+    /** LLM-assigned priority score (0-100, higher = more relevant) */
+    priority: number;
+    /** Content hash for change detection */
+    contentHash: string;
+    /** Whether the file has been deleted */
+    deleted: boolean;
+    /** Estimated token count */
+    tokenCount: number;
+    /** Error message if file couldn't be read (security, size, permission) */
+    error?: string;
+}
+interface FileReferenceState {
+    /** Map of reference path to tracked file info */
+    files: Map<string, TrackedFile>;
+    /** Base directory for resolving relative paths */
+    baseDir: string;
+}
+interface FileReferenceOptions {
+    /** Base directory for resolving relative paths (defaults to cwd) */
+    baseDir?: string;
+    /** Slot position (defaults to Slot.RAG) */
+    slot?: number;
+    /** Model to use for priority scoring */
+    scoringModel?: string;
+    /** Maximum file size in bytes (defaults to 1MB) */
+    maxFileSize?: number;
+    /** Whether to follow symlinks (defaults to false for security) */
+    followSymlinks?: boolean;
+    /** Allowed file extensions (defaults to common code/text extensions) */
+    allowedExtensions?: string[];
+}
+/**
+ * Creates a memory layer that tracks file references in user messages.
+ *
+ * Syntax: `#path/to/file` in user messages
+ *
+ * Behavior:
+ * - Transforms references to markdown anchor links `[#path/to/file](#path-to-file)`
+ * - Scores file relevance using LLM when first referenced
+ * - Injects file contents into context via recall(), ordered by priority
+ * - Detects file changes on each new message, triggers immediate re-render
+ * - Shows warning for deleted files
+ *
+ * @public
+ */
+export declare function fileReference(opts?: FileReferenceOptions): MemoryLayer<FileReferenceState>;
+export {};