@noetic-tools/context 1.0.0

package/dist/context/layer-provides.d.ts

@@ -0,0 +1,32 @@
+import type { ExecutionContext, LayerDataDecl, LayerFunctionDecl } from '@noetic-tools/types';
+import type { ZodType } from 'zod';
+/**
+ * Creates a read-only data declaration for a context layer's `provides` map.
+ *
+ * @public
+ * @param opts.read - Function that projects a value from the layer's current state.
+ * @returns A `LayerDataDecl` to include in a layer's `provides`.
+ */
+export declare function layerData<T, TState>(opts: {
+    read: (state: TState) => T;
+}): LayerDataDecl<T, TState>;
+/**
+ * Creates a callable function declaration for a context layer's `provides` map.
+ * Functions are accessible via `ctx.context['layerId'].fn()` and automatically exposed as LLM tools.
+ *
+ * @public
+ * @param opts.description - Human-readable description used as tool description for LLM.
+ * @param opts.input - Zod schema validating input arguments.
+ * @param opts.output - Zod schema validating the return value.
+ * @param opts.execute - Async function receiving args, current state, and execution context.
+ * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
+ */
+export declare function layerFn<TInput, TOutput, TState>(opts: {
+    description: string;
+    input: ZodType<TInput>;
+    output: ZodType<TOutput>;
+    execute: (args: TInput, state: TState, ctx: ExecutionContext) => Promise<{
+        result: TOutput;
+        state?: TState;
+    }>;
+}): LayerFunctionDecl<TInput, TOutput, TState>;

package/dist/context/layer-provides.js

@@ -0,0 +1,33 @@
+/**
+ * Creates a read-only data declaration for a context layer's `provides` map.
+ *
+ * @public
+ * @param opts.read - Function that projects a value from the layer's current state.
+ * @returns A `LayerDataDecl` to include in a layer's `provides`.
+ */
+export function layerData(opts) {
+    return {
+        kind: 'data',
+        read: opts.read,
+    };
+}
+/**
+ * Creates a callable function declaration for a context layer's `provides` map.
+ * Functions are accessible via `ctx.context['layerId'].fn()` and automatically exposed as LLM tools.
+ *
+ * @public
+ * @param opts.description - Human-readable description used as tool description for LLM.
+ * @param opts.input - Zod schema validating input arguments.
+ * @param opts.output - Zod schema validating the return value.
+ * @param opts.execute - Async function receiving args, current state, and execution context.
+ * @returns A `LayerFunctionDecl` to include in a layer's `provides`.
+ */
+export function layerFn(opts) {
+    return {
+        kind: 'function',
+        description: opts.description,
+        input: opts.input,
+        output: opts.output,
+        execute: opts.execute,
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { Context, LastLayerUsage, RecallLayerOutput, Tool } from '@noetic-tools/types';
+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/context/layer-usage.js

@@ -0,0 +1,54 @@
+import { estimateTokens } from '@noetic-tools/types';
+function canWriteLayerUsage(ctx) {
+    const desc = Object.getOwnPropertyDescriptor(ctx, 'lastLayerUsage');
+    if (desc === undefined) {
+        return false;
+    }
+    return desc.writable !== false;
+}
+//#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 (!canWriteLayerUsage(ctx)) {
+        return;
+    }
+    ctx.lastLayerUsage = usage;
+}
+//#endregion

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

@@ -0,0 +1,107 @@
+export interface DurableTaskState {
+    checkpoints: Array<{
+        timestamp: number;
+        depth: number;
+    }>;
+    files: string[];
+    data: Record<string, unknown>;
+}
+/**
+ * How a child's `data` map is merged into the parent's at a spawn/fork return.
+ *
+ * - `'shallow'` — `{ ...parent, ...child }`. Concurrent children that write the
+ *   same key clobber each other (last to return wins). Fine for a single child.
+ * - `'namespace'` — the child's map is stored whole under its execution id
+ *   (`parent.data[childExecutionId] = childData`), so N fan-out workers each
+ *   keep their own result. Keys the child inherited from the parent unchanged
+ *   are not re-written at the top level.
+ *
+ * @public
+ */
+export type DurableTaskDataMerge = 'shallow' | 'namespace';
+/** @public Options for {@link durableTaskState}. */
+export interface DurableTaskStateOptions {
+    /**
+     * Merge strategy for `data` at a child boundary. Defaults to `'shallow'`.
+     * Use `'namespace'` for coordinator/worker fan-out, where several children
+     * return concurrently into one parent.
+     */
+    mergeData?: DurableTaskDataMerge;
+}
+/**
+ * Creates a context layer that persists task checkpoints, files, and arbitrary data across iterations.
+ *
+ * State is rehydrated from `ScopedStorage` on init and persisted via the
+ * runtime's durable write-through; `store` appends capped checkpoints
+ * (newest 50 kept) and `recall` trims its render to the allocated budget.
+ *
+ * The layer is writable from the model: `provides` exposes
+ * `durable-task-state/recordArtifact` (append a produced/modified file path)
+ * and `durable-task-state/setTaskData` (record a structured result under a
+ * key). Both survive the spawn boundary — a worker's artifacts merge back into
+ * its coordinator via `onReturn`.
+ *
+ * @public
+ * @param opts - Layer options; `mergeData` selects the `data` merge strategy at a child boundary.
+ * @returns A `ContextLayer` scoped to the thread with durable task state.
+ */
+export declare function durableTaskState(opts?: DurableTaskStateOptions): {
+    id: 'durable-task-state';
+    name: string;
+    slot: number;
+    scope: "thread";
+    budget: {
+        min: number;
+        max: number;
+    };
+    timeouts: {
+        store: number;
+    };
+    provides: {
+        recordArtifact: import("@noetic-tools/types").LayerFunctionDecl<{
+            path: string;
+        }, string, DurableTaskState>;
+        setTaskData: import("@noetic-tools/types").LayerFunctionDecl<{
+            key: string;
+            value: unknown;
+        }, string, DurableTaskState>;
+    };
+    hooks: {
+        init({ storage }: import("@noetic-tools/types").InitParams): Promise<{
+            state: DurableTaskState;
+        }>;
+        recall({ state, budget }: import("@noetic-tools/types").RecallParams<DurableTaskState>): Promise<{
+            items: import("@noetic-tools/types").InputMessageItem[];
+            tokenCount: number;
+        } | null>;
+        store({ state, ctx }: import("@noetic-tools/types").StoreParams<DurableTaskState>): Promise<{
+            state: DurableTaskState;
+        }>;
+        onSpawn({ parentState }: import("@noetic-tools/types").SpawnParams<DurableTaskState>): Promise<{
+            childState: DurableTaskState;
+            items: never[];
+        }>;
+        onReturn({ childState, parentState, childCtx }: import("@noetic-tools/types").ReturnParams<DurableTaskState>): Promise<{
+            parentState: {
+                checkpoints: {
+                    timestamp: number;
+                    depth: number;
+                }[];
+                files: string[];
+                data: Record<string, unknown>;
+            };
+        }>;
+        onComplete({ state, outcome, ctx }: import("@noetic-tools/types").CompleteParams<DurableTaskState>): Promise<{
+            state: {
+                files: string[];
+                data: {
+                    __outcome: import("@noetic-tools/types").ExecutionOutcome;
+                };
+                checkpoints: {
+                    timestamp: number;
+                    depth: number;
+                }[];
+            };
+        } | undefined>;
+    };
+};

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

@@ -0,0 +1,250 @@
+import { createMessage, estimateTokens, Slot } from '@noetic-tools/types';
+import { z } from 'zod';
+import { layerFn } from '../layer-provides.js';
+/**
+ * Hard cap on retained checkpoints. store() appends one per model call and
+ * onReturn concatenates the child's list, so without a cap the thread-scoped
+ * (durably persisted) array grows linearly with total model calls forever.
+ * Newest checkpoints are kept.
+ */
+const MAX_CHECKPOINTS = 50;
+function trimCheckpoints(checkpoints) {
+    if (checkpoints.length <= MAX_CHECKPOINTS) {
+        return checkpoints;
+    }
+    return checkpoints.slice(checkpoints.length - MAX_CHECKPOINTS);
+}
+function renderTaskState(state) {
+    return `<task_state>\n${JSON.stringify(state, null, 2)}\n</task_state>`;
+}
+function mergeChildData({ parent, childState, childExecutionId, mergeData, }) {
+    if (mergeData === 'shallow') {
+        return {
+            ...parent.data,
+            ...childState.data,
+        };
+    }
+    return {
+        ...parent.data,
+        [childExecutionId]: childState.data,
+    };
+}
+/**
+ * Creates a context layer that persists task checkpoints, files, and arbitrary data across iterations.
+ *
+ * State is rehydrated from `ScopedStorage` on init and persisted via the
+ * runtime's durable write-through; `store` appends capped checkpoints
+ * (newest 50 kept) and `recall` trims its render to the allocated budget.
+ *
+ * The layer is writable from the model: `provides` exposes
+ * `durable-task-state/recordArtifact` (append a produced/modified file path)
+ * and `durable-task-state/setTaskData` (record a structured result under a
+ * key). Both survive the spawn boundary — a worker's artifacts merge back into
+ * its coordinator via `onReturn`.
+ *
+ * @public
+ * @param opts - Layer options; `mergeData` selects the `data` merge strategy at a child boundary.
+ * @returns A `ContextLayer` scoped to the thread with durable task state.
+ */
+export function durableTaskState(opts = {}) {
+    const mergeData = opts.mergeData ?? 'shallow';
+    return {
+        id: 'durable-task-state',
+        name: 'Durable Task State',
+        slot: Slot.WORKING_MEMORY + 10, // 110
+        // 'thread' (not 'execution'): the layer's purpose is to persist task state
+        // ACROSS executions/iterations within a thread. 'execution' scope rotates
+        // its storage key every run, so checkpoints never survived (storeLayers also
+        // skips durable persistence for 'execution' scope).
+        scope: 'thread',
+        budget: {
+            min: 100,
+            max: 800,
+        },
+        timeouts: {
+            store: 30_000,
+        },
+        provides: {
+            recordArtifact: layerFn({
+                description: 'Record a file this task produced or modified. Recorded paths survive the task boundary and merge back into the parent task.',
+                input: z.object({
+                    path: z.string().min(1),
+                }),
+                output: z.string(),
+                execute: async (args, state) => {
+                    if (state.files.includes(args.path)) {
+                        return {
+                            result: `Already recorded: ${args.path}`,
+                            state,
+                        };
+                    }
+                    return {
+                        result: `Recorded artifact: ${args.path}`,
+                        state: {
+                            ...state,
+                            files: [
+                                ...state.files,
+                                args.path,
+                            ],
+                        },
+                    };
+                },
+            }),
+            setTaskData: layerFn({
+                description: 'Record a structured result for this task under a key (e.g. a PR url, a verdict, a summary). Values survive the task boundary and merge back into the parent task.',
+                input: z.object({
+                    key: z.string().min(1),
+                    value: z.unknown(),
+                }),
+                output: z.string(),
+                execute: async (args, state) => {
+                    // `__outcome` is written by onComplete; letting the model set it would
+                    // make the recorded outcome unreliable.
+                    if (args.key === '__outcome') {
+                        return {
+                            result: 'Cannot set reserved key "__outcome".',
+                            state,
+                        };
+                    }
+                    return {
+                        result: `Recorded ${args.key}.`,
+                        state: {
+                            ...state,
+                            data: {
+                                ...state.data,
+                                [args.key]: args.value,
+                            },
+                        },
+                    };
+                },
+            }),
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                return {
+                    state: saved ?? {
+                        checkpoints: [],
+                        files: [],
+                        data: {},
+                    },
+                };
+            },
+            async recall({ state, budget }) {
+                if (!state) {
+                    return null;
+                }
+                let view = state;
+                let text = renderTaskState(view);
+                // `budget > 0` is the fail-open convention (see staticContent): a zero
+                // allocation must not delete the task state from the view.
+                if (budget > 0) {
+                    // Halve the OLDEST checkpoints while the render exceeds the budget —
+                    // files/data stay, recent checkpoints stay.
+                    while (estimateTokens(text) > budget && view.checkpoints.length > 0) {
+                        view = {
+                            ...view,
+                            checkpoints: view.checkpoints.slice(Math.ceil(view.checkpoints.length / 2)),
+                        };
+                        text = renderTaskState(view);
+                    }
+                    // Final guard: still over budget with no checkpoints left — char-slice
+                    // and keep the closing tag so the block stays well-formed.
+                    if (estimateTokens(text) > budget) {
+                        const closing = '\n</task_state>';
+                        const maxChars = Math.max(0, budget * 4 - closing.length);
+                        text = `${text.slice(0, maxChars)}${closing}`;
+                    }
+                }
+                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 (capped, newest kept)
+                const newState = {
+                    ...currentState,
+                    checkpoints: trimCheckpoints([
+                        ...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, childCtx }) {
+                // Merge child artifacts back to parent. The parent may have no state
+                // (init-less / never-initialized) — seed an empty base so the child's
+                // contribution is still merged rather than crashing.
+                const parent = parentState ?? {
+                    checkpoints: [],
+                    files: [],
+                    data: {},
+                };
+                return {
+                    parentState: {
+                        checkpoints: trimCheckpoints([
+                            ...parent.checkpoints,
+                            ...childState.checkpoints,
+                        ]),
+                        files: [
+                            ...new Set([
+                                ...parent.files,
+                                ...childState.files,
+                            ]),
+                        ],
+                        data: mergeChildData({
+                            parent,
+                            childState,
+                            childExecutionId: childCtx.executionId,
+                            mergeData,
+                        }),
+                    },
+                };
+            },
+            async onComplete({ state, outcome, ctx }) {
+                if (!state) {
+                    return;
+                }
+                return {
+                    state: {
+                        ...state,
+                        data: {
+                            ...state.data,
+                            __outcome: outcome,
+                        },
+                        checkpoints: trimCheckpoints([
+                            ...state.checkpoints,
+                            {
+                                timestamp: Date.now(),
+                                // The completing execution's own depth — a hardcoded 0 made
+                                // every terminal checkpoint look root-level regardless of
+                                // where the execution actually sat in the spawn tree.
+                                depth: ctx.depth,
+                            },
+                        ]),
+                    },
+                };
+            },
+        },
+    };
+}

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

@@ -0,0 +1,55 @@
+import type { ContextLayer } from '@noetic-tools/types';
+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 context 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): ContextLayer<FileReferenceState>;
+export {};