@noetic-tools/core 5.8.0 → 5.9.0

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

@@ -10,6 +10,7 @@ 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
@@ -548,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:
@@ -738,8 +741,13 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
             }
             return returnLayers({
                 layers,
+                stepId: step.id,
                 parentCtx: parentExecutionCtx,
-                childCtx: childExecutionCtx,
+                // `childExecutionCtx` predates the spawn span; trace onto that span.
+                childCtx: {
+                    ...childExecutionCtx,
+                    trace: span,
+                },
                 childLog: childCtx.itemLog,
                 result: childOutput,
                 store: layerStore,

package/dist/interpreter/execute-control.js

@@ -86,7 +86,7 @@ function tracePaths(ctx, executeStep, childContexts) {
         },
     };
 }
-function createForkLayerBridge({ ctx, childContexts, opts, }) {
+function createForkLayerBridge({ stepId, ctx, childContexts, opts, }) {
     const layers = ctx.layers;
     const layerStore = opts?.layerStore;
     if (!layers || layers.length === 0 || !layerStore) {
@@ -113,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,
@@ -173,6 +174,7 @@ export async function executeInParallel(step, input, ctx, rawExecuteStep, opts)
     const childContexts = createChildContexts(baseCtx, paths, step.id);
     const concurrency = step.concurrency ?? paths.length;
     const traced = tracePaths(baseCtx, withForkLayers(rawExecuteStep, childContexts, createForkLayerBridge({
+        stepId: step.id,
         ctx: baseCtx,
         childContexts,
         opts,

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.js

@@ -142,14 +142,12 @@ export function resolveLedgerKey(step, input, ctx) {
 }
 /**
  * Resume path: when a previous run recorded this exact step at `ledgerKey`,
- * replay its output instead of re-running. Held as a helper (rather than inline
- * in `execute`) so the resume branch stays flat: it pops the frontier itself —
- * the caller returns before the normal `leaveStep` runs — and emits
- * `step_replayed`. Returns `{ hit: false }` when there is nothing to replay so
- * the caller dispatches the step normally.
+ * replay its output instead of re-running, and emit `step_replayed`. Returns
+ * `{ hit: false }` when there is nothing to replay so the caller dispatches the
+ * step normally.
  */
 function replayFromLedger(opts) {
-    const { ledger, ledgerKey, impl, step, broadcaster, agentName } = opts;
+    const { ledger, ledgerKey, step, broadcaster, agentName } = opts;
     if (!ledger || ledgerKey === undefined || ledger.isEmpty) {
         return {
             hit: false,
@@ -164,9 +162,6 @@ function replayFromLedger(opts) {
             hit: false,
         };
     }
-    if (impl && step.id.length > 0) {
-        impl.leaveStep(step.id);
-    }
     emitFrameworkEvent({
         broadcaster,
         agentName,
@@ -249,56 +244,57 @@ export async function execute(step, input, ctx) {
             data: startedData,
         });
     }
-    // Push onto the durable frontier so checkpoints can record exactly which
-    // step was in flight when the snapshot fired. Steps with empty ids are
-    // skipped — they are not reattachable by id and would pollute the stack.
+    /* Register the step as in flight, so a checkpoint records it in the frontier, and
+     * run it on its own lane: a view of the context that carries this dispatch's path.
+     * Steps this step dispatches hang under that path, so concurrent dispatches on one
+     * context cannot interleave each other's paths. Steps with empty ids stay on the
+     * caller's lane — they are not reattachable by id and add no path segment. */
     const impl = asContextImpl(baseCtx);
-    if (impl && step.id.length > 0) {
-        impl.enterStep({
-            stepId: step.id,
-            input,
-        });
-    }
+    const frame = {
+        stepId: step.id,
+        input,
+    };
+    const lane = impl && step.id.length > 0 ? impl.enterStep(frame) : null;
+    const stepCtx = lane ? frameworkCast(lane) : ctx;
     /* Resume: a previous run that completed this exact step replays its recorded
      * output instead of re-running it. `ledgerKey`/`ledger` are captured before
-     * dispatch and reused by the record below, because `leaveStep` pops the path
-     * on the way out. */
-    const ledgerKey = resolveLedgerKey(step, input, ctx);
+     * dispatch and reused by the record below. */
+    const ledgerKey = resolveLedgerKey(step, input, stepCtx);
     const ledger = impl?.ledger;
     const replay = replayFromLedger({
         ledger,
         ledgerKey,
-        impl,
         step,
         broadcaster,
         agentName,
     });
     if (replay.hit) {
+        lane?.leaveStep(frame);
         return replay.output;
     }
     let result;
     try {
         switch (step.kind) {
             case 'runCode':
-                result = await dispatchViaAdapter(step, input, ctx, () => executeRunCode(step, input, ctx));
+                result = await dispatchViaAdapter(step, input, stepCtx, () => executeRunCode(step, input, stepCtx));
                 break;
             case 'callModel':
-                result = await executeCallModel(step, input, ctx, baseCtx.layers);
+                result = await executeCallModel(step, input, stepCtx, baseCtx.layers);
                 break;
             case 'acp-agent':
-                result = await executeAcpAgent(step, input, ctx, baseCtx.layers);
+                result = await executeAcpAgent(step, input, stepCtx, baseCtx.layers);
                 break;
             case 'invokeTool':
-                result = await executeInvokeTool(step, input, ctx, baseCtx.harness);
+                result = await executeInvokeTool(step, input, stepCtx, baseCtx.harness);
                 break;
             case 'decide':
-                result = await executeDecide(step, input, ctx, baseCtx.layers);
+                result = await executeDecide(step, input, stepCtx, baseCtx.layers);
                 break;
             case 'conditional':
-                result = await executeConditional(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeConditional(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             case 'inParallel':
-                result = await executeInParallel(step, input, ctx, (s, i, c) => execute(s, i, c), {
+                result = await executeInParallel(step, input, stepCtx, (s, i, c) => execute(s, i, c), {
                     // Fork paths are child executions: the layer store lets their
                     // `onSpawn`/`onReturn` boundary run (see `createForkLayerBridge`).
                     layerStore: harnessWithLayerStore(baseCtx).layerStateStore,
@@ -306,16 +302,16 @@ export async function execute(step, input, ctx) {
                 });
                 break;
             case 'spawn':
-                result = await dispatchViaAdapter(step, input, ctx, () => executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), buildSpawnOpts(ctx)));
+                result = await dispatchViaAdapter(step, input, stepCtx, () => executeSpawn(step, input, stepCtx, (s, i, c) => execute(s, i, c), buildSpawnOpts(stepCtx)));
                 break;
             case 'withContext':
-                result = await executeWithContext(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeWithContext(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             case 'loop':
-                result = await executeLoop(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeLoop(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             case 'schedule':
-                result = await executeSchedule(step, input, ctx, (s, i, c) => execute(s, i, c));
+                result = await executeSchedule(step, input, stepCtx, (s, i, c) => execute(s, i, c));
                 break;
             default: {
                 const _exhaustive = step;
@@ -330,9 +326,7 @@ export async function execute(step, input, ctx) {
         }
     }
     finally {
-        if (impl && step.id.length > 0) {
-            impl.leaveStep(step.id);
-        }
+        lane?.leaveStep(frame);
     }
     // Emit step_completed framework event (respects step.emit option)
     const completedData = {

package/dist/interpreter/model-error.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from './action-types.js';
+/**
+ * Give an error from a model provider call the step's id and a Noetic kind.
+ *
+ * Noetic errors pass through untouched. A failure on an aborted context is
+ * `cancelled` (the abort is what broke the call), a 429 is `model_rate_limit`,
+ * and anything else is `step_failed` with the provider error as its cause.
+ */
+export declare function wrapModelError(e: unknown, stepId: string, ctx: Pick<Context, 'aborted' | 'abortReason'>): Error;

package/dist/interpreter/model-error.js

@@ -0,0 +1,32 @@
+import { isNoeticError, NoeticConfigError, NoeticErrorImpl } from '@noetic-tools/types';
+import { statusOf } from '../util/status-code.js';
+/**
+ * Give an error from a model provider call the step's id and a Noetic kind.
+ *
+ * Noetic errors pass through untouched. A failure on an aborted context is
+ * `cancelled` (the abort is what broke the call), a 429 is `model_rate_limit`,
+ * and anything else is `step_failed` with the provider error as its cause.
+ */
+export function wrapModelError(e, stepId, ctx) {
+    if (isNoeticError(e) || e instanceof NoeticConfigError) {
+        return e;
+    }
+    if (ctx.aborted) {
+        return new NoeticErrorImpl({
+            kind: 'cancelled',
+            reason: ctx.abortReason ?? 'context aborted',
+        });
+    }
+    if (statusOf(e) === 429) {
+        return new NoeticErrorImpl({
+            kind: 'model_rate_limit',
+            stepId,
+        });
+    }
+    return new NoeticErrorImpl({
+        kind: 'step_failed',
+        stepId,
+        cause: e instanceof Error ? e : new Error(String(e)),
+        retriesExhausted: false,
+    });
+}

package/dist/interpreter/step-walk.d.ts

@@ -0,0 +1,11 @@
+import type { Step } from '@noetic-tools/types';
+/**
+ * Whether `step` or any step nested in it satisfies `test`.
+ *
+ * Only statically declared children are visited: a `conditional` or
+ * `inParallel` built from functions exposes its children through
+ * `_optimizable` only when the builder could enumerate them.
+ */
+export declare function someStep(step: Step, test: (step: Step) => boolean): boolean;
+/** The steps nested directly inside `step`, as far as they are statically known. */
+export declare function stepChildren(step: Step): ReadonlyArray<Step>;

package/dist/interpreter/step-walk.js

@@ -0,0 +1,41 @@
+/**
+ * Whether `step` or any step nested in it satisfies `test`.
+ *
+ * Only statically declared children are visited: a `conditional` or
+ * `inParallel` built from functions exposes its children through
+ * `_optimizable` only when the builder could enumerate them.
+ */
+export function someStep(step, test) {
+    if (test(step)) {
+        return true;
+    }
+    return stepChildren(step).some((child) => someStep(child, test));
+}
+/** The steps nested directly inside `step`, as far as they are statically known. */
+export function stepChildren(step) {
+    switch (step.kind) {
+        case 'callModel':
+        case 'runCode':
+        case 'invokeTool':
+        case 'decide':
+        case 'acp-agent':
+            return [];
+        case 'conditional':
+        case 'inParallel':
+            return step._optimizable ?? [];
+        case 'withContext':
+        case 'spawn':
+            return [
+                step.child,
+            ];
+        case 'loop':
+            return step.steps;
+        case 'schedule':
+            return [
+                step.step,
+            ];
+        default:
+            step;
+            return [];
+    }
+}

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

@@ -72,4 +72,11 @@ export declare const NoeticEvent: {
     readonly LOOP_VERDICT: "loop.verdict";
     /** A channel dropped data or is waiting with no timeout: `{ kind, channelName, message, capacity?, operation? }`. */
     readonly CHANNEL_WARNING: "channel.warning";
+    /**
+     * A layer's `onReturn` hook failed, so a spawn or inParallel path returned
+     * its result unchanged. Added to the child's span: `{ stepId, layerId,
+     * message }`. Defined in `@noetic-tools/context`, whose `returnLayers`
+     * emits it and cannot import core.
+     */
+    readonly SPAWN_SUMMARY_FAILED: "spawn.summary_failed";
 };

package/dist/observability/genai-attributes.js

@@ -1,3 +1,4 @@
+import { SPAWN_SUMMARY_FAILED_EVENT } from '@noetic-tools/context';
 // GenAI Semantic Convention attributes
 export const GenAI = {
     SYSTEM: 'gen_ai.system',
@@ -77,4 +78,11 @@ export const NoeticEvent = {
     LOOP_VERDICT: 'loop.verdict',
     /** A channel dropped data or is waiting with no timeout: `{ kind, channelName, message, capacity?, operation? }`. */
     CHANNEL_WARNING: 'channel.warning',
+    /**
+     * A layer's `onReturn` hook failed, so a spawn or inParallel path returned
+     * its result unchanged. Added to the child's span: `{ stepId, layerId,
+     * message }`. Defined in `@noetic-tools/context`, whose `returnLayers`
+     * emits it and cannot import core.
+     */
+    SPAWN_SUMMARY_FAILED: SPAWN_SUMMARY_FAILED_EVENT,
 };

package/dist/runtime/context-impl.d.ts

@@ -69,30 +69,24 @@ export declare class ContextImpl implements Context<ContextData> {
     private readonly _children;
     private _contextData?;
     /**
-     * Stack of steps currently in flight on this context, most-recent last.
-     * Pushed by `enterStep` at the top of `execute()` and popped by
-     * `leaveStep` when the step resolves (success or failure). The harness'
-     * checkpoint writer serialises this stack as the execution frontier so
-     * a restart can identify which step the context was paused inside.
+     * Steps in flight on this context, in dispatch order. `enterStep` adds a frame and
+     * `leaveStep` removes that same frame, so concurrent dispatches can settle in any
+     * order without disturbing each other. The checkpoint writer serialises this set as
+     * the execution frontier.
      * @internal
      */
-    private readonly _frontier;
+    private readonly _inFlight;
     /**
-     * Path segment for each in-flight frame, parallel to `_frontier`. Kept separate so
-     * `serialiseFrontier()` keeps emitting the published `FrontierFrame` shape.
+     * Execution path of the step whose lane this is. On the context itself it is the
+     * prefix its steps hang under: empty on a root context, the parent's path plus a
+     * discriminator on an inParallel/spawn child, so a path stays unique across the whole
+     * step tree. A lane (see `enterStep`) reads its own step's path here instead.
      * @internal
      */
-    private readonly _segments;
-    /**
-     * Path this context's steps hang under. Empty on a root context; an inParallel/spawn child
-     * inherits its parent's current path plus a discriminator, so a path key stays unique
-     * across the whole step tree rather than restarting per child context.
-     * @internal
-     */
-    private readonly _pathPrefix;
+    private readonly _path;
     /**
      * Dispatch counts per `<parent path>/<step id>`, so a loop body re-entered on each
-     * iteration gets `#0`, `#1`, … instead of colliding on one key.
+     * iteration gets `#0`, `#1`, … instead of colliding on one key. Shared by every lane.
      * @internal
      */
     private readonly _occurrences;
@@ -179,28 +173,26 @@ export declare class ContextImpl implements Context<ContextData> {
     get abortSignal(): AbortSignal;
     /**
      * @internal
-     * Push a frame onto the execution frontier. Called by `execute()` at the
-     * top of every step dispatch so that the frontier reflects exactly the
-     * stack of steps currently in-flight on this context.
+     * Register `frame` as in flight and return the lane its step runs on: a view of
+     * this context that shares everything except its execution path. `execute()` hands
+     * the lane to the step, so steps the step dispatches hang under its path no matter
+     * how other dispatches on this context interleave. The occurrence ordinal is taken
+     * here, at dispatch, never at settle.
      */
-    enterStep(frame: FrontierFrame): void;
+    enterStep(frame: FrontierFrame): ContextImpl;
     /**
      * @internal
-     * The execution path of the step currently on top of the frontier — the ledger key
-     * identifying this exact dispatch. Stable across a replay given the same control
-     * flow, which is what lets a resumed run line recorded outputs up with the steps
-     * that produced them.
+     * The execution path of the step this lane belongs to — the ledger key identifying
+     * this exact dispatch. Stable across a replay given the same control flow, which is
+     * what lets a resumed run line recorded outputs up with the steps that produced them.
      */
     currentPath(): string;
     /**
      * @internal
-     * Pop the top frame. Called when a step resolves (success or failure)
-     * so that the frontier unwinds cleanly. The value of `expectedStepId`
-     * is used as a consistency check — if it does not match the top frame
-     * the pop is still performed, but a best-effort warning is surfaced to
-     * stderr rather than swallowed silently.
+     * Drop `frame` from the in-flight set. Called when its step resolves, success or
+     * failure.
      */
-    leaveStep(expectedStepId: string): void;
+    leaveStep(frame: FrontierFrame): void;
     /**
      * @internal
      * Return a defensive copy of the current frontier. Consumed by the
@@ -208,3 +200,9 @@ export declare class ContextImpl implements Context<ContextData> {
      */
     serialiseFrontier(): FrontierFrame[];
 }
+/**
+ * @internal
+ * The context a lane views, or `ctx` itself when it is not a lane. For per-execution
+ * caches keyed by context identity, which every lane of one context must share.
+ */
+export declare function laneBase(ctx: Context<ContextData>): Context<ContextData>;