@noetic-tools/core 0.2.0 → 0.3.0

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

@@ -1,114 +0,0 @@
-/**
- * History-window memory 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 — for
- *      tool-burst histories the projected length can grow well beyond
- *      `maxItems` because the most recent role-pair may be far back.
- *   3. Drop any orphan `function_call` / `function_call_output` left at the
- *      slice boundary via `stripUnresolvedToolCalls`.
- */
-import { NoeticConfigError } from '../../errors/noetic-config-error.js';
-import { Slot } from '../../types/memory.js';
-import { isAssistantMessage, isUserMessage } from '../../util/message-helpers.js';
-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
-//#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;
-}
-//#endregion
-//#region Public API
-/**
- * Creates a history-window memory 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 `MemoryLayer` 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;
-                const expandedStart = expandToMinimumExchange(items, sliceStart);
-                const window = items.slice(expandedStart);
-                const cleaned = stripUnresolvedToolCalls(window);
-                return {
-                    items: cleaned,
-                };
-            },
-        },
-    };
-}
-//#endregion

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

@@ -1,53 +0,0 @@
-export interface ObservationalState {
-    observations: string[];
-    buffer: string[];
-    bufferTokens: number;
-    version: number;
-}
-export type ObserverFn = (buffer: string[]) => Promise<string[]>;
-export interface ObservationalMemoryConfig {
-    bufferThreshold?: number;
-    maxObservations?: number;
-    scope?: 'thread' | 'resource';
-    observer?: ObserverFn;
-}
-/**
- * Creates a memory 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 `MemoryLayer` that accumulates and summarizes observations over time.
- */
-export declare function observationalMemory(config?: ObservationalMemoryConfig): {
-    id: "observational-memory";
-    name: string;
-    slot: 200;
-    scope: "thread" | "resource";
-    budget: {
-        min: number;
-        max: number;
-    };
-    timeouts: {
-        store: number;
-    };
-    hooks: {
-        init({ storage }: import("../../index.js").InitParams): Promise<{
-            state: ObservationalState;
-        }>;
-        recall({ state }: import("../../index.js").RecallParams<ObservationalState>): Promise<{
-            items: import("../../index.js").InputMessageItem[];
-            tokenCount: number;
-        } | null>;
-        store({ newItems, state }: import("../../index.js").StoreParams<ObservationalState>): Promise<{
-            state: {
-                buffer: string[];
-                bufferTokens: number;
-                observations: string[];
-                version: number;
-            };
-        }>;
-        onSpawn({ parentState }: import("../../index.js").SpawnParams<ObservationalState>): Promise<{
-            childState: ObservationalState;
-        }>;
-    };
-};

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

@@ -1,109 +0,0 @@
-import { Slot } from '../../types/memory.js';
-import { createMessage, estimateTokens, isOutputText } from '../../util/message-helpers.js';
-const DEFAULT_BUFFER_THRESHOLD_TOKENS = 2_000;
-const DEFAULT_MAX_OBSERVATIONS = 50;
-/**
- * Creates a memory 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 `MemoryLayer` that accumulates and summarizes observations over time.
- */
-export function observationalMemory(config) {
-    const maxObs = config?.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;
-    const threshold = config?.bufferThreshold ?? DEFAULT_BUFFER_THRESHOLD_TOKENS;
-    const observer = config?.observer;
-    return {
-        id: 'observational-memory',
-        name: 'Observational Memory',
-        slot: Slot.OBSERVATIONS,
-        scope: config?.scope ?? 'resource',
-        budget: {
-            min: 500,
-            max: 2_500,
-        },
-        timeouts: {
-            store: 60_000,
-        },
-        hooks: {
-            async init({ storage }) {
-                const saved = await storage.get('state');
-                return {
-                    state: saved ?? {
-                        observations: [],
-                        buffer: [],
-                        bufferTokens: 0,
-                        version: 0,
-                    },
-                };
-            },
-            async recall({ state }) {
-                if (!state?.observations?.length) {
-                    return null;
-                }
-                const bullets = state.observations.map((o) => `- ${o}`).join('\n');
-                const text = `<observations>\n${bullets}\n</observations>`;
-                return {
-                    items: [
-                        createMessage(text, 'developer'),
-                    ],
-                    tokenCount: estimateTokens(text),
-                };
-            },
-            async store({ newItems, state }) {
-                const s = state ?? {
-                    observations: [],
-                    buffer: [],
-                    bufferTokens: 0,
-                    version: 0,
-                };
-                // Accumulate new items into buffer
-                const textItems = newItems
-                    .filter((i) => i.type === 'message')
-                    .map((i) => i.content
-                    .filter(isOutputText)
-                    .map((c) => c.text)
-                    .join(''))
-                    .filter((t) => t.length > 0);
-                const newBuffer = [
-                    ...s.buffer,
-                    ...textItems,
-                ];
-                // Token-based threshold: accumulate incrementally
-                const newTokens = textItems.reduce((sum, t) => sum + estimateTokens(t), 0);
-                const totalBufferTokens = s.bufferTokens + newTokens;
-                if (totalBufferTokens >= threshold) {
-                    const distilled = observer
-                        ? await observer(newBuffer)
-                        : [
-                            `Processed ${newBuffer.length} items`,
-                        ];
-                    const newObservations = [
-                        ...s.observations,
-                        ...distilled,
-                    ].slice(-maxObs);
-                    return {
-                        state: {
-                            observations: newObservations,
-                            buffer: [],
-                            bufferTokens: 0,
-                            version: s.version + 1,
-                        },
-                    };
-                }
-                return {
-                    state: {
-                        ...s,
-                        buffer: newBuffer,
-                        bufferTokens: totalBufferTokens,
-                    },
-                };
-            },
-            async onSpawn({ parentState }) {
-                return {
-                    childState: structuredClone(parentState),
-                };
-            },
-        },
-    };
-}

package/dist/memory/layers/plan.d.ts

@@ -1,55 +0,0 @@
-import type { MemoryLayer, MemoryScope } from '../../types/memory.js';
-import type { FlowNode } from '../flow-schema.js';
-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;
-    planTree: FlowNode | null;
-    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 PlanMemoryConfig {
-    scope?: MemoryScope;
-    additionalAllowedTools?: string[];
-    maxPrdLength?: number;
-    maxTreeDepth?: number;
-    /** 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 memory layer that manages the PRD authoring and plan execution lifecycle.
- *
- * @public
- * @param config - Optional configuration for scope, allowed tools, and limits.
- * @returns A `MemoryLayer` providing plan mode, PRD storage, and execution tracking.
- */
-export declare function planMemory(config?: PlanMemoryConfig): MemoryLayer<PlanState>;