@noetic-tools/context 1.0.0

package/dist/context/layers/static-content.d.ts

@@ -0,0 +1,27 @@
+import type { ContextScope } from '@noetic-tools/types';
+interface StaticContentOpts {
+    id?: string;
+    slot?: number;
+    scope?: ContextScope;
+    load: () => Promise<string>;
+    tag?: string;
+}
+/**
+ * Creates a read-only context layer that loads static content once at init and injects it into recall.
+ *
+ * @public
+ * @param opts - Configuration with a `load` function and optional id, slot, scope, and XML tag name.
+ * @returns A `ContextLayer` that provides static instructional content to the model.
+ */
+export declare function staticContent(opts: StaticContentOpts): {
+    id: string;
+    slot: number;
+    scope: ContextScope;
+    hooks: {
+        init(): Promise<{
+            state: string;
+        }>;
+        recall({ state, budget }: import("@noetic-tools/types").RecallParams<string>): Promise<string | null>;
+    };
+};
+export {};

package/dist/context/layers/static-content.js

@@ -0,0 +1,46 @@
+import { estimateTokens, Slot } from '@noetic-tools/types';
+/**
+ * Creates a read-only context layer that loads static content once at init and injects it into recall.
+ *
+ * @public
+ * @param opts - Configuration with a `load` function and optional id, slot, scope, and XML tag name.
+ * @returns A `ContextLayer` that provides static instructional content to the model.
+ */
+export function staticContent(opts) {
+    const tag = opts.tag ?? 'instructions';
+    return {
+        id: opts.id ?? 'static-content',
+        slot: opts.slot ?? Slot.WORKING_MEMORY + 5,
+        scope: opts.scope ?? 'resource',
+        hooks: {
+            async init() {
+                const raw = await opts.load();
+                if (!raw) {
+                    return {
+                        state: '',
+                    };
+                }
+                return {
+                    state: `<${tag}>\n${raw}\n</${tag}>`,
+                };
+            },
+            async recall({ state, budget }) {
+                if (!state) {
+                    return null;
+                }
+                // `budget > 0` is a deliberate fail-open guard: a zero allocation must
+                // not delete the instructions (slice(0, 0) would silently drop the
+                // whole layer from the view).
+                if (budget > 0 && estimateTokens(state) > budget) {
+                    // Trim so the recalled text fits the token budget (~4 chars/token),
+                    // reserving room for the closing tag so the block stays well-formed
+                    // XML instead of being cut mid-tag/mid-sentence.
+                    const closing = `\n</${tag}>`;
+                    const maxChars = Math.max(0, budget * 4 - closing.length);
+                    return `${state.slice(0, maxChars)}${closing}`;
+                }
+                return state;
+            },
+        },
+    };
+}

package/dist/context/layers/steering.d.ts

@@ -0,0 +1,50 @@
+import type { AfterModelCallParams, BeforeToolCallParams, ContextScope, LedgerEntry, SteeringConfig, SteeringDecision, SteeringState } from '@noetic-tools/types';
+/**
+ * Creates a steering context 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 `ContextLayer` that enforces steering rules via allow/deny/guide decisions.
+ */
+export declare function steering(config: SteeringConfig): {
+    id: 'steering';
+    name: string;
+    slot: 90;
+    scope: ContextScope;
+    budget: {
+        min: number;
+        max: number;
+    };
+    timeouts: {
+        beforeToolCall: number;
+        afterModelCall: number;
+    };
+    hooks: {
+        init({ storage }: import("@noetic-tools/types").InitParams): Promise<{
+            state: SteeringState;
+        }>;
+        recall({ state }: import("@noetic-tools/types").RecallParams<SteeringState>): Promise<{
+            items: import("@noetic-tools/types").InputMessageItem[];
+            tokenCount: number;
+            state: SteeringState;
+        } | null>;
+        store(): Promise<undefined>;
+        beforeToolCall({ toolName, toolArgs, ctx, state }: BeforeToolCallParams<SteeringState>): Promise<{
+            decision: SteeringDecision;
+            state: SteeringState;
+        }>;
+        afterModelCall({ response, ctx, state }: AfterModelCallParams<SteeringState>): Promise<{
+            decision: SteeringDecision;
+            state: SteeringState;
+        }>;
+        onSpawn({ parentState }: import("@noetic-tools/types").SpawnParams<SteeringState>): Promise<{
+            childState: {
+                ledger: LedgerEntry[];
+                pendingAsync: never[];
+            };
+        }>;
+        onComplete({ state, outcome }: import("@noetic-tools/types").CompleteParams<SteeringState>): Promise<{
+            state: SteeringState;
+        }>;
+    };
+};

package/dist/context/layers/steering.js

@@ -0,0 +1,291 @@
+import { createMessage, estimateTokens, extractAssistantText, LedgerEntryKind, NoeticConfigError, Slot, SteeringAction, } from '@noetic-tools/types';
+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);
+}
+/**
+ * Parse an LLM steering verdict. Returns `null` when the output is unparseable
+ * (neither ALLOW/DENY/GUIDE) so the caller can retry. The verdict keyword is
+ * matched case-insensitively, but the guidance text is preserved verbatim.
+ */
+function parseLlmVerdict(raw) {
+    const text = raw.trim();
+    // Match the verdict keyword on a word boundary (so "DENYALL" is NOT a DENY),
+    // case-insensitively, but keep the guidance text's original casing.
+    if (/^ALLOW\b/i.test(text)) {
+        return {
+            action: SteeringAction.Allow,
+        };
+    }
+    if (/^DENY\b/i.test(text)) {
+        return {
+            action: SteeringAction.Deny,
+            guidance: text
+                .slice(4)
+                .replace(/^[:\s]+/, '')
+                .trim() || undefined,
+        };
+    }
+    if (/^GUIDE\b/i.test(text)) {
+        return {
+            action: SteeringAction.Guide,
+            guidance: text
+                .slice(5)
+                .replace(/^[:\s]+/, '')
+                .trim() || undefined,
+        };
+    }
+    return null;
+}
+async function evaluateLlmRuleSync(rule, params, maxRetries) {
+    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';
+    // Retry on unparseable output up to maxRetries; treat as pass on exhaustion.
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const response = await callModel({
+            model,
+            items: [
+                userMessage,
+            ],
+        });
+        const verdict = parseLlmVerdict(extractAssistantText(response.items));
+        if (verdict) {
+            return verdict;
+        }
+    }
+    return {
+        action: SteeringAction.Allow,
+    };
+}
+function fireLlmRuleAsync({ rule, params, pendingAsync, maxRetries, }) {
+    evaluateLlmRuleSync(rule, params, maxRetries)
+        .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, maxRetries, }) {
+    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, maxRetries);
+            decisions.push(decision);
+            if (decision.action === SteeringAction.Deny) {
+                return mostRestrictive(decisions);
+            }
+            continue;
+        }
+        // Async — fire and forget
+        fireLlmRuleAsync({
+            rule,
+            params,
+            pendingAsync: state.pendingAsync,
+            maxRetries,
+        });
+    }
+    return mostRestrictive(decisions);
+}
+//#endregion
+//#region Public API
+/**
+ * Creates a steering context 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 `ContextLayer` that enforces steering rules via allow/deny/guide decisions.
+ */
+export function steering(config) {
+    const maxLedger = config.maxLedgerEntries ?? DEFAULT_MAX_LEDGER_ENTRIES;
+    const maxRetries = config.maxRetries ?? 1;
+    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;
+                }
+                // Drain IN PLACE (splice, not reassignment): in-flight async LLM rules
+                // hold this array by reference (fireLlmRuleAsync) — replacing it would
+                // orphan their late verdicts. Late pushes land in the live array and
+                // surface on the next recall.
+                const drained = state.pendingAsync.splice(0, state.pendingAsync.length);
+                const feedback = drained.map((p) => `[${p.ruleId}] ${p.guidance}`).join('\n');
+                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,
+                    maxRetries,
+                });
+                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,
+                    maxRetries,
+                });
+                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/context/layers/temporal-context.d.ts

@@ -0,0 +1,91 @@
+import type { ContextLayer, ContextScope } from '@noetic-tools/types';
+/**
+ * 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 fact 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 `observationalContext`'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 temporalContext}.
+ * @public
+ */
+export interface TemporalContextConfig {
+    /** Returns "now" for date grounding/extraction. Defaults to the system clock. */
+    now?: () => Date;
+    /** Context scope. Defaults to `'resource'` (long-term, cross-session). */
+    scope?: ContextScope;
+    /** 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 context 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 `observationalContext`'s `observer`), keeping `context/` 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 `ContextLayer` with a fact-ledger store + `searchMemory` tool.
+ */
+export declare function temporalContext(config?: TemporalContextConfig): ContextLayer<TemporalState>;
+export {};