@noetic-tools/core 0.2.1 → 1.0.0

package/dist/memory/budget.js

@@ -1,117 +0,0 @@
-import { NoeticErrorImpl } from '../errors/noetic-error.js';
-function extractMin(config) {
-    if (config && typeof config === 'object' && 'min' in config) {
-        return config.min;
-    }
-    return 0;
-}
-function extractMax(config) {
-    if (config === 'auto') {
-        return Number.POSITIVE_INFINITY;
-    }
-    if (typeof config === 'number') {
-        return config;
-    }
-    if (config && typeof config === 'object' && 'min' in config) {
-        return config.max;
-    }
-    return 0;
-}
-function computeShare({ headroom, layerPool, infiniteCount, finiteTotal, totalMax, allHeadrooms, layerIndex, }) {
-    if (!Number.isFinite(headroom)) {
-        // All infinite-headroom layers split the pool after finite layers take their share.
-        // `infiniteCount >= 1` is guaranteed here since headroom is infinite.
-        const finiteUsed = Number.isFinite(totalMax)
-            ? 0
-            : allHeadrooms.reduce((sum, m, j) => Number.isFinite(m) && j !== layerIndex
-                ? sum + Math.min(m, (m / (finiteTotal || 1)) * layerPool)
-                : sum, 0);
-        return (layerPool - finiteUsed) / infiniteCount;
-    }
-    if (Number.isFinite(totalMax)) {
-        return (headroom / totalMax) * layerPool;
-    }
-    // Mix of finite and infinite: finite layers share half the pool proportionally.
-    return finiteTotal > 0 ? (headroom / finiteTotal) * (layerPool * 0.5) : 0;
-}
-export function allocateBudgets({ layers, totalBudget, systemPromptTokens, responseReserve, }) {
-    const available = totalBudget - responseReserve - systemPromptTokens;
-    if (available <= 0) {
-        return {
-            allocations: layers.map((l) => ({
-                layerId: l.id,
-                allocated: 0,
-            })),
-            historyBudget: 0,
-        };
-    }
-    // Phase 1: satisfy minimums
-    let remaining = available;
-    const allocations = [];
-    for (const layer of layers) {
-        const min = extractMin(layer.budget);
-        allocations.push({
-            layerId: layer.id,
-            allocated: min,
-        });
-        remaining -= min;
-    }
-    // Phase 2: distribute 60% of remaining to layers proportionally, 40% to history
-    const layerPool = remaining * 0.6;
-    const historyBudget = remaining * 0.4;
-    // Compute headroom per layer (how much above the minimum each layer can absorb)
-    let totalMax = 0;
-    const headrooms = [];
-    for (let i = 0; i < layers.length; i++) {
-        const max = extractMax(layers[i].budget);
-        const headroom = Math.max(0, max - allocations[i].allocated);
-        headrooms.push(headroom);
-        totalMax += headroom;
-    }
-    if (totalMax > 0) {
-        const infiniteCount = headrooms.filter((h) => !Number.isFinite(h)).length;
-        const finiteTotal = headrooms.reduce((sum, h) => (Number.isFinite(h) ? sum + h : sum), 0);
-        for (let i = 0; i < headrooms.length; i++) {
-            const share = computeShare({
-                headroom: headrooms[i],
-                layerPool,
-                infiniteCount,
-                finiteTotal,
-                totalMax,
-                allHeadrooms: headrooms,
-                layerIndex: i,
-            });
-            allocations[i].allocated += Math.min(share, headrooms[i]);
-        }
-    }
-    return {
-        allocations,
-        historyBudget: Math.max(0, historyBudget),
-    };
-}
-export function checkBudget(ctx, limits) {
-    if (limits.maxCost !== undefined && ctx.cost > limits.maxCost) {
-        throw new NoeticErrorImpl({
-            kind: 'budget_exceeded',
-            field: 'cost',
-            limit: limits.maxCost,
-            actual: ctx.cost,
-        });
-    }
-    if (limits.maxSteps !== undefined && ctx.stepCount > limits.maxSteps) {
-        throw new NoeticErrorImpl({
-            kind: 'budget_exceeded',
-            field: 'steps',
-            limit: limits.maxSteps,
-            actual: ctx.stepCount,
-        });
-    }
-    if (limits.maxDuration !== undefined && ctx.elapsed > limits.maxDuration) {
-        throw new NoeticErrorImpl({
-            kind: 'budget_exceeded',
-            field: 'duration',
-            limit: limits.maxDuration,
-            actual: ctx.elapsed,
-        });
-    }
-}

package/dist/memory/exec-context-factory.d.ts

@@ -1,25 +0,0 @@
-import type { Context } from '../types/context.js';
-import type { ExecutionContext } from '../types/memory.js';
-/**
- * Optional overrides for `contextToExecCtx`. Used by `executeSpawn` to build
- * parent and child execution contexts that reuse the same tokenize / trace /
- * layer-state wiring as the main path, but with spawn-specific identity
- * (`executionId`, `depth`, `stepNumber`, and the scope used for layer-state
- * reads).
- */
-export interface ExecCtxOverrides {
-    callModel?: ExecutionContext['callModel'];
-    executionId?: string;
-    depth?: number;
-    stepNumber?: number;
-    tokenUsage?: ExecutionContext['tokenUsage'];
-    cost?: number;
-    /** Execution id to scope `readLayerState` to (defaults to `ctx.id`). */
-    readLayerStateId?: string;
-}
-/**
- * Maps a full `Context` to the lightweight `ExecutionContext` consumed by memory layer hooks.
- * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the
- * spawn interpreter.
- */
-export declare function contextToExecCtx(ctx: Context, overrides?: ExecCtxOverrides): ExecutionContext;

package/dist/memory/exec-context-factory.js

@@ -1,30 +0,0 @@
-import { estimateTokens } from '../util/message-helpers.js';
-/**
- * Maps a full `Context` to the lightweight `ExecutionContext` consumed by memory layer hooks.
- * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the
- * spawn interpreter.
- */
-export function contextToExecCtx(ctx, overrides) {
-    const readLayerStateId = overrides?.readLayerStateId ?? ctx.id;
-    return {
-        executionId: overrides?.executionId ?? ctx.id,
-        threadId: ctx.threadId,
-        resourceId: ctx.resourceId,
-        depth: overrides?.depth ?? ctx.depth,
-        stepNumber: overrides?.stepNumber ?? ctx.stepCount,
-        tokenUsage: overrides?.tokenUsage ?? {
-            input: ctx.tokens.input,
-            output: ctx.tokens.output,
-        },
-        cost: overrides?.cost ?? ctx.cost,
-        fs: ctx.harness.fs,
-        shell: ctx.harness.shell,
-        callModel: overrides?.callModel,
-        tokenize: estimateTokens,
-        trace: {
-            setAttribute: (key, value) => ctx.span.setAttribute(key, value),
-            addEvent: (name, attributes) => ctx.span.addEvent(name, attributes),
-        },
-        readLayerState: (layerId) => ctx.harness.getLayerState(readLayerStateId, layerId),
-    };
-}

package/dist/memory/flow-schema.d.ts

@@ -1,52 +0,0 @@
-/**
- * Zod schema for plan-mode flow JSON.
- *
- * A "flow" is a JSON-serialisable subset of noetic's `Step` shape that the model
- * may emit during plan mode. The runtime expands each node into a concrete `Step`
- * via the existing builders (`step.llm`, `fork`, `spawn`) at execute time.
- *
- * Tool references inside `llm` nodes are name strings. They get resolved against
- * the harness's live tool registry when the flow runs.
- */
-import { z } from 'zod';
-interface NodeBase {
-    id: string;
-    subPlanRef?: string;
-}
-export interface LlmFlowNode extends NodeBase {
-    kind: 'llm';
-    model?: string;
-    instructions: string;
-    tools?: string[];
-}
-export interface SubagentFlowNode extends NodeBase {
-    kind: 'subagent';
-    preset: string;
-    prompt: string;
-}
-export interface ForkFlowNode extends NodeBase {
-    kind: 'fork';
-    mode: 'all' | 'race' | 'settle';
-    paths: FlowNode[];
-}
-export interface SpawnFlowNode extends NodeBase {
-    kind: 'spawn';
-    child: FlowNode;
-}
-export interface SequenceFlowNode extends NodeBase {
-    kind: 'sequence';
-    steps: FlowNode[];
-}
-export type FlowNode = LlmFlowNode | SubagentFlowNode | ForkFlowNode | SpawnFlowNode | SequenceFlowNode;
-/** Top-level flow document: a single root node. */
-export declare const FlowSchema: z.ZodType<FlowNode, unknown, z.core.$ZodTypeInternals<FlowNode, unknown>>;
-/** Validates a candidate flow document. Throws `ZodError` on invalid input. */
-export declare function validateFlow(input: unknown): FlowNode;
-/** Walks a flow tree depth-first, yielding each node. */
-export declare function walkFlow(root: FlowNode): Iterable<FlowNode>;
-/**
- * Returns the maximum depth of a flow tree. A leaf (llm/subagent) is depth 0.
- * Structural nodes (sequence/fork/spawn) contribute +1 over their deepest child.
- */
-export declare function flowDepth(node: FlowNode): number;
-export {};

package/dist/memory/flow-schema.js

@@ -1,102 +0,0 @@
-/**
- * Zod schema for plan-mode flow JSON.
- *
- * A "flow" is a JSON-serialisable subset of noetic's `Step` shape that the model
- * may emit during plan mode. The runtime expands each node into a concrete `Step`
- * via the existing builders (`step.llm`, `fork`, `spawn`) at execute time.
- *
- * Tool references inside `llm` nodes are name strings. They get resolved against
- * the harness's live tool registry when the flow runs.
- */
-import { z } from 'zod';
-//#endregion
-//#region Schema
-const FlowNodeRef = z.lazy(() => FlowNodeSchema);
-const SHARED_FIELDS = {
-    id: z.string().min(1),
-    subPlanRef: z.string().optional(),
-};
-const LlmNodeSchema = z.object({
-    kind: z.literal('llm'),
-    ...SHARED_FIELDS,
-    model: z.string().optional(),
-    instructions: z.string(),
-    tools: z.array(z.string()).optional(),
-});
-const SubagentNodeSchema = z.object({
-    kind: z.literal('subagent'),
-    ...SHARED_FIELDS,
-    preset: z.string().min(1),
-    prompt: z.string(),
-});
-const ForkNodeSchema = z.object({
-    kind: z.literal('fork'),
-    ...SHARED_FIELDS,
-    mode: z.enum([
-        'all',
-        'race',
-        'settle',
-    ]),
-    paths: z.array(FlowNodeRef).min(1),
-});
-const SpawnNodeSchema = z.object({
-    kind: z.literal('spawn'),
-    ...SHARED_FIELDS,
-    child: FlowNodeRef,
-});
-const SequenceNodeSchema = z.object({
-    kind: z.literal('sequence'),
-    ...SHARED_FIELDS,
-    steps: z.array(FlowNodeRef).min(1),
-});
-const FlowNodeSchema = z.discriminatedUnion('kind', [
-    LlmNodeSchema,
-    SubagentNodeSchema,
-    ForkNodeSchema,
-    SpawnNodeSchema,
-    SequenceNodeSchema,
-]);
-/** Top-level flow document: a single root node. */
-export const FlowSchema = FlowNodeSchema;
-//#endregion
-//#region Public API
-/** Validates a candidate flow document. Throws `ZodError` on invalid input. */
-export function validateFlow(input) {
-    return FlowSchema.parse(input);
-}
-/** Walks a flow tree depth-first, yielding each node. */
-export function* walkFlow(root) {
-    yield root;
-    if (root.kind === 'fork') {
-        for (const path of root.paths) {
-            yield* walkFlow(path);
-        }
-        return;
-    }
-    if (root.kind === 'sequence') {
-        for (const step of root.steps) {
-            yield* walkFlow(step);
-        }
-        return;
-    }
-    if (root.kind === 'spawn') {
-        yield* walkFlow(root.child);
-    }
-}
-/**
- * Returns the maximum depth of a flow tree. A leaf (llm/subagent) is depth 0.
- * Structural nodes (sequence/fork/spawn) contribute +1 over their deepest child.
- */
-export function flowDepth(node) {
-    if (node.kind === 'sequence') {
-        return 1 + Math.max(0, ...node.steps.map(flowDepth));
-    }
-    if (node.kind === 'fork') {
-        return 1 + Math.max(0, ...node.paths.map(flowDepth));
-    }
-    if (node.kind === 'spawn') {
-        return 1 + flowDepth(node.child);
-    }
-    return 0;
-}
-//#endregion

package/dist/memory/function-call-utils.d.ts

@@ -1,6 +0,0 @@
-import type { Item } from '../types/items.js';
-/**
- * Finds the first function_call item matching `name`, parses its JSON arguments,
- * and returns the result as a record. Returns null if no match or invalid data.
- */
-export declare function findFunctionCall(items: ReadonlyArray<Item>, name: string): Record<string, unknown> | null;

package/dist/memory/function-call-utils.js

@@ -1,27 +0,0 @@
-import { frameworkCast } from '../util/framework-cast.js';
-function isFunctionCall(item) {
-    return item.type === 'function_call' && 'callId' in item && 'name' in item;
-}
-/**
- * Finds the first function_call item matching `name`, parses its JSON arguments,
- * and returns the result as a record. Returns null if no match or invalid data.
- */
-export function findFunctionCall(items, name) {
-    for (const item of items) {
-        if (!isFunctionCall(item)) {
-            continue;
-        }
-        if (item.name !== name) {
-            continue;
-        }
-        try {
-            const raw = JSON.parse(item.arguments);
-            if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-                continue;
-            }
-            return frameworkCast(raw);
-        }
-        catch { }
-    }
-    return null;
-}

package/dist/memory/layer-api.d.ts

@@ -1,14 +0,0 @@
-import type { Context } from '../types/context.js';
-import type { ContextMemory, MemoryLayer } from '../types/memory.js';
-import type { AgentHarnessContract } from '../types/runtime.js';
-import type { Tool } from '../types/tool.js';
-/**
- * Build the `ctx.memory` object — a readonly map of layer ID → resolved handle.
- * Handles use getters for data (live reads) and closures for functions (lazy state).
- */
-export declare function buildContextMemory(layers: ReadonlyArray<MemoryLayer>, ctx: Context): ContextMemory;
-/**
- * Collect all `provides` function declarations from active layers and convert them to Tools.
- * Tool names are namespaced as `layerId/functionName`.
- */
-export declare function resolveLayerTools(layers: ReadonlyArray<MemoryLayer>, harness: AgentHarnessContract, ctx: Context): Tool[];

package/dist/memory/layer-api.js

@@ -1,91 +0,0 @@
-import { frameworkCast } from '../util/framework-cast.js';
-import { contextToExecCtx } from './exec-context-factory.js';
-function executeLayerFn(params) {
-    const { fn, args, layerId, harness, ctx } = params;
-    const validated = fn.input.parse(args);
-    const state = harness.getLayerState(ctx.id, layerId);
-    const execCtx = contextToExecCtx(ctx);
-    return fn.execute(validated, state, execCtx).then((outcome) => {
-        if (outcome.state !== undefined) {
-            harness.setLayerState(ctx.id, layerId, outcome.state);
-        }
-        return outcome.result;
-    });
-}
-function buildLayerHandle(layer, ctx) {
-    const provides = layer.provides;
-    if (!provides) {
-        return {};
-    }
-    const handle = {};
-    const harness = ctx.harness;
-    const layerId = layer.id;
-    for (const [name, decl] of Object.entries(provides)) {
-        if (decl.kind === 'data') {
-            Object.defineProperty(handle, name, {
-                get() {
-                    const state = harness.getLayerState(ctx.id, layerId);
-                    return decl.read(state);
-                },
-                enumerable: true,
-            });
-            continue;
-        }
-        handle[name] = (args) => executeLayerFn({
-            fn: decl,
-            args,
-            layerId,
-            harness,
-            ctx,
-        });
-    }
-    return handle;
-}
-//#endregion
-//#region Context Memory
-/**
- * Build the `ctx.memory` object — a readonly map of layer ID → resolved handle.
- * Handles use getters for data (live reads) and closures for functions (lazy state).
- */
-export function buildContextMemory(layers, ctx) {
-    const memory = {};
-    for (const layer of layers) {
-        memory[layer.id] = buildLayerHandle(layer, ctx);
-    }
-    return frameworkCast(memory);
-}
-//#endregion
-//#region Layer Tools Resolution
-/**
- * Collect all `provides` function declarations from active layers and convert them to Tools.
- * Tool names are namespaced as `layerId/functionName`.
- */
-export function resolveLayerTools(layers, harness, ctx) {
-    const tools = [];
-    for (const layer of layers) {
-        if (!layer.provides) {
-            continue;
-        }
-        for (const [name, decl] of Object.entries(layer.provides)) {
-            if (decl.kind !== 'function') {
-                continue;
-            }
-            const layerId = layer.id;
-            tools.push({
-                name: `${layerId}/${name}`,
-                description: decl.description,
-                input: decl.input,
-                output: decl.output,
-                execute: (args, _toolCtx) => executeLayerFn({
-                    fn: decl,
-                    args,
-                    layerId,
-                    harness,
-                    ctx,
-                }),
-            });
-        }
-    }
-    return tools;
-}
-//#endregion

package/dist/memory/layer-lifecycle.d.ts

@@ -1,160 +0,0 @@
-import type { ItemSchemaRegistry } from '../schemas/item.js';
-import type { LLMResponse } from '../types/common.js';
-import type { ItemLog } from '../types/context-parts/item-log.js';
-import type { Item } from '../types/items.js';
-import type { ExecutionContext, MemoryLayer, StorageAdapter } from '../types/memory.js';
-import type { SteeringDecision } from '../types/steering.js';
-export interface LayerStateStore {
-    get<T>(executionId: string, layerId: string): T | undefined;
-    set<T>(executionId: string, layerId: string, state: T): void;
-    cleanup(executionId: string): void;
-    diagnostic: (layerId: string, hook: string, error: unknown) => void;
-}
-interface InitLayersParams {
-    layers: MemoryLayer[];
-    ctx: ExecutionContext;
-    storage: StorageAdapter;
-    store: LayerStateStore;
-}
-interface RecallLayersParams {
-    layers: MemoryLayer[];
-    query: string;
-    ctx: ExecutionContext;
-    log: ItemLog;
-    budgets: Map<string, number>;
-    store: LayerStateStore;
-    itemSchemas?: ItemSchemaRegistry;
-}
-interface StoreLayersParams {
-    layers: MemoryLayer[];
-    response: LLMResponse;
-    ctx: ExecutionContext;
-    log: ItemLog;
-    store: LayerStateStore;
-    storage: StorageAdapter;
-}
-interface SpawnLayersParams {
-    layers: MemoryLayer[];
-    parentCtx: ExecutionContext;
-    childCtx: ExecutionContext;
-    store: LayerStateStore;
-    itemSchemas?: ItemSchemaRegistry;
-}
-interface ReturnLayersParams<T = unknown> {
-    layers: MemoryLayer[];
-    parentCtx: ExecutionContext;
-    childCtx: ExecutionContext;
-    childLog: ItemLog;
-    result: T;
-    store: LayerStateStore;
-}
-interface CompleteLayersParams {
-    layers: MemoryLayer[];
-    ctx: ExecutionContext;
-    log: ItemLog;
-    outcome: 'success' | 'failure' | 'aborted';
-    store: LayerStateStore;
-}
-interface DisposeLayersParams {
-    layers: MemoryLayer[];
-    ctx: ExecutionContext;
-    store: LayerStateStore;
-}
-interface BeforeToolCallLayersParams {
-    layers: MemoryLayer[];
-    toolName: string;
-    toolArgs: unknown;
-    ctx: ExecutionContext;
-    store: LayerStateStore;
-}
-interface AfterModelCallLayersParams {
-    layers: MemoryLayer[];
-    response: LLMResponse;
-    ctx: ExecutionContext;
-    store: LayerStateStore;
-}
-interface ProjectHistoryLayersParams {
-    layers: MemoryLayer[];
-    items: ReadonlyArray<Item>;
-    ctx: ExecutionContext;
-    store: LayerStateStore;
-}
-/** @public A request to re-render the context window, collected from onItemAppend hooks. */
-export interface RerenderRequest {
-    layerId: string;
-    slot: number;
-    timing: 'immediate' | 'batched';
-    scope: 'self' | 'slot-after' | 'all';
-}
-/** @public Result of running items through the onItemAppend pipeline. */
-export interface AppendPipelineResult {
-    /** Final items to append after all transformations. */
-    items: Item[];
-    /** Re-render requests collected from layers. */
-    rerenderRequests: RerenderRequest[];
-}
-interface RunAppendPipelineParams {
-    layers: MemoryLayer[];
-    items: Item[];
-    ctx: ExecutionContext;
-    log: ItemLog;
-    store: LayerStateStore;
-}
-interface ExecuteRerenderParams {
-    requests: RerenderRequest[];
-    layers: MemoryLayer[];
-    ctx: ExecutionContext;
-    log: ItemLog;
-    budgets: Map<string, number>;
-    store: LayerStateStore;
-    itemSchemas?: ItemSchemaRegistry;
-    /** Query for context-aware recall (e.g., last user message) */
-    query?: string;
-    /** Current re-render depth (for loop protection) */
-    depth?: number;
-}
-/** Resolve each layer's `BudgetConfig` to a concrete token budget for recall. */
-export declare function resolveLayerBudgets(layers: ReadonlyArray<MemoryLayer>): Map<string, number>;
-export declare function createLayerStateStore(diagnostic?: (layerId: string, hook: string, error: unknown) => void): LayerStateStore;
-export declare function mostRestrictive(decisions: SteeringDecision[]): SteeringDecision;
-export declare function initLayers({ layers, ctx, storage, store }: InitLayersParams): Promise<void>;
-export declare function recallLayers({ layers, query, ctx, log, budgets, store, itemSchemas, }: RecallLayersParams): Promise<{
-    layerId: string;
-    items: Item[];
-    tokenCount: number;
-}[]>;
-export declare function storeLayers({ layers, response, ctx, log, store, storage, }: StoreLayersParams): Promise<void>;
-export declare function disposeLayers({ layers, ctx, store }: DisposeLayersParams): Promise<void>;
-export declare function spawnLayers({ layers, parentCtx, childCtx, store, itemSchemas, }: SpawnLayersParams): Promise<{
-    layerId: string;
-    childState: unknown;
-    items: Item[];
-}[]>;
-export declare function returnLayers<T>({ layers, parentCtx, childCtx, childLog, result, store, }: ReturnLayersParams<T>): Promise<T>;
-export declare function completeLayers({ layers, ctx, log, outcome, store, }: CompleteLayersParams): Promise<void>;
-export declare function beforeToolCallLayers({ layers, toolName, toolArgs, ctx, store, }: BeforeToolCallLayersParams): Promise<SteeringDecision>;
-export declare function afterModelCallLayers({ layers, response, ctx, store, }: AfterModelCallLayersParams): Promise<SteeringDecision>;
-/**
- * Run history items through every layer's `projectHistory` hook in slot order.
- * Each layer receives the previous layer's output. Storage (`itemLog`) is
- * never mutated — this is a pure projection over the input array. Returns
- * the projected items unchanged when no layer registers the hook.
- */
-export declare function projectHistoryLayers({ layers, items, ctx, store, }: ProjectHistoryLayersParams): Promise<ReadonlyArray<Item>>;
-/**
- * Run items through the onItemAppend pipeline.
- * Each layer can filter, transform, or inject items.
- * Returns final items to append and any re-render requests.
- */
-export declare function runAppendPipeline({ layers, items, ctx, log, store, }: RunAppendPipelineParams): Promise<AppendPipelineResult>;
-/**
- * Execute re-render based on collected requests.
- * Determines which layers need re-recall based on scope and runs them.
- * Returns new recall results to merge into view.
- */
-export declare function executeRerender({ requests, layers, ctx, log, budgets, store, itemSchemas, query, depth, }: ExecuteRerenderParams): Promise<{
-    layerId: string;
-    items: Item[];
-    tokenCount: number;
-}[]>;
-export {};