@noetic-tools/core 5.7.0 → 5.9.0

package/dist/index.js

@@ -70,7 +70,7 @@ export { createMessage, estimateTokens, recordUsage } from '@noetic-tools/types'
 //#endregion
 //#region Observability
 /** @public */
-export { GenAI, NoeticAttr, ToolAttr } from './observability/genai-attributes.js';
+export { GenAI, NoeticAttr, NoeticEvent, ToolAttr } from './observability/genai-attributes.js';
 /** @public */
 export { InMemoryExporter, NoopExporter } from './observability/trace-exporter.js';
 /** @public */
@@ -90,13 +90,13 @@ export { defaultItemSchemaRegistry, ItemSchema, ItemSchemaRegistry } from '@noet
 /** @public */
 export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, } from './schemas/workflow.js';
 /** @public */
-export { isServerToolSpec, isStandardJsonSchema, isZodSchema, standardIssuesToZodError, validateSchema, } from '@noetic-tools/types';
+export { isServerToolSpec, isStandardJsonSchema, isZodSchema, ServiceTier, standardIssuesToZodError, validateSchema, } from '@noetic-tools/types';
 /** @public */
 export { getToolCwd, setToolCwd, snapshotCwdState } from './runtime/cwd-helpers.js';
 /** @public */
 export { DetachedStatus } from '@noetic-tools/types';
 /** @public */
-export { CheckpointSchemaVersion, CheckpointSnapshotSchema, CwdSnapshotSchema, FrontierFrameSchema, ItemLogSnapshotSchema, PendingAskUserSnapshotSchema, } from './types/checkpoint.js';
+export { ChannelSnapshotSchema, CheckpointSchemaVersion, CheckpointSnapshotSchema, CwdSnapshotSchema, FrontierFrameSchema, ItemLogSnapshotSchema, PendingAskUserSnapshotSchema, } from './types/checkpoint.js';
 /** @public */
 export { Slot } from '@noetic-tools/context';
 /** @public */

package/dist/interpreter/action-deps.d.ts

@@ -3,6 +3,6 @@ export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, c
 export type { ItemSchemaRegistry } from '@noetic-tools/types';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
-export { ContextImpl } from '../runtime/context-impl.js';
+export { ContextImpl, laneBase } from '../runtime/context-impl.js';
 export { snapshotCwdState } from '../runtime/cwd-helpers.js';
 export { buildToolExecutionContext } from '../runtime/tool-context.js';

package/dist/interpreter/action-deps.js

@@ -1,6 +1,6 @@
 export { allocateBudgets, assembleView, churnFor, churnRate, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DECISION_PROJECTION, DEFAULT_PROJECTION, lineageKey, noteCacheOutcome, openEpoch, pin, pinKey, reanchorReason, resolveCacheConfig, resolveLayerTools, returnLayers, spawnLayers, } from '@noetic-tools/context';
 export { defaultItemSchemaRegistry } from '@noetic-tools/types';
 export { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
-export { ContextImpl } from '../runtime/context-impl.js';
+export { ContextImpl, laneBase } from '../runtime/context-impl.js';
 export { snapshotCwdState } from '../runtime/cwd-helpers.js';
 export { buildToolExecutionContext } from '../runtime/tool-context.js';

package/dist/interpreter/child-span.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spans for child contexts (`spawn` children and `inParallel` paths). A child
+ * context carries its own span, so events its steps add to `ctx.span` (e.g.
+ * `loop.verdict`) and the model/tool spans they open nest under the child
+ * rather than being lost to a no-op span.
+ */
+import type { Context, Span } from '@noetic-tools/types';
+/** Opens a span named `name` under `parent.span`, stamped with the owning step id. */
+export declare function openChildSpan(parent: Context, name: string, stepId: string): Span;
+/**
+ * Runs `run` inside `span`, then ends the span and exports it, whether `run`
+ * returns or throws. A failure stamps `noetic.error.kind`; any failure but
+ * cancellation also stamps `error: true`.
+ */
+export declare function traceChild<T>(parent: Context, span: Span, run: () => Promise<T>): Promise<T>;
+/** Ends a span whose child never ran: it was cancelled before it started. */
+export declare function closeUnstartedSpan(parent: Context, span: Span): Promise<void>;

package/dist/interpreter/child-span.js

@@ -0,0 +1,51 @@
+/**
+ * Spans for child contexts (`spawn` children and `inParallel` paths). A child
+ * context carries its own span, so events its steps add to `ctx.span` (e.g.
+ * `loop.verdict`) and the model/tool spans they open nest under the child
+ * rather than being lost to a no-op span.
+ */
+import { isNoeticError } from '@noetic-tools/types';
+import { NoeticAttr } from '../observability/genai-attributes.js';
+/** Opens a span named `name` under `parent.span`, stamped with the owning step id. */
+export function openChildSpan(parent, name, stepId) {
+    const span = parent.harness.createSpan(name, parent.span);
+    span.setAttribute(NoeticAttr.NODE_ID, stepId);
+    return span;
+}
+/**
+ * Runs `run` inside `span`, then ends the span and exports it, whether `run`
+ * returns or throws. A failure stamps `noetic.error.kind`; any failure but
+ * cancellation also stamps `error: true`.
+ */
+export async function traceChild(parent, span, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        markFailed(span, e);
+        throw e;
+    }
+    finally {
+        await closeChildSpan(parent, span);
+    }
+}
+/** Ends a span whose child never ran: it was cancelled before it started. */
+export async function closeUnstartedSpan(parent, span) {
+    span.setAttribute(NoeticAttr.ERROR_KIND, 'cancelled');
+    await closeChildSpan(parent, span);
+}
+function markFailed(span, error) {
+    const kind = isNoeticError(error) ? error.noeticError.kind : undefined;
+    if (kind !== undefined) {
+        span.setAttribute(NoeticAttr.ERROR_KIND, kind);
+    }
+    if (kind !== 'cancelled') {
+        span.setAttribute('error', true);
+    }
+}
+async function closeChildSpan(parent, span) {
+    span.end();
+    await parent.harness.traceExporter.export([
+        span,
+    ]);
+}

package/dist/interpreter/collect-tools.js

@@ -1,4 +1,5 @@
 import { frameworkCast, isServerToolSpec } from '@noetic-tools/types';
+import { stepChildren } from './step-walk.js';
 /**
  * Recursively walks a step tree and collects all Tool instances
  * declared on LLM steps. Used to build the unified tool set
@@ -26,59 +27,23 @@ export function deduplicateTools(tools) {
     ];
 }
 function walkStep(step, out) {
-    switch (step.kind) {
-        case 'callModel':
-            // Skip function-form tools: they're resolved per execution from `ctx`
-            // and cannot contribute to the pre-computed unified set. Consumers that
-            // need those tools in the pool should register them via
-            // `AgentHarness.tools` instead. Inline server-tool specs (web search/
-            // fetch) are not client `Tool`s — they never enter the unified pool.
-            if (Array.isArray(step.tools)) {
-                for (const entry of step.tools) {
-                    if (!isServerToolSpec(entry)) {
-                        out.push(entry);
-                    }
-                }
-            }
-            return;
-        case 'runCode':
-        case 'invokeTool':
-        // Decide steps ask questions; they never call tools.
-        case 'decide':
-        // An ACP agent runs its own tools inside the external agent process; it
-        // contributes nothing to the host unified tool set.
-        case 'acp-agent':
-            return;
-        case 'conditional':
-            if (step._optimizable) {
-                for (const child of step._optimizable) {
-                    walkStep(child, out);
-                }
-            }
-            return;
-        case 'inParallel':
-            if (step._optimizable) {
-                for (const child of step._optimizable) {
-                    walkStep(child, out);
-                }
-            }
-            return;
-        case 'withContext':
-            walkStep(step.child, out);
-            return;
-        case 'spawn':
-            walkStep(step.child, out);
-            return;
-        case 'loop':
-            for (const child of step.steps) {
-                walkStep(child, out);
-            }
-            return;
-        case 'schedule':
-            walkStep(step.step, out);
-            return;
-        default:
-            step;
-            return;
+    if (step.kind !== 'callModel') {
+        for (const child of stepChildren(step)) {
+            walkStep(child, out);
+        }
+        return;
+    }
+    // Skip function-form tools: they're resolved per execution from `ctx`
+    // and cannot contribute to the pre-computed unified set. Consumers that
+    // need those tools in the pool should register them via
+    // `AgentHarness.tools` instead. Inline server-tool specs (web search/
+    // fetch) are not client `Tool`s — they never enter the unified pool.
+    if (!Array.isArray(step.tools)) {
+        return;
+    }
+    for (const entry of step.tools) {
+        if (!isServerToolSpec(entry)) {
+            out.push(entry);
+        }
     }
 }

package/dist/interpreter/execute-action.js

@@ -5,10 +5,12 @@ import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isN
 import { emitToolUi } from '../runtime/tool-ui.js';
 import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, createContextCacheStore, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, lineageKey, noteCacheOutcome, resolveCacheConfig, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.js';
 import { isServerToolSpec, SteeringAction } from './action-types.js';
+import { openChildSpan, traceChild } from './child-span.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { collectAllTools, deduplicateTools } from './collect-tools.js';
 import { prepareBandedView, stampAnchoringAttributes } from './context-assembly.js';
 import { trackUsage } from './message-helpers.js';
+import { wrapModelError } from './model-error.js';
 import { parseStructuredOutput } from './structured-output.js';
 import { getContextChannelStore, isContextImpl, isFunctionCall, isMutableContext, } from './typeguards.js';
 //#region run
@@ -433,6 +435,7 @@ function recordTurnOutcome(params) {
         toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
         usage: response.usage,
         cost: response.cost,
+        serviceTier: response.serviceTier,
         responseItems: response.items,
     };
     if (isMutableContext(ctx)) {
@@ -546,7 +549,9 @@ export async function executeCallModel(step, input, ctx, layers) {
             serverToolSpecs,
             assembledItems,
         });
-        const response = await baseCtx.harness.callModel(request);
+        const response = await baseCtx.harness.callModel(request).catch((e) => {
+            throw wrapModelError(e, step.id, baseCtx);
+        });
         // Track tokens/cost for EVERY model call, including responses steering
         // subsequently rejects (Deny throw / Guide retry below) — the spend is
         // real, and until.maxCost / HarnessResponse.usage must see it (spec 07:
@@ -705,9 +710,11 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
     // `id: childId` keeps the ContextImpl's id in sync with the executionId
     // used by spawnLayers/returnLayers in the layer-state store, so writes via
     // `ctx.context[layerId]` and spawn-boundary hooks read from the same key.
+    const span = openChildSpan(baseCtx, 'spawn', step.id);
     const childCtx = new ContextImpl({
         harness: baseCtx.harness,
         parent: baseCtx,
+        span,
         items: childItems,
         state: cloneWithGuard(baseCtx.state, `Spawn '${step.id}'`),
         threadId: baseCtx.threadId,
@@ -723,23 +730,29 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
         ledger: baseCtx instanceof ContextImpl ? baseCtx.ledger : undefined,
     });
     try {
-        // Execute the child step. Its token/cost usage needs no merge here: every
-        // charge recorded on `childCtx` is also charged up its `usageParent`
-        // chain as it is spent, so a child that throws still bills the parent.
-        const childOutput = await executeStep(step.child, input, frameworkCast(childCtx));
-        // Pipeline result through layer onReturn hooks
-        if (!hasLayers || !parentExecutionCtx) {
-            return childOutput;
-        }
-        const pipelinedResult = await returnLayers({
-            layers,
-            parentCtx: parentExecutionCtx,
-            childCtx: childExecutionCtx,
-            childLog: childCtx.itemLog,
-            result: childOutput,
-            store: layerStore,
+        return await traceChild(baseCtx, span, async () => {
+            // Execute the child step. Its token/cost usage needs no merge here: every
+            // charge recorded on `childCtx` is also charged up its `usageParent`
+            // chain as it is spent, so a child that throws still bills the parent.
+            const childOutput = await executeStep(step.child, input, frameworkCast(childCtx));
+            // Pipeline result through layer onReturn hooks
+            if (!hasLayers || !parentExecutionCtx) {
+                return childOutput;
+            }
+            return returnLayers({
+                layers,
+                stepId: step.id,
+                parentCtx: parentExecutionCtx,
+                // `childExecutionCtx` predates the spawn span; trace onto that span.
+                childCtx: {
+                    ...childExecutionCtx,
+                    trace: span,
+                },
+                childLog: childCtx.itemLog,
+                result: childOutput,
+                store: layerStore,
+            });
         });
-        return pipelinedResult;
     }
     finally {
         // Clean up child execution state to prevent memory leaks — runs on success and error

package/dist/interpreter/execute-control.js

@@ -2,9 +2,11 @@
  * Control-flow step handlers: conditional, inParallel, loop, schedule.
  */
 import { createMessage, frameworkCast, isNoeticError, NoeticErrorImpl } from '@noetic-tools/types';
+import { NoeticAttr, NoeticEvent } from '../observability/genai-attributes.js';
 import { ContextImpl } from '../runtime/context-impl.js';
 import { snapshotCwdState } from '../runtime/cwd-helpers.js';
 import { contextToExecCtx, returnLayers, spawnLayers } from './action-deps.js';
+import { closeUnstartedSpan, openChildSpan, traceChild } from './child-span.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { getContextChannelStore, isContextImpl, isMutableContext } from './typeguards.js';
 //#region conditional
@@ -19,17 +21,20 @@ export async function executeConditional(step, input, ctx, executeStep) {
 }
 //#endregion
 //#region inParallel
-function createChildContexts(ctx, count, stepId) {
+function createChildContexts(ctx, paths, stepId) {
     const threadId = isContextImpl(ctx) ? ctx.threadId : crypto.randomUUID();
     const resourceId = isContextImpl(ctx) ? ctx.resourceId : undefined;
     const channelStore = getContextChannelStore(ctx);
     const parentPath = isContextImpl(ctx) ? ctx.currentPath() : '';
     const parentLedger = isContextImpl(ctx) ? ctx.ledger : undefined;
-    return Array.from({
-        length: count,
-    }, (_unused, index) => new ContextImpl({
+    return paths.map((path, index) => new ContextImpl({
         harness: ctx.harness,
         parent: ctx,
+        span: openPathSpan(ctx, {
+            stepId,
+            pathId: path.id,
+            index,
+        }),
         /* Ledger paths must stay unique across sibling paths: a child ContextImpl
          * starts with an empty frontier, so without a prefix every path would
          * restart at the root and collide with its siblings. */
@@ -52,7 +57,36 @@ function createChildContexts(ctx, count, stepId) {
         unifiedTools: ctx.unifiedTools,
     }));
 }
-function createForkLayerBridge({ ctx, childContexts, opts, }) {
+function openPathSpan(ctx, { stepId, pathId, index, }) {
+    const span = openChildSpan(ctx, 'inParallel.path', pathId);
+    span.setAttribute(NoeticAttr.PARALLEL_ID, stepId);
+    span.setAttribute(NoeticAttr.PARALLEL_INDEX, index);
+    return span;
+}
+/**
+ * Ends each path's span when the path settles. A path that never starts (queued
+ * behind a fail-fast abort, or unstarted when a race settles) has no run to
+ * wrap, so `closeUnstarted` ends its span as cancelled.
+ */
+function tracePaths(ctx, executeStep, childContexts) {
+    const unstarted = new Set(childContexts);
+    return {
+        executeStep: (step, input, childCtx) => {
+            const child = frameworkCast(childCtx);
+            if (!unstarted.delete(child)) {
+                return executeStep(step, input, childCtx);
+            }
+            return traceChild(ctx, child.span, () => executeStep(step, input, childCtx));
+        },
+        async closeUnstarted() {
+            for (const child of unstarted) {
+                await closeUnstartedSpan(ctx, child.span);
+            }
+            unstarted.clear();
+        },
+    };
+}
+function createForkLayerBridge({ stepId, ctx, childContexts, opts, }) {
     const layers = ctx.layers;
     const layerStore = opts?.layerStore;
     if (!layers || layers.length === 0 || !layerStore) {
@@ -79,6 +113,7 @@ function createForkLayerBridge({ ctx, childContexts, opts, }) {
         settle(index, result) {
             return serialize(() => returnLayers({
                 layers: layers ?? [],
+                stepId,
                 parentCtx: parentExecCtx,
                 childCtx: childExecCtxs[index],
                 childLog: childContexts[index].itemLog,
@@ -136,13 +171,15 @@ export async function executeInParallel(step, input, ctx, rawExecuteStep, opts)
             failed: [],
         });
     }
-    const childContexts = createChildContexts(baseCtx, paths.length, step.id);
+    const childContexts = createChildContexts(baseCtx, paths, step.id);
     const concurrency = step.concurrency ?? paths.length;
-    const executeStep = withForkLayers(rawExecuteStep, childContexts, createForkLayerBridge({
+    const traced = tracePaths(baseCtx, withForkLayers(rawExecuteStep, childContexts, createForkLayerBridge({
+        stepId: step.id,
         ctx: baseCtx,
         childContexts,
         opts,
-    }));
+    })), childContexts);
+    const executeStep = traced.executeStep;
     try {
         switch (step.mode) {
             case 'all':
@@ -168,6 +205,7 @@ export async function executeInParallel(step, input, ctx, rawExecuteStep, opts)
         for (const child of childContexts) {
             child.detachFromParent();
         }
+        await traced.closeUnstarted();
     }
 }
 async function runWithConcurrency(tasks, concurrency) {
@@ -368,6 +406,10 @@ async function executeSettle(step, paths, input, ctx, childContexts, executeStep
     });
     return step.merge(results, ctx);
 }
+//#endregion
+//#region loop
+/** History entries a loop keeps when `maxHistorySize` is unset; oldest drop first. */
+const DEFAULT_MAX_HISTORY = 100;
 function hasTextField(value) {
     return typeof value === 'object' && value !== null && 'text' in value;
 }
@@ -409,7 +451,7 @@ export async function executeLoop(step, input, ctx, executeStep) {
     const startTime = Date.now();
     let stepCount = 0;
     const maxIterations = step.maxIterations ?? 1e3;
-    const maxHistory = step.maxHistorySize ?? 100;
+    const maxHistory = step.maxHistorySize ?? DEFAULT_MAX_HISTORY;
     let totalIterations = 0;
     // Validate maxIterations
     if (!Number.isFinite(maxIterations) || maxIterations < 1) {
@@ -515,6 +557,7 @@ export async function executeLoop(step, input, ctx, executeStep) {
                 reason: `Predicate error: ${predicateError instanceof Error ? predicateError.message : String(predicateError)}`,
             };
         }
+        recordVerdict(ctx, step.id, totalIterations, verdict);
         if (verdict.stop) {
             if (lastOutput === undefined) {
                 throw new NoeticErrorImpl({
@@ -614,6 +657,21 @@ function park(parkCtx) {
         });
     });
 }
+/**
+ * Adds a `loop.verdict` event to the enclosing span; loops open no span of
+ * their own. Leaves out `feedback`, which can be large or sensitive.
+ */
+function recordVerdict(ctx, loop, iteration, verdict) {
+    const attributes = {
+        loop,
+        iteration,
+        stop: verdict.stop,
+    };
+    if (verdict.reason !== undefined) {
+        attributes.reason = verdict.reason;
+    }
+    ctx.span.addEvent(NoeticEvent.LOOP_VERDICT, attributes);
+}
 function recordIterationError(ctx, error) {
     const message = error instanceof Error ? error.message : String(error);
     const stack = error instanceof Error && error.stack ? error.stack : '';

package/dist/interpreter/execute-decide.js

@@ -1,10 +1,10 @@
-import { choiceValues, DecideOutputError, frameworkCast, hashString, isNoeticError, NoeticConfigError, NoeticErrorImpl, scoreLevels, } from '@noetic-tools/types';
+import { choiceValues, DecideOutputError, frameworkCast, hashString, NoeticConfigError, NoeticErrorImpl, scoreLevels, } from '@noetic-tools/types';
 import { z } from 'zod';
 import { GenAI, NoeticAttr } from '../observability/genai-attributes.js';
-import { statusOf } from '../util/status-code.js';
-import { allocateBudgets, assembleView, DECISION_PROJECTION } from './action-deps.js';
+import { allocateBudgets, assembleView, DECISION_PROJECTION, laneBase } from './action-deps.js';
 import { resolveLazy } from './execute-action.js';
 import { trackUsage } from './message-helpers.js';
+import { wrapModelError } from './model-error.js';
 import { isContextImpl, isMutableContext } from './typeguards.js';
 //#region Public API
 /**
@@ -110,10 +110,12 @@ export async function executeDecide(step, input, ctx, layers) {
  */
 const ANSWERED = new WeakMap();
 function answered(ctx) {
-    let map = ANSWERED.get(ctx);
+    // Every step runs on its own lane of the context; the answers belong to the context.
+    const key = laneBase(ctx);
+    let map = ANSWERED.get(key);
     if (!map) {
         map = new Map();
-        ANSWERED.set(ctx, map);
+        ANSWERED.set(key, map);
     }
     return map;
 }
@@ -150,16 +152,7 @@ async function askHarness(step, ctx, request) {
         return await ctx.harness.decide(request);
     }
     catch (e) {
-        if (isNoeticError(e) || e instanceof NoeticConfigError) {
-            throw e;
-        }
-        if (ctx.aborted) {
-            throw new NoeticErrorImpl({
-                kind: 'cancelled',
-                reason: ctx.abortReason ?? 'context aborted',
-            });
-        }
-        if (e instanceof DecideOutputError) {
+        if (e instanceof DecideOutputError && !ctx.aborted) {
             if (e.usage) {
                 trackUsage(ctx, {
                     items: [],
@@ -175,18 +168,7 @@ async function askHarness(step, ctx, request) {
                 zodError: e.zodError,
             });
         }
-        if (statusOf(e) === 429) {
-            throw new NoeticErrorImpl({
-                kind: 'model_rate_limit',
-                stepId: step.id,
-            });
-        }
-        throw new NoeticErrorImpl({
-            kind: 'step_failed',
-            stepId: step.id,
-            cause: e instanceof Error ? e : new Error(String(e)),
-            retriesExhausted: false,
-        });
+        throw wrapModelError(e, step.id, ctx);
     }
 }
 //#endregion

package/dist/interpreter/execute.d.ts

@@ -13,6 +13,16 @@ import type { Context, Step } from '@noetic-tools/types';
  * continue to work.
  */
 export declare function executeNoAdapter<TContext, I, O>(step: Step<TContext, I, O>, input: I, ctx: Context<TContext>): Promise<O>;
+/**
+ * @internal
+ * The ledger key this dispatch records and replays under, or undefined when the
+ * step bypasses the ledger (spec 23a § Identity). A `durable: false` step and a
+ * `schedule` (which never completes) are neither replayed nor recorded; the opt-out
+ * covers this step only, so its children still resolve their own keys. A
+ * `replayKey` replaces the positional path with `key:<key>`. A throwing `replayKey`
+ * costs this dispatch its durability, not its run: the step executes unrecorded.
+ */
+export declare function resolveLedgerKey<TContext, I, O>(step: Step<TContext, I, O>, input: I, ctx: Context<TContext>): string | undefined;
 /**
  * Executes a step within the interpreter, dispatching to the appropriate handler by step kind.
  *