@noetic-tools/core 0.2.0 → 0.3.0

package/dist/errors/noetic-error.d.ts

@@ -1,18 +0,0 @@
-import type { NoeticError } from '../types/error.js';
-/**
- * Runtime error thrown during step execution (LLM failures, fork failures, budget exceeded, etc.).
- *
- * @public
- */
-export declare class NoeticErrorImpl extends Error {
-    readonly noeticError: NoeticError;
-    constructor(error: NoeticError);
-}
-/**
- * Type guard for `NoeticErrorImpl`.
- *
- * @public
- * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
- */
-export declare function isNoeticError(e: unknown): e is NoeticErrorImpl;

package/dist/errors/noetic-error.js

@@ -1,54 +0,0 @@
-/**
- * Runtime error thrown during step execution (LLM failures, fork failures, budget exceeded, etc.).
- *
- * @public
- */
-export class NoeticErrorImpl extends Error {
-    noeticError;
-    constructor(error) {
-        super(formatMessage(error));
-        this.name = 'NoeticError';
-        this.noeticError = error;
-    }
-}
-/**
- * Type guard for `NoeticErrorImpl`.
- *
- * @public
- * @param e - Value to check.
- * @returns `true` if `e` is a `NoeticErrorImpl`.
- */
-export function isNoeticError(e) {
-    return e instanceof NoeticErrorImpl;
-}
-function formatMessage(error) {
-    switch (error.kind) {
-        case 'step_failed':
-            return `Step '${error.stepId}' failed: ${error.cause.message}`;
-        case 'llm_refused':
-            return `LLM refused at step '${error.stepId}': ${error.refusal}`;
-        case 'llm_parse_error':
-            return `LLM parse error at step '${error.stepId}': failed to parse output`;
-        case 'llm_rate_limit':
-            return `LLM rate limited at step '${error.stepId}'${error.retryAfter ? ` (retry after ${error.retryAfter}ms)` : ''}`;
-        case 'fork_partial':
-            return `Fork '${error.stepId}' partial failure: ${error.succeeded.length} succeeded, ${error.failed.length} failed`;
-        case 'channel_timeout':
-            return `Channel '${error.channelName}' timed out after ${error.timeout}ms`;
-        case 'channel_closed':
-            return `Channel '${error.channelName}' is closed`;
-        case 'cancelled':
-            return `Cancelled${error.reason ? `: ${error.reason}` : ''}`;
-        case 'budget_exceeded':
-            return `Budget exceeded: ${error.field} limit ${error.limit}, actual ${error.actual}`;
-        case 'steering_denied':
-            return `Steering denied${error.guidance ? `: ${error.guidance}` : ''}`;
-        case 'handle_evicted':
-            return `Subprocess handle '${error.handleId}' evicted (step '${error.stepId}'): adapter returned null for ${error.gracePeriodMs}ms`;
-        default: {
-            const _exhaustive = error;
-            void _exhaustive;
-            return 'NoeticError: unknown kind';
-        }
-    }
-}

package/dist/memory/budget.d.ts

@@ -1,23 +0,0 @@
-import type { Context } from '../types/context.js';
-import type { MemoryLayer } from '../types/memory.js';
-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

@@ -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