@noetic-tools/core 0.2.0 → 0.3.0

package/dist/memory/layers/steering.js

@@ -1,258 +0,0 @@
-import { NoeticConfigError } from '../../errors/noetic-config-error.js';
-import { Slot } from '../../types/memory.js';
-import { LedgerEntryKind, SteeringAction } from '../../types/steering.js';
-import { createMessage, estimateTokens, extractAssistantText } from '../../util/message-helpers.js';
-import { mostRestrictive } from '../layer-lifecycle.js';
-//#region Constants
-const DEFAULT_MAX_LEDGER_ENTRIES = 100;
-//#endregion
-//#region Rule Evaluation Helpers
-function requireCallModel(params, ruleId) {
-    if (!params.ctx.callModel) {
-        throw new NoeticConfigError({
-            code: 'MISSING_CALL_MODEL',
-            message: `LLM-evaluated steering rule "${ruleId}" requires a callModel but none is available.`,
-            hint: 'Pass `llm: { provider: "openrouter", apiKey: "..." }` to AgentHarness or set OPENROUTER_API_KEY.',
-        });
-    }
-}
-function evaluateProgrammaticRule(rule, params) {
-    if (!rule.predicate) {
-        return null;
-    }
-    return rule.predicate(params);
-}
-async function evaluateLlmRuleSync(rule, params) {
-    if (!rule.llmEval) {
-        return {
-            action: SteeringAction.Allow,
-        };
-    }
-    const { callModel } = params.ctx;
-    if (!callModel) {
-        return {
-            action: SteeringAction.Allow,
-        };
-    }
-    const contextSummary = 'toolName' in params
-        ? `Tool: ${params.toolName}, Args: ${JSON.stringify(params.toolArgs)}`
-        : `Response items: ${params.response.items.length}`;
-    const prompt = `${rule.llmEval.prompt}\n\nContext: ${contextSummary}\n\nRespond with exactly "ALLOW", "DENY", or "GUIDE: <guidance text>".`;
-    const userMessage = createMessage(prompt, 'user');
-    const model = rule.llmEval.model ?? 'openai/gpt-4o-mini';
-    const response = await callModel({
-        model,
-        items: [
-            userMessage,
-        ],
-    });
-    const text = extractAssistantText(response.items).trim().toUpperCase();
-    if (text.startsWith('DENY')) {
-        return {
-            action: SteeringAction.Deny,
-            guidance: text.slice(5).trim() || undefined,
-        };
-    }
-    if (text.startsWith('GUIDE:')) {
-        return {
-            action: SteeringAction.Guide,
-            guidance: text.slice(6).trim(),
-        };
-    }
-    return {
-        action: SteeringAction.Allow,
-    };
-}
-function fireLlmRuleAsync({ rule, params, pendingAsync }) {
-    evaluateLlmRuleSync(rule, params)
-        .then((decision) => {
-        if (decision.action !== SteeringAction.Allow) {
-            pendingAsync.push({
-                ruleId: rule.id,
-                guidance: decision.guidance ?? `Rule ${rule.id}: ${decision.action}`,
-            });
-        }
-    })
-        .catch(() => {
-        // Async LLM eval failures are silently swallowed — they must not disrupt the agent
-    });
-}
-function trimLedger(ledger, max) {
-    if (ledger.length <= max) {
-        return ledger;
-    }
-    return ledger.slice(ledger.length - max);
-}
-async function evaluateRules({ rules, hookName, params, state, }) {
-    const applicable = rules.filter((r) => r.appliesTo.includes(hookName));
-    const decisions = [];
-    for (const rule of applicable) {
-        // Programmatic predicate (fast)
-        const programmatic = evaluateProgrammaticRule(rule, params);
-        if (programmatic) {
-            decisions.push(programmatic);
-            if (programmatic.action === SteeringAction.Deny) {
-                return mostRestrictive(decisions);
-            }
-            continue;
-        }
-        // LLM eval — throws NoeticConfigError if callModel is missing
-        if (!rule.llmEval) {
-            continue;
-        }
-        requireCallModel(params, rule.id);
-        if (rule.llmEval.mode === 'sync') {
-            const decision = await evaluateLlmRuleSync(rule, params);
-            decisions.push(decision);
-            if (decision.action === SteeringAction.Deny) {
-                return mostRestrictive(decisions);
-            }
-            continue;
-        }
-        // Async — fire and forget
-        fireLlmRuleAsync({
-            rule,
-            params,
-            pendingAsync: state.pendingAsync,
-        });
-    }
-    return mostRestrictive(decisions);
-}
-//#endregion
-//#region Public API
-/**
- * Creates a steering memory layer that evaluates rules before tool calls and after model calls.
- *
- * @public
- * @param config - Steering configuration including rules, scope, and max ledger size.
- * @returns A `MemoryLayer` that enforces steering rules via allow/deny/guide decisions.
- */
-export function steering(config) {
-    const maxLedger = config.maxLedgerEntries ?? DEFAULT_MAX_LEDGER_ENTRIES;
-    const scope = config.scope ?? 'execution';
-    return {
-        id: 'steering',
-        name: 'Steering',
-        slot: Slot.STEERING,
-        scope,
-        budget: {
-            min: 0,
-            max: 500,
-        },
-        timeouts: {
-            beforeToolCall: 5e3,
-            afterModelCall: 1e4,
-        },
-        hooks: {
-            async init({ storage }) {
-                const saved = await storage.get('state');
-                const state = saved ?? {
-                    ledger: [],
-                    pendingAsync: [],
-                };
-                return {
-                    state,
-                };
-            },
-            async recall({ state }) {
-                if (state.pendingAsync.length === 0) {
-                    return null;
-                }
-                const feedback = state.pendingAsync.map((p) => `[${p.ruleId}] ${p.guidance}`).join('\n');
-                state.pendingAsync = [];
-                const content = `<steering_feedback>\n${feedback}\n</steering_feedback>`;
-                return {
-                    items: [
-                        createMessage(content, 'developer'),
-                    ],
-                    tokenCount: estimateTokens(content),
-                    state,
-                };
-            },
-            async store() {
-                // Model turn ledger entries are recorded in afterModelCall to avoid duplicates
-                return undefined;
-            },
-            async beforeToolCall({ toolName, toolArgs, ctx, state }) {
-                const decision = await evaluateRules({
-                    rules: config.rules,
-                    hookName: 'beforeToolCall',
-                    params: {
-                        toolName,
-                        toolArgs,
-                        ctx,
-                        state,
-                    },
-                    state,
-                });
-                const entry = {
-                    kind: LedgerEntryKind.ToolCall,
-                    timestamp: Date.now(),
-                    toolName,
-                    toolArgs,
-                    ruleId: decision.action !== SteeringAction.Allow ? 'steering' : undefined,
-                    action: decision.action,
-                    guidance: decision.guidance,
-                };
-                state.ledger.push(entry);
-                state.ledger = trimLedger(state.ledger, maxLedger);
-                return {
-                    decision,
-                    state,
-                };
-            },
-            async afterModelCall({ response, ctx, state }) {
-                const decision = await evaluateRules({
-                    rules: config.rules,
-                    hookName: 'afterModelCall',
-                    params: {
-                        response,
-                        ctx,
-                        state,
-                    },
-                    state,
-                });
-                const entry = {
-                    kind: LedgerEntryKind.ModelTurn,
-                    timestamp: Date.now(),
-                    tokenUsage: {
-                        input: response.usage.inputTokens,
-                        output: response.usage.outputTokens,
-                    },
-                    ruleId: decision.action !== SteeringAction.Allow ? 'steering' : undefined,
-                    action: decision.action,
-                    guidance: decision.guidance,
-                };
-                state.ledger.push(entry);
-                state.ledger = trimLedger(state.ledger, maxLedger);
-                return {
-                    decision,
-                    state,
-                };
-            },
-            async onSpawn({ parentState }) {
-                return {
-                    childState: {
-                        ledger: structuredClone(parentState.ledger),
-                        pendingAsync: [],
-                    },
-                };
-            },
-            async onComplete({ state, outcome }) {
-                const entry = {
-                    kind: LedgerEntryKind.Custom,
-                    timestamp: Date.now(),
-                    custom: {
-                        outcome,
-                    },
-                };
-                state.ledger.push(entry);
-                state.ledger = trimLedger(state.ledger, maxLedger);
-                return {
-                    state,
-                };
-            },
-        },
-    };
-}
-//#endregion

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

@@ -1,91 +0,0 @@
-import type { MemoryLayer, MemoryScope } from '../../types/memory.js';
-/**
- * A single remembered fact tied to an instant.
- * @public
- */
-export interface TemporalFact {
-    /** ISO-8601 timestamp the fact is associated with (when it happened / was stated). */
-    ts: string;
-    /** The fact, stated tersely. */
-    fact: string;
-}
-/**
- * Result of a temporal memory search.
- * @public
- */
-export interface TemporalSearchResult {
-    /** Matching facts, most relevant first. */
-    facts: string[];
-    /** A resolved date for the query, when one applies (ISO-8601 or a natural phrase). */
-    date?: string;
-    /** True when `date` is approximate ("around March", "a few weeks ago"). */
-    fuzzy?: boolean;
-}
-/**
- * Extracts timestamped facts from a batch of conversation text. Host-injected so
- * the layer stays LLM-agnostic and tree-shakable (mirrors `observationalMemory`'s
- * `observer`). When omitted, the layer only buffers — it never fabricates facts.
- * @public
- */
-export type FactExtractor = (input: {
-    transcript: string;
-    now: string;
-}) => Promise<TemporalFact[]>;
-/**
- * Searches the stored fact ledger for a query, optionally resolving a date.
- * Host-injected. When omitted, search falls back to returning the raw ledger.
- * @public
- */
-export type FactSearcher = (input: {
-    query: string;
-    facts: ReadonlyArray<TemporalFact>;
-    now: string;
-}) => Promise<TemporalSearchResult>;
-/**
- * Configuration for {@link temporalMemory}.
- * @public
- */
-export interface TemporalMemoryConfig {
-    /** Returns "now" for date grounding/extraction. Defaults to the system clock. */
-    now?: () => Date;
-    /** Memory scope. Defaults to `'resource'` (long-term, cross-session). */
-    scope?: MemoryScope;
-    /** LLM-backed fact extractor. Without it, `store` only buffers (no extraction). */
-    extract?: FactExtractor;
-    /** LLM-backed fact searcher. Without it, `searchMemory` returns the raw ledger. */
-    search?: FactSearcher;
-    /** Buffered output tokens that trigger an extraction pass. Default 2000. */
-    bufferThreshold?: number;
-    /** Maximum facts retained (oldest dropped beyond this). Default 200. */
-    maxFacts?: number;
-    /** Inject a `<current_datetime>` grounding block on recall. Default true. */
-    groundDateTime?: boolean;
-    /** Inject the fact ledger on recall (vs. on-demand via the search tool). Default false. */
-    injectLedger?: boolean;
-}
-interface TemporalState {
-    /** ISO timestamp → facts recorded at that instant. */
-    facts: Record<string, string[]>;
-    /** Accumulated output text awaiting extraction. */
-    buffer: string[];
-    bufferTokens: number;
-    version: number;
-}
-/**
- * A non-atomic, LLM-backed memory layer that extracts timestamped facts from the
- * conversation into a key-value ledger (key = ISO timestamp) and exposes a
- * `temporal/searchMemory` tool for relative-time recall — given a fact/query it
- * returns matching facts and, when applicable, a resolved (possibly fuzzy) date.
- *
- * The layer is LLM-agnostic: the host injects `extract` and `search` callbacks
- * (mirrors `observationalMemory`'s `observer`), keeping `memory/` tree-shakable.
- * Without them, the layer still buffers text and the search tool returns the raw
- * ledger — it never fabricates facts. A `<current_datetime>` grounding block is
- * injected on recall by default to anchor relative-time reasoning.
- *
- * @public
- * @param config - Clock, scope, injected LLM callbacks, and tuning knobs.
- * @returns A `MemoryLayer` with a fact-ledger store + `searchMemory` tool.
- */
-export declare function temporalMemory(config?: TemporalMemoryConfig): MemoryLayer<TemporalState>;
-export {};

package/dist/memory/layers/temporal.js

@@ -1,245 +0,0 @@
-import { z } from 'zod';
-import { Slot } from '../../types/memory.js';
-import { createMessage, estimateTokens, isOutputText } from '../../util/message-helpers.js';
-import { layerFn } from '../layer-provides.js';
-function emptyState() {
-    return {
-        facts: {},
-        buffer: [],
-        bufferTokens: 0,
-        version: 0,
-    };
-}
-const DEFAULT_BUFFER_THRESHOLD_TOKENS = 2_000;
-const DEFAULT_MAX_FACTS = 200;
-//#endregion
-//#region Date grounding
-const WEEKDAYS = [
-    'Sun',
-    'Mon',
-    'Tue',
-    'Wed',
-    'Thu',
-    'Fri',
-    'Sat',
-];
-/** Formats an instant as `YYYY/MM/DD (Ddd) HH:MM` using local fields. */
-function formatNow(date) {
-    const yyyy = date.getFullYear();
-    const mm = String(date.getMonth() + 1).padStart(2, '0');
-    const dd = String(date.getDate()).padStart(2, '0');
-    const day = WEEKDAYS[date.getDay()];
-    const hh = String(date.getHours()).padStart(2, '0');
-    const min = String(date.getMinutes()).padStart(2, '0');
-    return `${yyyy}/${mm}/${dd} (${day}) ${hh}:${min}`;
-}
-function renderDateTimeBlock(date) {
-    return [
-        '<current_datetime>',
-        `Now: ${formatNow(date)}`,
-        'Resolve relative time ("N days/weeks/months ago", "last/next <weekday>",',
-        '"before/after", "first/earliest/most recent", "how long since/until") against',
-        'Now above and compute the difference explicitly before answering. Use the',
-        'temporal/searchMemory tool to look up when something happened.',
-        '</current_datetime>',
-    ].join('\n');
-}
-//#endregion
-//#region Ledger helpers
-/** Flattens the KV ledger into a flat, chronologically sorted fact list. */
-function ledgerToFacts(state) {
-    const out = [];
-    for (const [ts, facts] of Object.entries(state.facts)) {
-        for (const fact of facts) {
-            out.push({
-                ts,
-                fact,
-            });
-        }
-    }
-    out.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
-    return out;
-}
-/** Merges new facts into the KV ledger, capping total facts to `maxFacts` (oldest dropped). */
-function mergeFacts(state, incoming, maxFacts) {
-    const facts = {};
-    for (const [ts, list] of Object.entries(state.facts)) {
-        facts[ts] = [
-            ...list,
-        ];
-    }
-    for (const { ts, fact } of incoming) {
-        const list = facts[ts] ?? [];
-        if (!list.includes(fact)) {
-            list.push(fact);
-        }
-        facts[ts] = list;
-    }
-    // Cap: drop oldest timestamps until under maxFacts.
-    let total = 0;
-    for (const list of Object.values(facts)) {
-        total += list.length;
-    }
-    if (total <= maxFacts) {
-        return facts;
-    }
-    const sortedTs = Object.keys(facts).sort();
-    for (const ts of sortedTs) {
-        if (total <= maxFacts) {
-            break;
-        }
-        total -= facts[ts].length;
-        delete facts[ts];
-    }
-    return facts;
-}
-/** Extracts assistant/output text from newly appended items for buffering. */
-function collectText(newItems) {
-    return newItems
-        .filter((i) => i.type === 'message')
-        .map((i) => i.content
-        .filter(isOutputText)
-        .map((c) => c.text)
-        .join(''))
-        .filter((t) => t.length > 0);
-}
-//#endregion
-//#region Layer
-/**
- * A non-atomic, LLM-backed memory layer that extracts timestamped facts from the
- * conversation into a key-value ledger (key = ISO timestamp) and exposes a
- * `temporal/searchMemory` tool for relative-time recall — given a fact/query it
- * returns matching facts and, when applicable, a resolved (possibly fuzzy) date.
- *
- * The layer is LLM-agnostic: the host injects `extract` and `search` callbacks
- * (mirrors `observationalMemory`'s `observer`), keeping `memory/` tree-shakable.
- * Without them, the layer still buffers text and the search tool returns the raw
- * ledger — it never fabricates facts. A `<current_datetime>` grounding block is
- * injected on recall by default to anchor relative-time reasoning.
- *
- * @public
- * @param config - Clock, scope, injected LLM callbacks, and tuning knobs.
- * @returns A `MemoryLayer` with a fact-ledger store + `searchMemory` tool.
- */
-export function temporalMemory(config) {
-    const now = config?.now ?? (() => new Date());
-    const threshold = config?.bufferThreshold ?? DEFAULT_BUFFER_THRESHOLD_TOKENS;
-    const maxFacts = config?.maxFacts ?? DEFAULT_MAX_FACTS;
-    const groundDateTime = config?.groundDateTime ?? true;
-    const injectLedger = config?.injectLedger ?? false;
-    const extract = config?.extract;
-    const search = config?.search;
-    return {
-        id: 'temporal',
-        name: 'Temporal Memory',
-        // Grounding sits near the top of the window, before reasoning content.
-        slot: Slot.REMINDER,
-        scope: config?.scope ?? 'resource',
-        budget: {
-            min: 0,
-            max: injectLedger ? 800 : 200,
-        },
-        timeouts: {
-            store: 60_000,
-        },
-        provides: {
-            searchMemory: layerFn({
-                description: 'Search remembered facts about the user by topic or fact, and resolve relative time. Returns matching facts and, when the query implies a time, a resolved date (which may be approximate).',
-                input: z.object({
-                    query: z.string(),
-                }),
-                output: z.object({
-                    facts: z.array(z.string()),
-                    date: z.string().optional(),
-                    fuzzy: z.boolean().optional(),
-                }),
-                execute: async (args, state) => {
-                    const facts = ledgerToFacts(state ?? emptyState());
-                    if (!search) {
-                        return {
-                            result: {
-                                facts: facts.map((f) => `[${f.ts}] ${f.fact}`),
-                            },
-                        };
-                    }
-                    const result = await search({
-                        query: args.query,
-                        facts,
-                        now: formatNow(now()),
-                    });
-                    return {
-                        result,
-                    };
-                },
-            }),
-        },
-        hooks: {
-            async init({ storage }) {
-                const saved = await storage.get('state');
-                return {
-                    state: saved ?? emptyState(),
-                };
-            },
-            async recall({ state }) {
-                const blocks = [];
-                if (groundDateTime) {
-                    blocks.push(renderDateTimeBlock(now()));
-                }
-                if (injectLedger) {
-                    const facts = ledgerToFacts(state ?? emptyState());
-                    if (facts.length > 0) {
-                        const lines = facts.map((f) => `- [${f.ts}] ${f.fact}`).join('\n');
-                        blocks.push(`<remembered_facts>\n${lines}\n</remembered_facts>`);
-                    }
-                }
-                if (blocks.length === 0) {
-                    return null;
-                }
-                const text = blocks.join('\n\n');
-                return {
-                    items: [
-                        createMessage(text, 'developer'),
-                    ],
-                    tokenCount: estimateTokens(text),
-                };
-            },
-            async store({ newItems, state }) {
-                const s = state ?? emptyState();
-                const texts = collectText(newItems);
-                const newBuffer = [
-                    ...s.buffer,
-                    ...texts,
-                ];
-                const newTokens = texts.reduce((sum, t) => sum + estimateTokens(t), 0);
-                const totalBufferTokens = s.bufferTokens + newTokens;
-                if (extract && totalBufferTokens >= threshold && newBuffer.length > 0) {
-                    const extracted = await extract({
-                        transcript: newBuffer.join('\n'),
-                        now: formatNow(now()),
-                    });
-                    return {
-                        state: {
-                            facts: mergeFacts(s, extracted, maxFacts),
-                            buffer: [],
-                            bufferTokens: 0,
-                            version: s.version + 1,
-                        },
-                    };
-                }
-                return {
-                    state: {
-                        ...s,
-                        buffer: newBuffer,
-                        bufferTokens: totalBufferTokens,
-                    },
-                };
-            },
-            async onSpawn({ parentState }) {
-                return {
-                    childState: structuredClone(parentState),
-                };
-            },
-        },
-    };
-}
-//#endregion

package/dist/memory/layers/tool-memory-layer.d.ts

@@ -1,16 +0,0 @@
-import type { MemoryLayer } from '../../types/memory.js';
-import type { Tool } from '../../types/tool.js';
-interface ToolMemoryLayerOpts {
-    slot?: number;
-}
-/**
- * Generates one MemoryLayer per unique memory id among the provided tools.
- * Tools sharing the same `memory.id` share a single layer (and thus state).
- *
- * @public
- * @param tools - Array of tools to extract memory declarations from.
- * @param opts - Optional slot override for the generated layers.
- * @returns An array of `MemoryLayer` instances, one per unique tool memory id.
- */
-export declare function toolMemoryLayer(tools: ReadonlyArray<Tool>, opts?: ToolMemoryLayerOpts): MemoryLayer[];
-export {};

package/dist/memory/layers/tool-memory-layer.js

@@ -1,43 +0,0 @@
-import { Slot } from '../../types/memory.js';
-const EXECUTION_SCOPE = 'execution';
-/**
- * Generates one MemoryLayer per unique memory id among the provided tools.
- * Tools sharing the same `memory.id` share a single layer (and thus state).
- *
- * @public
- * @param tools - Array of tools to extract memory declarations from.
- * @param opts - Optional slot override for the generated layers.
- * @returns An array of `MemoryLayer` instances, one per unique tool memory id.
- */
-export function toolMemoryLayer(tools, opts) {
-    const seen = new Map();
-    for (const t of tools) {
-        if (!t.memory) {
-            continue;
-        }
-        const memId = t.memory.id ?? t.name;
-        if (seen.has(memId)) {
-            continue;
-        }
-        seen.set(memId, t.memory);
-    }
-    const slot = opts?.slot ?? Slot.WORKING_MEMORY + 10;
-    return [
-        ...seen.entries(),
-    ].map(([memId, decl]) => ({
-        id: memId,
-        name: memId,
-        slot,
-        scope: EXECUTION_SCOPE,
-        hooks: {
-            async init() {
-                return {
-                    state: decl.init(),
-                };
-            },
-            async recall({ state }) {
-                return decl.recall(state);
-            },
-        },
-    }));
-}

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

@@ -1,44 +0,0 @@
-import type { ZodType } from 'zod';
-export type WorkingMemoryState = string | Record<string, unknown>;
-export interface WorkingMemoryConfig {
-    scope?: 'thread' | 'resource';
-    schema?: ZodType;
-    template?: string;
-    readOnly?: boolean;
-}
-/**
- * Creates a mutable working memory layer that the model can update via the `working-memory/update` tool.
- *
- * @public
- * @param config - Optional configuration for scope, Zod schema, template, and read-only mode.
- * @returns A `MemoryLayer` providing scratchpad state the model can read and write.
- */
-export declare function workingMemory(config?: WorkingMemoryConfig): {
-    id: "working-memory";
-    name: string;
-    slot: 100;
-    scope: "thread" | "resource";
-    budget: {
-        min: number;
-        max: number;
-    };
-    provides: {
-        snapshot: import("../../index.js").LayerDataDecl<WorkingMemoryState, WorkingMemoryState>;
-        update: import("../../index.js").LayerFunctionDecl<Record<string, unknown>, void, WorkingMemoryState>;
-    };
-    hooks: {
-        init({ storage }: import("../../index.js").InitParams): Promise<{
-            state: WorkingMemoryState;
-        }>;
-        recall({ state }: import("../../index.js").RecallParams<WorkingMemoryState>): Promise<{
-            items: import("../../index.js").InputMessageItem[];
-            tokenCount: number;
-        } | null>;
-        store({ newItems, state }: import("../../index.js").StoreParams<WorkingMemoryState>): Promise<{
-            state: WorkingMemoryState;
-        } | undefined>;
-        onSpawn({ parentState }: import("../../index.js").SpawnParams<WorkingMemoryState>): Promise<{
-            childState: WorkingMemoryState;
-        } | null>;
-    };
-};