@noetic-tools/core 0.0.1

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

@@ -0,0 +1,51 @@
+import type { MemoryScope } from '../../types/memory';
+import type { AfterModelCallParams, BeforeToolCallParams, LedgerEntry, SteeringConfig, SteeringDecision, SteeringState } from '../../types/steering';
+/**
+ * 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 declare function steering(config: SteeringConfig): {
+    id: "steering";
+    name: string;
+    slot: 90;
+    scope: MemoryScope;
+    budget: {
+        min: number;
+        max: number;
+    };
+    timeouts: {
+        beforeToolCall: number;
+        afterModelCall: number;
+    };
+    hooks: {
+        init({ storage }: import("../..").InitParams): Promise<{
+            state: SteeringState;
+        }>;
+        recall({ state }: import("../..").RecallParams<SteeringState>): Promise<{
+            items: import("../..").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("../..").SpawnParams<SteeringState>): Promise<{
+            childState: {
+                ledger: LedgerEntry[];
+                pendingAsync: never[];
+            };
+        }>;
+        onComplete({ state, outcome }: import("../..").CompleteParams<SteeringState>): Promise<{
+            state: SteeringState;
+        }>;
+    };
+};

package/dist/memory/layers/steering.js

@@ -0,0 +1,258 @@
+import { NoeticConfigError } from '../../errors/noetic-config-error';
+import { createMessage, estimateTokens, extractAssistantText, } from '../../interpreter/message-helpers';
+import { Slot } from '../../types/memory';
+import { LedgerEntryKind, SteeringAction } from '../../types/steering';
+import { mostRestrictive } from '../layer-lifecycle';
+//#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/tool-memory-layer.d.ts

@@ -0,0 +1,16 @@
+import type { Tool } from '../../types/common';
+import type { MemoryLayer } from '../../types/memory';
+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

@@ -0,0 +1,43 @@
+import { Slot } from '../../types/memory';
+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

@@ -0,0 +1,44 @@
+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("../..").LayerDataDecl<WorkingMemoryState, WorkingMemoryState>;
+        update: import("../..").LayerFunctionDecl<Record<string, unknown>, void, WorkingMemoryState>;
+    };
+    hooks: {
+        init({ storage }: import("../..").InitParams): Promise<{
+            state: WorkingMemoryState;
+        }>;
+        recall({ state }: import("../..").RecallParams<WorkingMemoryState>): Promise<{
+            items: import("../..").InputMessageItem[];
+            tokenCount: number;
+        } | null>;
+        store({ newItems, state }: import("../..").StoreParams<WorkingMemoryState>): Promise<{
+            state: WorkingMemoryState;
+        } | undefined>;
+        onSpawn({ parentState }: import("../..").SpawnParams<WorkingMemoryState>): Promise<{
+            childState: WorkingMemoryState;
+        } | null>;
+    };
+};

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

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { layerData, layerFn } from '../../builders/layer-provides-builders';
+import { createMessage, estimateTokens } from '../../interpreter/message-helpers';
+import { Slot } from '../../types/memory';
+import { findFunctionCall } from '../function-call-utils';
+function safeMerge(state, args) {
+    const { __proto__: _p, constructor: _c, ...safeArgs } = args;
+    if (typeof state === 'object' && state !== null) {
+        return {
+            ...state,
+            ...safeArgs,
+        };
+    }
+    return safeArgs;
+}
+/**
+ * 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 function workingMemory(config) {
+    const scope = config?.scope ?? 'thread';
+    return {
+        id: 'working-memory',
+        name: 'Working Memory',
+        slot: Slot.WORKING_MEMORY,
+        scope,
+        budget: {
+            min: 200,
+            max: 1_500,
+        },
+        provides: {
+            snapshot: layerData({
+                read: (state) => state,
+            }),
+            update: layerFn({
+                description: 'Update the agent working memory with new key-value pairs.',
+                input: z.record(z.string(), z.unknown()),
+                output: z.void(),
+                execute: async (args, state) => ({
+                    result: undefined,
+                    state: safeMerge(state, args),
+                }),
+            }),
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                const state = saved ?? (config?.schema ? {} : '');
+                return {
+                    state,
+                };
+            },
+            async recall({ state }) {
+                if (!state || (typeof state === 'object' && Object.keys(state).length === 0)) {
+                    return null;
+                }
+                const text = typeof state === 'string' ? state : JSON.stringify(state, null, 2);
+                const content = `<working_memory>\n${text}\n</working_memory>`;
+                return {
+                    items: [
+                        createMessage(content, 'developer'),
+                    ],
+                    tokenCount: estimateTokens(content),
+                };
+            },
+            async store({ newItems, state }) {
+                if (config?.readOnly) {
+                    return;
+                }
+                // Backward compat: detect implicit updateWorkingMemory calls from LLMs
+                const args = findFunctionCall(newItems, 'updateWorkingMemory');
+                if (!args) {
+                    return;
+                }
+                return {
+                    state: safeMerge(state, args),
+                };
+            },
+            async onSpawn({ parentState }) {
+                if (scope === 'resource') {
+                    return {
+                        childState: structuredClone(parentState),
+                    };
+                }
+                return null;
+            },
+        },
+    };
+}

package/dist/memory/projector.d.ts

@@ -0,0 +1,10 @@
+import type { Item } from '../types/items';
+import type { ProjectionPolicy } from '../types/memory';
+interface AssembleViewParams {
+    systemPromptItems: Item[];
+    layerOutputItems: Item[];
+    historyItems: Item[];
+    policy?: ProjectionPolicy;
+}
+export declare function assembleView({ systemPromptItems, layerOutputItems, historyItems, policy, }: AssembleViewParams): Item[];
+export {};

package/dist/memory/projector.js

@@ -0,0 +1,19 @@
+//#endregion
+//#region Public API
+export function assembleView({ systemPromptItems, layerOutputItems, historyItems, policy, }) {
+    const view = [];
+    // Add system prompt items
+    view.push(...systemPromptItems);
+    // Add layer output items (sorted by slot already from recall)
+    view.push(...layerOutputItems);
+    // Add history items (with overflow handling if policy specified)
+    if (policy?.overflow === 'sliding_window' && policy.windowSize) {
+        const windowItems = historyItems.slice(-policy.windowSize);
+        view.push(...windowItems);
+    }
+    else {
+        view.push(...historyItems);
+    }
+    return view;
+}
+//#endregion

package/dist/memory/scope.d.ts

@@ -0,0 +1,3 @@
+import type { ExecutionContext, MemoryScope, ScopedStorage, StorageAdapter } from '../types/memory';
+export declare function resolveScopeKey(scope: MemoryScope, ctx: ExecutionContext): string;
+export declare function createScopedStorage(storage: StorageAdapter, layerId: string, scopeKey: string): ScopedStorage;

package/dist/memory/scope.js

@@ -0,0 +1,31 @@
+export function resolveScopeKey(scope, ctx) {
+    switch (scope) {
+        case 'thread':
+            return ctx.threadId;
+        case 'resource':
+            return ctx.resourceId ?? ctx.threadId;
+        case 'global':
+            return '__global__';
+        case 'execution':
+            return ctx.executionId;
+    }
+}
+export function createScopedStorage(storage, layerId, scopeKey) {
+    const prefix = `layers/${layerId}/${scopeKey}/`;
+    return {
+        async get(key) {
+            return storage.get(`${prefix}${key}`);
+        },
+        async set(key, value) {
+            return storage.set(`${prefix}${key}`, value);
+        },
+        async delete(key) {
+            return storage.delete(`${prefix}${key}`);
+        },
+        async list(keyPrefix) {
+            const fullPrefix = keyPrefix ? `${prefix}${keyPrefix}` : prefix;
+            const keys = await storage.list(fullPrefix);
+            return keys.map((k) => (k.startsWith(prefix) ? k.slice(prefix.length) : k));
+        },
+    };
+}

package/dist/memory/strip-unresolved.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Drop dangling tool-call state from an item list. A `function_call` without a
+ * matching `function_call_output` (or vice-versa) wedges the model on the next
+ * round (it typically fabricates an output), so we filter both sides of any
+ * incomplete pair. Order-preserving and pure — safe to run after a slice.
+ *
+ * Mirrors Claude Code's `filterUnresolvedToolUses`. Used by the CLI's
+ * session-resume path to drop dangling pairs left by a crash, and by the
+ * `historyWindow` memory layer to clean orphans at the slice boundary.
+ */
+import type { Item } from '../types/items';
+/** @public */
+export declare function stripUnresolvedToolCalls(items: ReadonlyArray<Item>): Item[];

package/dist/memory/strip-unresolved.js

@@ -0,0 +1,35 @@
+/**
+ * Drop dangling tool-call state from an item list. A `function_call` without a
+ * matching `function_call_output` (or vice-versa) wedges the model on the next
+ * round (it typically fabricates an output), so we filter both sides of any
+ * incomplete pair. Order-preserving and pure — safe to run after a slice.
+ *
+ * Mirrors Claude Code's `filterUnresolvedToolUses`. Used by the CLI's
+ * session-resume path to drop dangling pairs left by a crash, and by the
+ * `historyWindow` memory layer to clean orphans at the slice boundary.
+ */
+/** @public */
+export function stripUnresolvedToolCalls(items) {
+    const outputCallIds = new Set();
+    const callCallIds = new Set();
+    for (const item of items) {
+        if (item.type === 'function_call_output') {
+            outputCallIds.add(item.callId);
+            continue;
+        }
+        if (item.type === 'function_call') {
+            callCallIds.add(item.callId);
+        }
+    }
+    const keep = [];
+    for (const item of items) {
+        if (item.type === 'function_call' && !outputCallIds.has(item.callId)) {
+            continue;
+        }
+        if (item.type === 'function_call_output' && !callCallIds.has(item.callId)) {
+            continue;
+        }
+        keep.push(item);
+    }
+    return keep;
+}

package/dist/observability/genai-attributes.d.ts

@@ -0,0 +1,11 @@
+export declare const GenAI: {
+    readonly SYSTEM: "gen_ai.system";
+    readonly REQUEST_MODEL: "gen_ai.request.model";
+    readonly USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens";
+    readonly USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens";
+    readonly COST: "gen_ai.cost";
+};
+export declare const ToolAttr: {
+    readonly NAME: "tool.name";
+    readonly NEEDS_APPROVAL: "tool.needs_approval";
+};

package/dist/observability/genai-attributes.js

@@ -0,0 +1,12 @@
+// GenAI Semantic Convention attributes
+export const GenAI = {
+    SYSTEM: 'gen_ai.system',
+    REQUEST_MODEL: 'gen_ai.request.model',
+    USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens',
+    USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens',
+    COST: 'gen_ai.cost',
+};
+export const ToolAttr = {
+    NAME: 'tool.name',
+    NEEDS_APPROVAL: 'tool.needs_approval',
+};

package/dist/observability/span-impl.d.ts

@@ -0,0 +1,20 @@
+import type { Span } from '../types/observability';
+export declare class SpanImpl implements Span {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId: string | null;
+    readonly name: string;
+    readonly startTime: number;
+    endTime?: number;
+    readonly attributes: Map<string, string | number | boolean>;
+    readonly events: Array<{
+        name: string;
+        timestamp: number;
+        attributes?: Record<string, string | number | boolean>;
+    }>;
+    constructor(name: string, parent: Span | null, traceId?: string);
+    setAttribute(key: string, value: string | number | boolean): void;
+    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    end(): void;
+    get duration(): number;
+}