@noetic-tools/core 0.0.1

package/dist/interpreter/execute-tool.js

@@ -0,0 +1,81 @@
+import { NoeticErrorImpl } from '../errors/noetic-error';
+import { emitFrameworkEvent, getBroadcaster } from '../runtime/broadcaster-utils';
+import { buildToolExecutionContext } from '../runtime/tool-memory';
+import { SteeringAction } from '../types/steering';
+import { frameworkCast } from './framework-cast';
+//#region Helpers
+function isAsyncGenerator(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    return Symbol.asyncIterator in value;
+}
+async function consumeToolGenerator(params) {
+    const broadcaster = getBroadcaster(params.ctx);
+    const agentName = params.ctx.harness.config.name;
+    while (true) {
+        const next = await params.generator.next();
+        if (next.done) {
+            return next.value;
+        }
+        emitFrameworkEvent({
+            broadcaster,
+            agentName,
+            eventType: 'tool_progress',
+            data: {
+                stepId: params.stepId,
+                toolName: params.toolName,
+                event: next.value,
+            },
+        });
+    }
+}
+//#endregion
+//#region Public API
+export async function executeTool(step, input, ctx, harness, layers) {
+    const baseCtx = frameworkCast(ctx);
+    const args = step.args ? Object.assign({}, input, step.args) : input;
+    const parseResult = step.tool.input.safeParse(args);
+    if (!parseResult.success) {
+        throw new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId: step.id,
+            cause: new Error(`Tool input validation failed: ${parseResult.error.message}`),
+            retriesExhausted: false,
+        });
+    }
+    if (layers && layers.length > 0) {
+        const decision = await harness.beforeToolCall(layers, step.tool.name, parseResult.data, baseCtx);
+        if (decision.action !== SteeringAction.Allow) {
+            throw new NoeticErrorImpl({
+                kind: 'steering_denied',
+                guidance: decision.guidance,
+            });
+        }
+    }
+    try {
+        const toolCtx = buildToolExecutionContext(baseCtx, harness);
+        const result = step.tool.execute(parseResult.data, toolCtx);
+        if (isAsyncGenerator(result)) {
+            return frameworkCast(await consumeToolGenerator({
+                generator: result,
+                stepId: step.id,
+                toolName: step.tool.name,
+                ctx: baseCtx,
+            }));
+        }
+        return frameworkCast(await result);
+    }
+    catch (e) {
+        if (e instanceof NoeticErrorImpl) {
+            throw e;
+        }
+        throw new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId: step.id,
+            cause: e instanceof Error ? e : new Error(String(e)),
+            retriesExhausted: false,
+        });
+    }
+}
+//#endregion

package/dist/interpreter/execute.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '../types/context';
+import type { ContextMemory } from '../types/memory';
+import type { Step } from '../types/step';
+/**
+ * Executes a step within the interpreter, dispatching to the appropriate handler by step kind.
+ *
+ * @param step - The step to execute.
+ * @param input - Input value passed to the step.
+ * @param ctx - Execution context carrying state, tokens, and observability.
+ * @returns The step's output value.
+ * @throws `NoeticError` with kind `step_failed` if max depth is exceeded or an unknown step kind is encountered.
+ * @throws `NoeticError` with kind `cancelled` if the context is aborted.
+ */
+export declare function execute<TMemory = ContextMemory, I = unknown, O = unknown>(step: Step<TMemory, I, O>, input: I, ctx: Context<TMemory>): Promise<O>;

package/dist/interpreter/execute.js

@@ -0,0 +1,119 @@
+import { NoeticErrorImpl } from '../errors/noetic-error';
+import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils';
+import { executeBranch } from './execute-branch';
+import { executeEvery } from './execute-every';
+import { executeFork } from './execute-fork';
+import { executeLLM } from './execute-llm';
+import { executeLoop } from './execute-loop';
+import { executeProvide } from './execute-provide';
+import { executeRun } from './execute-run';
+import { executeSpawn } from './execute-spawn';
+import { executeTool } from './execute-tool';
+import { frameworkCast } from './framework-cast';
+import { isMutableContext } from './typeguards';
+const MAX_DEPTH = 64;
+/**
+ * Executes a step within the interpreter, dispatching to the appropriate handler by step kind.
+ *
+ * @param step - The step to execute.
+ * @param input - Input value passed to the step.
+ * @param ctx - Execution context carrying state, tokens, and observability.
+ * @returns The step's output value.
+ * @throws `NoeticError` with kind `step_failed` if max depth is exceeded or an unknown step kind is encountered.
+ * @throws `NoeticError` with kind `cancelled` if the context is aborted.
+ */
+export async function execute(step, input, ctx) {
+    const baseCtx = frameworkCast(ctx);
+    // Depth guard — classified as step_failed (not budget_exceeded) because depth
+    // is a structural safety limit, not a user-configurable budget field.
+    if (ctx.depth >= MAX_DEPTH) {
+        throw new NoeticErrorImpl({
+            kind: 'step_failed',
+            stepId: step.id,
+            cause: new Error(`Maximum spawn depth ${MAX_DEPTH} exceeded (depth: ${ctx.depth})`),
+            retriesExhausted: true,
+        });
+    }
+    // Abort check
+    if (ctx.aborted) {
+        throw new NoeticErrorImpl({
+            kind: 'cancelled',
+            reason: ctx.abortReason ?? 'context aborted',
+        });
+    }
+    // Increment step count
+    if (isMutableContext(baseCtx)) {
+        baseCtx.stepCount = (baseCtx.stepCount || 0) + 1;
+    }
+    // Emit step_started framework event (respects step.emit option)
+    const broadcaster = getBroadcaster(baseCtx);
+    const agentName = baseCtx.harness.config.name;
+    const startedData = {
+        stepId: step.id,
+        kind: step.kind,
+    };
+    const emit = step.kind === 'llm' ? step.emit : undefined;
+    if (shouldEmit(emit, 'step_started', startedData)) {
+        emitFrameworkEvent({
+            broadcaster,
+            agentName,
+            eventType: 'step_started',
+            data: startedData,
+        });
+    }
+    let result;
+    switch (step.kind) {
+        case 'run':
+            result = await executeRun(step, input, ctx);
+            break;
+        case 'llm':
+            result = await executeLLM(step, input, ctx, baseCtx.layers);
+            break;
+        case 'tool':
+            result = await executeTool(step, input, ctx, baseCtx.harness);
+            break;
+        case 'branch':
+            result = await executeBranch(step, input, ctx, (s, i, c) => execute(s, i, c));
+            break;
+        case 'fork':
+            result = await executeFork(step, input, ctx, (s, i, c) => execute(s, i, c));
+            break;
+        case 'spawn':
+            result = await executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), {
+                itemSchemas: baseCtx.itemSchemas,
+            });
+            break;
+        case 'provide':
+            result = await executeProvide(step, input, ctx, (s, i, c) => execute(s, i, c));
+            break;
+        case 'loop':
+            result = await executeLoop(step, input, ctx, (s, i, c) => execute(s, i, c));
+            break;
+        case 'every':
+            result = await executeEvery(step, input, ctx, (s, i, c) => execute(s, i, c));
+            break;
+        default: {
+            const _exhaustive = step;
+            throw new NoeticErrorImpl({
+                kind: 'step_failed',
+                stepId: 'unknown',
+                cause: new Error('Unknown step kind'),
+                retriesExhausted: false,
+            });
+        }
+    }
+    // Emit step_completed framework event (respects step.emit option)
+    const completedData = {
+        stepId: step.id,
+        kind: step.kind,
+    };
+    if (shouldEmit(emit, 'step_completed', completedData)) {
+        emitFrameworkEvent({
+            broadcaster,
+            agentName,
+            eventType: 'step_completed',
+            data: completedData,
+        });
+    }
+    return result;
+}

package/dist/interpreter/framework-cast.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Explicit cast for framework boundaries where TypeScript's type system
+ * cannot express the relationship between input and output types.
+ *
+ * Used for: pass-through returns (branch null route, loop feedback),
+ * raw LLM text output, type-erased collections, and cross-library bridges.
+ *
+ * This is the single approved location for unsafe type coercion in the codebase.
+ */
+export declare function frameworkCast<T>(value: unknown): T;

package/dist/interpreter/framework-cast.js

@@ -0,0 +1,16 @@
+/**
+ * Explicit cast for framework boundaries where TypeScript's type system
+ * cannot express the relationship between input and output types.
+ *
+ * Used for: pass-through returns (branch null route, loop feedback),
+ * raw LLM text output, type-erased collections, and cross-library bridges.
+ *
+ * This is the single approved location for unsafe type coercion in the codebase.
+ */
+// Declared return type differs from the parameter type intentionally —
+// callers specify T to bridge a framework type gap that TypeScript cannot express.
+// The runtime value is returned unchanged (identity function).
+export function frameworkCast(value) {
+    // @ts-expect-error — intentional unsafe coercion at framework boundary
+    return value;
+}

package/dist/interpreter/message-helpers.d.ts

@@ -0,0 +1,9 @@
+import type { LLMResponse } from '../types/common';
+import type { Context } from '../types/context';
+import type { InputMessageItem, Item } from '../types/items';
+export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
+export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
+/** Naive token estimate: ~4 chars per token */
+export declare function estimateTokens(text: string): number;
+/** Accumulate token usage and cost from an LLM response onto the context. */
+export declare function trackUsage(ctx: Context, response: LLMResponse): void;

package/dist/interpreter/message-helpers.js

@@ -0,0 +1,42 @@
+import { isAssistantMessage, isMutableContext, isOutputText } from './typeguards';
+export function createMessage(text, role) {
+    return {
+        id: crypto.randomUUID(),
+        status: 'completed',
+        type: 'message',
+        role,
+        content: [
+            {
+                type: 'input_text',
+                text,
+            },
+        ],
+    };
+}
+export function extractAssistantText(items) {
+    const lastMsg = items.findLast(isAssistantMessage);
+    if (!lastMsg) {
+        return '';
+    }
+    return (lastMsg.content
+        ?.filter(isOutputText)
+        ?.map((c) => c.text)
+        ?.join('') ?? '');
+}
+/** Naive token estimate: ~4 chars per token */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Accumulate token usage and cost from an LLM response onto the context. */
+export function trackUsage(ctx, response) {
+    if (!isMutableContext(ctx)) {
+        return;
+    }
+    ctx.tokens.input += response.usage.inputTokens;
+    ctx.tokens.output += response.usage.outputTokens;
+    ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
+    ctx.tokens.cached = (ctx.tokens.cached ?? 0) + (response.usage.cachedTokens ?? 0);
+    if (response.cost) {
+        ctx.cost = ctx.cost + response.cost;
+    }
+}

package/dist/interpreter/typeguards.d.ts

@@ -0,0 +1,25 @@
+import type { ChannelStore } from '../runtime/channel-store';
+import { ContextImpl } from '../runtime/context-impl';
+import type { Context } from '../types/context';
+import type { FunctionCallItem, Item, MessageItem } from '../types/items';
+import type { ContextMemory } from '../types/memory';
+import type { MutableContext } from '../types/mutable-context';
+export declare function isMutableContext(ctx: Context<ContextMemory>): ctx is MutableContext;
+export declare function isContextImpl(ctx: Context<ContextMemory>): ctx is ContextImpl;
+/**
+ * Co-located with `isContextImpl` so the import of `ContextImpl` flows through
+ * the same module other interpreters pull it from, sidestepping a circular
+ * TDZ when this helper is used by `execute-every.ts`.
+ */
+export declare function getContextChannelStore<TMemory>(ctx: Context<TMemory>): ChannelStore | undefined;
+export declare function isAssistantMessage(item: unknown): item is MessageItem;
+export declare function isUserMessage(item: unknown): item is MessageItem;
+export declare function isFunctionCall(item: Item): item is FunctionCallItem;
+export declare function isOutputText(part: {
+    type: string;
+}): part is {
+    type: 'output_text';
+    text: string;
+};
+declare function assertNever(_value: never): never;
+export { assertNever };

package/dist/interpreter/typeguards.js

@@ -0,0 +1,50 @@
+import { ContextImpl } from '../runtime/context-impl';
+export function isMutableContext(ctx) {
+    // Check if the context has writable mutable fields (ContextImpl or compatible mock)
+    if (ctx instanceof ContextImpl) {
+        return true;
+    }
+    // Duck-type check: verify the fields we need to mutate are present and writable
+    const desc = Object.getOwnPropertyDescriptor(ctx, 'stepCount');
+    return desc !== undefined && desc.writable !== false;
+}
+export function isContextImpl(ctx) {
+    return ctx instanceof ContextImpl;
+}
+/**
+ * Co-located with `isContextImpl` so the import of `ContextImpl` flows through
+ * the same module other interpreters pull it from, sidestepping a circular
+ * TDZ when this helper is used by `execute-every.ts`.
+ */
+export function getContextChannelStore(ctx) {
+    if (ctx instanceof ContextImpl) {
+        return ctx.channelStore;
+    }
+    return undefined;
+}
+export function isAssistantMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message' &&
+        'role' in item &&
+        item.role === 'assistant');
+}
+export function isUserMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message' &&
+        'role' in item &&
+        item.role === 'user');
+}
+export function isFunctionCall(item) {
+    return item.type === 'function_call' && 'callId' in item && 'name' in item;
+}
+export function isOutputText(part) {
+    return part.type === 'output_text';
+}
+function assertNever(_value) {
+    throw new Error('Exhaustive check failed');
+}
+export { assertNever };

package/dist/memory/budget.d.ts

@@ -0,0 +1,23 @@
+import type { Context } from '../types/context';
+import type { MemoryLayer } from '../types/memory';
+export interface BudgetAllocation {
+    layerId: string;
+    allocated: number;
+}
+interface AllocateBudgetsOpts {
+    layers: MemoryLayer[];
+    totalBudget: number;
+    systemPromptTokens: number;
+    responseReserve: number;
+}
+export declare function allocateBudgets({ layers, totalBudget, systemPromptTokens, responseReserve, }: AllocateBudgetsOpts): {
+    allocations: BudgetAllocation[];
+    historyBudget: number;
+};
+export interface BudgetLimits {
+    maxCost?: number;
+    maxSteps?: number;
+    maxDuration?: number;
+}
+export declare function checkBudget(ctx: Context, limits: BudgetLimits): void;
+export {};

package/dist/memory/budget.js

@@ -0,0 +1,117 @@
+import { NoeticErrorImpl } from '../errors/noetic-error';
+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/function-call-utils.d.ts

@@ -0,0 +1,6 @@
+import type { Item } from '../types/items';
+/**
+ * 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

@@ -0,0 +1,25 @@
+import { frameworkCast } from '../interpreter/framework-cast';
+import { isFunctionCall } from '../interpreter/typeguards';
+/**
+ * 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

@@ -0,0 +1,14 @@
+import type { Tool } from '../types/common';
+import type { Context } from '../types/context';
+import type { ContextMemory, MemoryLayer } from '../types/memory';
+import type { AgentHarnessContract } from '../types/runtime';
+/**
+ * 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

@@ -0,0 +1,91 @@
+import { frameworkCast } from '../interpreter/framework-cast';
+import { contextToExecCtx } from '../runtime/exec-context-factory';
+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