@noetic-tools/context 1.0.0

package/dist/context/layers/history-window.d.ts

@@ -0,0 +1,31 @@
+/**
+ * History-window context layer — caps the number of items projected to the LLM
+ * without touching `itemLog` storage. Pure read-side projection via the
+ * `projectHistory` hook.
+ *
+ * Algorithm per turn:
+ *   1. Slice the last `maxItems`.
+ *   2. If the slice lacks a user `message` or an assistant `message`, expand
+ *      backward until both are present. The cap may be exceeded, but only up to
+ *      a hard bound (`maxItems * MAX_EXPANSION_MULTIPLE`) — a tool-only burst
+ *      cannot grow the window back to the start of history.
+ *   3. Re-attach a system/anchor message from the head if it fell outside the
+ *      window, so core instructions survive windowing.
+ *   4. Drop any orphan `function_call` / `function_call_output` left at the
+ *      slice boundary via `stripUnresolvedToolCalls`.
+ */
+import type { ContextLayer } from '@noetic-tools/types';
+/** @public Configuration for the {@link historyWindow} layer. */
+export interface HistoryWindowConfig {
+    /** Cap on the number of trailing items projected to the LLM. Defaults to 40. */
+    maxItems?: number;
+}
+/**
+ * Creates a history-window context layer that caps the trailing items projected
+ * to the LLM. Storage stays unbounded; only the wire payload is narrowed.
+ *
+ * @public
+ * @param config - Optional `{ maxItems }`. Defaults to 40.
+ * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
+ */
+export declare function historyWindow(config?: HistoryWindowConfig): ContextLayer<null>;

package/dist/context/layers/history-window.js

@@ -0,0 +1,150 @@
+/**
+ * History-window context layer — caps the number of items projected to the LLM
+ * without touching `itemLog` storage. Pure read-side projection via the
+ * `projectHistory` hook.
+ *
+ * Algorithm per turn:
+ *   1. Slice the last `maxItems`.
+ *   2. If the slice lacks a user `message` or an assistant `message`, expand
+ *      backward until both are present. The cap may be exceeded, but only up to
+ *      a hard bound (`maxItems * MAX_EXPANSION_MULTIPLE`) — a tool-only burst
+ *      cannot grow the window back to the start of history.
+ *   3. Re-attach a system/anchor message from the head if it fell outside the
+ *      window, so core instructions survive windowing.
+ *   4. Drop any orphan `function_call` / `function_call_output` left at the
+ *      slice boundary via `stripUnresolvedToolCalls`.
+ */
+import { isAssistantMessage, isUserMessage, NoeticConfigError, Slot } from '@noetic-tools/types';
+import { stripUnresolvedToolCalls } from '../strip-unresolved.js';
+//#region Constants
+const DEFAULT_MAX_ITEMS = 40;
+const MIN_MAX_ITEMS = 2;
+const MAX_MAX_ITEMS = 1e4;
+const HISTORY_WINDOW_SLOT = Slot.PROCEDURAL + 25; // 275 — runs after recall-contributing layers
+// Hard upper bound on how far minimum-exchange expansion may grow the window,
+// expressed as a multiple of maxItems. Without this, a tool-only burst lets the
+// window expand back to the first role-pair, defeating the cap entirely.
+const MAX_EXPANSION_MULTIPLE = 4;
+// How many leading items to scan for a system/anchor message to preserve.
+const ANCHOR_SCAN_LIMIT = 4;
+//#endregion
+//#region Helpers
+function validateMaxItems(value) {
+    if (!Number.isInteger(value) || value < MIN_MAX_ITEMS || value > MAX_MAX_ITEMS) {
+        throw new NoeticConfigError({
+            code: 'INVALID_HISTORY_WINDOW_MAX_ITEMS',
+            message: `historyWindow: maxItems must be an integer in [${MIN_MAX_ITEMS}, ${MAX_MAX_ITEMS}], got ${value}`,
+            hint: 'Pass a sensible cap such as { maxItems: 40 }, or omit the layer to keep history uncapped.',
+        });
+    }
+}
+/**
+ * Walk backwards from the natural slice point until both a user message and
+ * an assistant message are present. Returns the index at which the projected
+ * window should start in the full `items` array.
+ */
+function expandToMinimumExchange(items, sliceStart) {
+    let start = sliceStart;
+    let needsUser = true;
+    let needsAssistant = true;
+    // Pass 1: scan the natural slice for the user/assistant pair. Early-return
+    // at the original sliceStart when both roles are already inside.
+    for (let i = items.length - 1; i >= start; i--) {
+        const item = items[i];
+        if (needsUser && isUserMessage(item)) {
+            needsUser = false;
+        }
+        if (needsAssistant && isAssistantMessage(item)) {
+            needsAssistant = false;
+        }
+        if (!needsUser && !needsAssistant) {
+            return start;
+        }
+    }
+    // Pass 2: walk backward past the slice until the missing role(s) are found.
+    for (let i = start - 1; i >= 0 && (needsUser || needsAssistant); i--) {
+        const item = items[i];
+        if (needsUser && isUserMessage(item)) {
+            needsUser = false;
+            start = i;
+            continue;
+        }
+        if (needsAssistant && isAssistantMessage(item)) {
+            needsAssistant = false;
+            start = i;
+        }
+    }
+    return start;
+}
+/**
+ * Find a system/anchor message in the leading items that falls outside the
+ * projected window (`windowStart`). Returns it so it can be re-attached to the
+ * head of the projection; returns null when there is none.
+ */
+function findHeadAnchor(items, windowStart) {
+    const limit = Math.min(windowStart, ANCHOR_SCAN_LIMIT);
+    for (let i = 0; i < limit; i++) {
+        const item = items[i];
+        if (item.type === 'message' && item.role === 'system') {
+            return item;
+        }
+    }
+    return null;
+}
+//#endregion
+//#region Public API
+/**
+ * Creates a history-window context layer that caps the trailing items projected
+ * to the LLM. Storage stays unbounded; only the wire payload is narrowed.
+ *
+ * @public
+ * @param config - Optional `{ maxItems }`. Defaults to 40.
+ * @returns A `ContextLayer` that contributes only a `projectHistory` hook.
+ */
+export function historyWindow(config) {
+    const maxItems = config?.maxItems ?? DEFAULT_MAX_ITEMS;
+    validateMaxItems(maxItems);
+    return {
+        id: 'history-window',
+        name: 'History Window',
+        slot: HISTORY_WINDOW_SLOT,
+        scope: 'execution',
+        hooks: {
+            async init() {
+                return {
+                    state: null,
+                };
+            },
+            async projectHistory({ items }) {
+                if (items.length <= maxItems) {
+                    return {
+                        items,
+                    };
+                }
+                const sliceStart = items.length - maxItems;
+                let expandedStart = expandToMinimumExchange(items, sliceStart);
+                // Hard upper bound: minimum-exchange expansion (e.g. for a tool-only
+                // burst) must never grow the window without limit. Drop the oldest
+                // excess so the projected count stays a bounded multiple of maxItems.
+                const maxWindow = maxItems * MAX_EXPANSION_MULTIPLE;
+                if (items.length - expandedStart > maxWindow) {
+                    expandedStart = items.length - maxWindow;
+                }
+                const window = items.slice(expandedStart);
+                // Preserve a system/anchor message at the head even when it falls
+                // outside the trailing window.
+                const anchor = findHeadAnchor(items, expandedStart);
+                const cleaned = stripUnresolvedToolCalls(anchor
+                    ? [
+                        anchor,
+                        ...window,
+                    ]
+                    : window);
+                return {
+                    items: cleaned,
+                };
+            },
+        },
+    };
+}
+//#endregion

package/dist/context/layers/observational-context.d.ts

@@ -0,0 +1,56 @@
+export interface ObservationalState {
+    observations: string[];
+    buffer: string[];
+    bufferTokens: number;
+    version: number;
+}
+export type ObserverFn = (buffer: string[]) => Promise<string[]>;
+export interface ObservationalContextConfig {
+    bufferThreshold?: number;
+    maxObservations?: number;
+    scope?: 'thread' | 'resource';
+    observer?: ObserverFn;
+}
+/**
+ * Creates a context layer that buffers raw items and distills them into observations when a token threshold is reached.
+ *
+ * @public
+ * @param config - Optional configuration for buffer threshold, max observations, scope, and observer function.
+ * @returns A `ContextLayer` that accumulates and summarizes observations over time.
+ */
+export declare function observationalContext(config?: ObservationalContextConfig): {
+    id: 'observational-context';
+    name: string;
+    slot: 200;
+    scope: "resource" | "thread";
+    budget: {
+        min: number;
+        max: number;
+    };
+    timeouts: {
+        store: number;
+        onItemAppend: number;
+    };
+    hooks: {
+        init({ storage }: import("@noetic-tools/types").InitParams): Promise<{
+            state: ObservationalState;
+        }>;
+        recall({ state, budget }: import("@noetic-tools/types").RecallParams<ObservationalState>): Promise<{
+            items: import("@noetic-tools/types").InputMessageItem[];
+            tokenCount: number;
+        } | null>;
+        store({ newItems, state }: import("@noetic-tools/types").StoreParams<ObservationalState>): Promise<{
+            state: ObservationalState;
+        }>;
+        onItemAppend({ items, state }: import("@noetic-tools/types").OnItemAppendParams<ObservationalState>): Promise<{
+            items: import("@noetic-tools/types").Item[];
+            state?: undefined;
+        } | {
+            items: import("@noetic-tools/types").Item[];
+            state: ObservationalState;
+        }>;
+        onSpawn({ parentState }: import("@noetic-tools/types").SpawnParams<ObservationalState>): Promise<{
+            childState: ObservationalState;
+        }>;
+    };
+};

package/dist/context/layers/observational-context.js

@@ -0,0 +1,152 @@
+import { collectInputText, collectOutputText, createMessage, estimateTokens, Slot, } from '@noetic-tools/types';
+const DEFAULT_BUFFER_THRESHOLD_TOKENS = 2_000;
+const DEFAULT_MAX_OBSERVATIONS = 50;
+function emptyObservationalState() {
+    return {
+        observations: [],
+        buffer: [],
+        bufferTokens: 0,
+        version: 0,
+    };
+}
+/**
+ * Appends `texts` into the layer buffer and, once the token threshold is crossed,
+ * distills the buffer into observations. Shared by `store` (assistant output) and
+ * `onItemAppend` (user/tool input).
+ */
+async function accumulate(s, texts, cfg) {
+    const newBuffer = [
+        ...s.buffer,
+        ...texts,
+    ];
+    const newTokens = texts.reduce((sum, t) => sum + estimateTokens(t), 0);
+    const totalBufferTokens = s.bufferTokens + newTokens;
+    if (totalBufferTokens >= cfg.threshold) {
+        const distilled = cfg.observer
+            ? await cfg.observer(newBuffer)
+            : [
+                `Processed ${newBuffer.length} items`,
+            ];
+        const newObservations = [
+            ...s.observations,
+            ...distilled,
+        ].slice(-cfg.maxObs);
+        return {
+            observations: newObservations,
+            buffer: [],
+            bufferTokens: 0,
+            version: s.version + 1,
+        };
+    }
+    return {
+        ...s,
+        buffer: newBuffer,
+        bufferTokens: totalBufferTokens,
+    };
+}
+/** Render observations as a tagged bullet list. */
+function renderObservations(observations) {
+    const bullets = observations.map((o) => `- ${o}`).join('\n');
+    return `<observations>\n${bullets}\n</observations>`;
+}
+/**
+ * Render the most recent observations that fit within `budget` tokens (rendered
+ * output included). Drops oldest observations first; returns null if not even
+ * the single newest observation fits.
+ */
+function renderObservationsWithinBudget(observations, budget) {
+    for (let start = 0; start < observations.length; start++) {
+        const text = renderObservations(observations.slice(start));
+        if (estimateTokens(text) <= budget) {
+            return text;
+        }
+    }
+    return null;
+}
+/**
+ * Creates a context layer that buffers raw items and distills them into observations when a token threshold is reached.
+ *
+ * @public
+ * @param config - Optional configuration for buffer threshold, max observations, scope, and observer function.
+ * @returns A `ContextLayer` that accumulates and summarizes observations over time.
+ */
+export function observationalContext(config) {
+    const maxObs = config?.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;
+    const threshold = config?.bufferThreshold ?? DEFAULT_BUFFER_THRESHOLD_TOKENS;
+    const observer = config?.observer;
+    return {
+        id: 'observational-context',
+        name: 'Observational Context',
+        slot: Slot.OBSERVATIONS,
+        scope: config?.scope ?? 'resource',
+        budget: {
+            min: 500,
+            max: 2_500,
+        },
+        timeouts: {
+            store: 60_000,
+            // onItemAppend runs the same LLM-backed accumulate/distill path as
+            // store — it needs the same headroom, not the 5s pipeline default.
+            onItemAppend: 60_000,
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                return {
+                    state: saved ?? emptyObservationalState(),
+                };
+            },
+            async recall({ state, budget }) {
+                if (!state?.observations?.length) {
+                    return null;
+                }
+                // Trim to the most recent observations that fit within the token budget.
+                const text = renderObservationsWithinBudget(state.observations, budget);
+                if (text === null) {
+                    return null;
+                }
+                return {
+                    items: [
+                        createMessage(text, 'developer'),
+                    ],
+                    tokenCount: estimateTokens(text),
+                };
+            },
+            // Captures assistant output text.
+            async store({ newItems, state }) {
+                const s = state ?? emptyObservationalState();
+                const texts = collectOutputText(newItems);
+                return {
+                    state: await accumulate(s, texts, {
+                        threshold,
+                        maxObs,
+                        observer,
+                    }),
+                };
+            },
+            // Captures user input and tool output text (pass-through; no transform).
+            async onItemAppend({ items, state }) {
+                const s = state ?? emptyObservationalState();
+                const texts = collectInputText(items);
+                if (texts.length === 0) {
+                    return {
+                        items,
+                    };
+                }
+                return {
+                    items,
+                    state: await accumulate(s, texts, {
+                        threshold,
+                        maxObs,
+                        observer,
+                    }),
+                };
+            },
+            async onSpawn({ parentState }) {
+                return {
+                    childState: structuredClone(parentState),
+                };
+            },
+        },
+    };
+}

package/dist/context/layers/plan-context.d.ts

@@ -0,0 +1,73 @@
+import type { ContextLayer, ContextScope, WorkflowDocument, WorkflowNode } from '@noetic-tools/types';
+export declare const PlanPhase: {
+    readonly Idle: 'idle';
+    readonly Planning: 'planning';
+    readonly Executing: 'executing';
+    readonly Completed: 'completed';
+    readonly Failed: 'failed';
+};
+export type PlanPhase = (typeof PlanPhase)[keyof typeof PlanPhase];
+export interface PlanExecutionEntry {
+    timestamp: number;
+    version: number;
+    outcome: 'success' | 'failure' | 'aborted';
+}
+export interface PlanState {
+    phase: PlanPhase;
+    prd: string | null;
+    /** The reviewed plan: a complete JSON workflow document. */
+    planTree: WorkflowDocument | null;
+    /** Named workflows referenced from the tree via `{ kind: 'subflow', ref }` nodes. */
+    workflows: Record<string, WorkflowDocument>;
+    executionLog: PlanExecutionEntry[];
+    version: number;
+    /** Identifier of the on-disk plan session (set by `onEnterSession` host callback). */
+    planSlug?: string | null;
+}
+/** Host-supplied callback invoked when entering plan mode. Returns a session identifier the host owns (e.g. on-disk dir slug). */
+export type PlanEnterSessionCallback = () => Promise<{
+    slug: string;
+}>;
+/**
+ * Host-supplied callback invoked when the model requests `exitPlanMode` with `action: 'execute'`.
+ * Return `{ approved: false }` to keep the layer in `Planning` (e.g. user rejected the plan in the UI).
+ */
+export type PlanExitCallback = (state: PlanState) => Promise<{
+    approved: boolean;
+}>;
+export interface PlanContextConfig {
+    scope?: ContextScope;
+    additionalAllowedTools?: string[];
+    maxPrdLength?: number;
+    /** Max structural depth (`workflowDepth`) of the plan tree and each named workflow. Default 5. */
+    maxDepth?: number;
+    /** Max number of named workflows a plan may store. Default 20. */
+    maxWorkflows?: number;
+    /** Max serialized size (`JSON.stringify` length) of each workflow document. Default 20000. */
+    maxWorkflowChars?: number;
+    /**
+     * Optional profile restricting which `WorkflowNode` kinds the plan tree and
+     * named workflows may use. Undefined allows all kinds. Hosts that set this
+     * must include `'subflow'` for named workflows to be referenceable.
+     */
+    allowedNodeKinds?: WorkflowNode['kind'][];
+    /** Extra free-form instructions appended to the planning-phase recall payload. */
+    additionalPlanInstructions?: string;
+    /** Called once when the layer transitions Idle → Planning. */
+    onEnterSession?: PlanEnterSessionCallback;
+    /** Called when `exitPlanMode` is requested with `action: 'execute'`. */
+    onExit?: PlanExitCallback;
+}
+/**
+ * Creates a plan context layer that manages the PRD authoring and plan execution lifecycle.
+ *
+ * The plan tree is a JSON `WorkflowDocument`; plans additionally store named
+ * workflows referenced from the tree via `subflow` nodes, keeping the reviewed
+ * tree small. On approval, hosts execute the plan by feeding `planTree` and
+ * `workflows` to the JSON workflow runtime (`parseAndRunWorkflow`).
+ *
+ * @public
+ * @param config - Optional configuration for scope, allowed tools, and limits.
+ * @returns A `ContextLayer` providing plan mode, PRD storage, and execution tracking.
+ */
+export declare function planContext(config?: PlanContextConfig): ContextLayer<PlanState>;