@noetic-tools/core 5.2.0 → 5.4.0

package/dist/interpreter/execute-action.js

@@ -1,17 +1,18 @@
 /**
  * Action step handlers: run, llm, spawn, provide, tool.
  */
-import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, isOutputCodec, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
-import { ZodError } from 'zod';
+import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, isOutputCodec, NoeticConfigError, NoeticErrorImpl, validateSchema, } from '@noetic-tools/types';
 import { emitToolUi } from '../runtime/tool-ui.js';
-import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.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 { 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 { parseStructuredOutput } from './structured-output.js';
 import { getContextChannelStore, isContextImpl, isFunctionCall, isMutableContext, } from './typeguards.js';
 //#region run
-export async function executeRun(step, input, ctx) {
+export async function executeRunCode(step, input, ctx) {
     const retry = step.retry;
     const maxAttempts = retry?.maxAttempts ?? 1;
     let lastError = new Error('No attempts executed');
@@ -173,7 +174,7 @@ async function runInputPipeline({ ctx, layers, input, }) {
  * it is kept off `outputSchema` (which drives JSON-schema formatting).
  */
 function resolveOutputMode(output, baseInstructions) {
-    // A generic type predicate does not reliably narrow a `ZodType<O> |
+    // A generic type predicate does not reliably narrow a `StandardSchemaV1 |
     // OutputCodec<O>` union through a free type parameter, so bridge the two
     // branches with the sanctioned framework cast — `isOutputCodec` guarantees
     // the discriminant at runtime.
@@ -222,46 +223,237 @@ function finalizeCodecOutput(codec, lastText, ctx, emit) {
     });
     return session.finish(lastText);
 }
-/** JSON-parse + Zod-validate the assistant text, raising `llm_parse_error`. */
-function parseSchemaOutput(schema, lastText, stepId) {
-    try {
-        return schema.parse(JSON.parse(lastText));
-    }
-    catch (e) {
-        if (e instanceof SyntaxError || e instanceof ZodError) {
-            throw new NoeticErrorImpl({
-                kind: 'llm_parse_error',
-                stepId,
-                raw: lastText,
-                schema,
-                zodError: e instanceof ZodError
-                    ? e
-                    : new ZodError([
-                        {
-                            code: 'custom',
-                            message: `Invalid JSON: ${e.message}`,
-                            path: [],
-                        },
-                    ]),
-            });
-        }
-        throw e;
-    }
-}
 /**
  * Turn the finished assistant text into the step's typed output: a streaming
- * codec, a Zod schema, or raw text passthrough.
+ * codec, a Standard Schema, or raw text passthrough.
  */
-function finalizeStepOutput(params) {
+async function finalizeStepOutput(params) {
     if (params.outputCodec) {
         return finalizeCodecOutput(params.outputCodec, params.lastText, params.ctx, params.emit);
     }
     if (params.outputSchema) {
-        return parseSchemaOutput(params.outputSchema, params.lastText, params.stepId);
+        return parseStructuredOutput({
+            schema: params.outputSchema,
+            rawText: params.lastText,
+            stepId: params.stepId,
+        });
     }
     return frameworkCast(params.lastText);
 }
-export async function executeLLM(step, input, ctx, layers) {
+/**
+ * `step.tools` is heterogeneous: client `Tool`s plus inline OpenRouter
+ * server-tool specs (web search/fetch). Partition them — client tools flow
+ * through the unified-tool / allowedToolNames / steering machinery as before;
+ * server-tool specs bypass it entirely and are stamped onto the model request
+ * (`_serverTools`) for the model caller to wrap via the SDK's `serverTool()`.
+ * `undefined` (unrestricted) is preserved as-is; only a present array is
+ * partitioned so the `[] = opt-out` semantics of step.tools stay intact.
+ */
+function partitionStepTools(resolvedStepTools) {
+    if (resolvedStepTools === undefined) {
+        return {
+            clientStepTools: undefined,
+            serverToolSpecs: [],
+        };
+    }
+    const clientStepTools = [];
+    const serverToolSpecs = [];
+    for (const entry of resolvedStepTools) {
+        if (isServerToolSpec(entry)) {
+            serverToolSpecs.push(entry);
+            continue;
+        }
+        clientStepTools.push(entry);
+    }
+    return {
+        clientStepTools,
+        serverToolSpecs,
+    };
+}
+/**
+ * Append user input — through layer pipeline if layers exist, otherwise direct.
+ * The append pipeline may request a context re-render (e.g. a layer that
+ * expanded an input reference into new content); applied after recall.
+ */
+async function appendUserInput(params) {
+    const { ctx, layers, input } = params;
+    if (typeof input !== 'string' || input.length === 0) {
+        return [];
+    }
+    if (layers !== undefined && layers.length > 0) {
+        return await runInputPipeline({
+            ctx,
+            layers,
+            input,
+        });
+    }
+    ctx.itemLog.append(createMessage(input, 'user'));
+    return [];
+}
+/**
+ * Splits the context budget across layers via `allocateBudgets`. An empty map
+ * when the step runs without layers.
+ */
+function computeBudgetMap(params) {
+    const { layers, policy, systemPromptTokens } = params;
+    if (layers === undefined || layers.length === 0) {
+        return new Map();
+    }
+    const { allocations } = allocateBudgets({
+        layers,
+        totalBudget: policy.tokenBudget,
+        systemPromptTokens,
+        responseReserve: policy.responseReserve,
+    });
+    return new Map(allocations.map((a) => [
+        a.layerId,
+        a.allocated,
+    ]));
+}
+/**
+ * Recall once per LLM step: atomic layers run in the hot path; eventual layers
+ * are served from cache. Results drive both the assembled context window and
+ * the per-layer usage breakdown (ctx.lastLayerUsage). Recall fires before the
+ * steering retry loop because retries replay the same context. Re-render
+ * requests collected from the input-append pipeline are applied on top.
+ */
+async function gatherRecallResults(params) {
+    const { ctx, layers, recallQuery, budgetMap, slotOf, rerenderRequests } = params;
+    if (layers === undefined || layers.length === 0) {
+        return emptyRecall;
+    }
+    const atomic = await ctx.harness.recallLayersAtomic(layers, recallQuery, ctx, budgetMap);
+    const eventual = await ctx.harness.recallLayersEventual(layers, recallQuery, ctx, budgetMap);
+    let recallResults = [
+        ...atomic,
+        ...eventual,
+    ].sort((a, b) => (slotOf.get(a.layerId) ?? 0) - (slotOf.get(b.layerId) ?? 0));
+    if (rerenderRequests.length > 0) {
+        const rerendered = await ctx.harness.executeRerender(rerenderRequests, layers, ctx, budgetMap, recallQuery);
+        recallResults = mergeRecallResults([
+            ...recallResults,
+        ], rerendered, slotOf);
+    }
+    return recallResults;
+}
+/**
+ * Builds the items the model sees for one attempt: system messages stay at the
+ * front, the banded anchor/live/delta output rides between them and history,
+ * and steering guidance from a prior retry lands at the very tail. The
+ * projector enforces the token budget (drops highest-slot layer output, then
+ * oldest history).
+ */
+async function assembleTurnItems(params) {
+    const { ctx, layers, banded, steeringTail, viewPolicy } = params;
+    const rawHistoryItems = ctx.itemLog.items;
+    if (layers === undefined || layers.length === 0) {
+        return rawHistoryItems;
+    }
+    const projectedHistoryItems = await ctx.harness.projectHistory(layers, rawHistoryItems, ctx);
+    const systemItems = [];
+    const nonSystemHistory = [];
+    const tailIds = new Set(steeringTail.map((i) => i.id));
+    for (const item of projectedHistoryItems) {
+        if (item.type === 'message' && item.role === 'system') {
+            systemItems.push(item);
+            continue;
+        }
+        // Steering guidance is re-placed at the tail; skip it here so the retry
+        // does not see the same correction twice.
+        if ('id' in item && typeof item.id === 'string' && tailIds.has(item.id)) {
+            continue;
+        }
+        nonSystemHistory.push(item);
+    }
+    return assembleView({
+        systemPromptItems: systemItems,
+        layerOutputItems: banded.anchorItems,
+        historyItems: nonSystemHistory,
+        liveLayerItems: banded.liveItems,
+        deltaItems: banded.deltaItems,
+        tailItems: steeringTail,
+        policy: viewPolicy,
+    });
+}
+/**
+ * Builds the callModel request for one attempt. Cancellation reaches INSIDE
+ * the model call, not just the step boundary: the caller's abort signal stops
+ * the stream and the tool-round loop mid flight, so `ctx.abort()` /
+ * `harness.cancel()` don't wait out a long generation before taking effect
+ * (spec 09, Cancellation item 2).
+ */
+function buildModelRequest(params) {
+    const { step, ctx, layers } = params;
+    const _serverTools = params.serverToolSpecs.length > 0 ? params.serverToolSpecs : undefined;
+    const signal = isContextImpl(ctx) ? ctx.abortSignal : undefined;
+    if (params.resolvedTools) {
+        return {
+            model: params.resolvedModel,
+            items: params.assembledItems,
+            instructions: params.resolvedInstructions,
+            tools: params.resolvedTools,
+            params: step.params,
+            outputSchema: params.outputSchema,
+            outputJsonSchema: params.step.outputJsonSchema,
+            emit: step.emit,
+            _serverTools,
+            ctx,
+            layers,
+            allowedToolNames: params.allowedToolNames,
+            nodeId: step.id,
+            parentSpan: ctx.span,
+            signal,
+        };
+    }
+    return {
+        model: params.resolvedModel,
+        items: params.assembledItems,
+        instructions: params.resolvedInstructions,
+        params: step.params,
+        outputSchema: params.outputSchema,
+        outputJsonSchema: params.step.outputJsonSchema,
+        emit: step.emit,
+        _serverTools,
+        nodeId: step.id,
+        parentSpan: ctx.span,
+        signal,
+    };
+}
+/**
+ * Records a finished model response on the context: appends response items to
+ * the log, publishes `lastStepMeta`, and commits the per-layer usage breakdown
+ * (what the model was actually shown, pinned replays included — raw recall
+ * output would report content it never saw).
+ */
+function recordTurnOutcome(params) {
+    const { ctx, response, banded } = params;
+    const toolCalls = [];
+    for (const item of response.items) {
+        ctx.itemLog.append(item);
+        if (isFunctionCall(item)) {
+            toolCalls.push(item);
+        }
+    }
+    const meta = {
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+        usage: response.usage,
+        cost: response.cost,
+        responseItems: response.items,
+    };
+    if (isMutableContext(ctx)) {
+        ctx.lastStepMeta = meta;
+    }
+    commitLayerUsage(ctx, computeLayerUsage({
+        ctx,
+        modelId: params.resolvedModel,
+        instructions: params.resolvedInstructions,
+        tools: params.resolvedTools,
+        recallResults: banded.servedPerLayer,
+        serveInfo: banded.serveInfo,
+        epoch: banded.epoch,
+    }));
+}
+export async function executeCallModel(step, input, ctx, layers) {
     const baseCtx = frameworkCast(ctx);
     const hasLayers = layers !== undefined && layers.length > 0;
     // Resolve lazy step fields up-front. Function-form getters run once per
@@ -271,49 +463,19 @@ export async function executeLLM(step, input, ctx, layers) {
     if (!resolvedModel || resolvedModel.trim() === '') {
         throw new NoeticConfigError({
             code: 'MISSING_MODEL',
-            message: `step.llm(${JSON.stringify(step.id)}) resolved model to an empty string.`,
+            message: `callModel(${JSON.stringify(step.id)}) resolved model to an empty string.`,
             hint: "Ensure `model` (or your `(ctx) => string` getter) returns a non-empty identifier, e.g. 'anthropic/claude-sonnet-4-20250514'.",
         });
     }
     const baseInstructions = await resolveLazy(step.instructions, ctx);
     const { outputCodec, outputSchema, resolvedInstructions } = resolveOutputMode(step.output, baseInstructions);
     const resolvedStepTools = await resolveLazy(step.tools, ctx);
-    // `step.tools` is heterogeneous: client `Tool`s plus inline OpenRouter
-    // server-tool specs (web search/fetch). Partition them — client tools flow
-    // through the unified-tool / allowedToolNames / steering machinery as before;
-    // server-tool specs bypass it entirely and are stamped onto the model request
-    // (`_serverTools`) for the model caller to wrap via the SDK's `serverTool()`.
-    // `undefined` (unrestricted) is preserved as-is; only a present array is
-    // partitioned so the `[] = opt-out` semantics of step.tools stay intact.
-    let clientStepTools;
-    const serverToolSpecs = [];
-    if (resolvedStepTools !== undefined) {
-        clientStepTools = [];
-        for (const entry of resolvedStepTools) {
-            if (isServerToolSpec(entry)) {
-                serverToolSpecs.push(entry);
-            }
-            else {
-                clientStepTools.push(entry);
-            }
-        }
-    }
-    // Append user input — through layer pipeline if layers exist, otherwise direct.
-    // The append pipeline may request a context re-render (e.g. a layer that
-    // expanded an input reference into new content); applied after recall below.
-    let rerenderRequests = [];
-    if (typeof input === 'string' && input.length > 0) {
-        if (hasLayers) {
-            rerenderRequests = await runInputPipeline({
-                ctx: baseCtx,
-                layers,
-                input,
-            });
-        }
-        else {
-            baseCtx.itemLog.append(createMessage(input, 'user'));
-        }
-    }
+    const { clientStepTools, serverToolSpecs } = partitionStepTools(resolvedStepTools);
+    const rerenderRequests = await appendUserInput({
+        ctx: baseCtx,
+        layers,
+        input,
+    });
     const { tools: resolvedTools, allowedToolNames } = resolveToolsAndRestrictions(clientStepTools, layers, baseCtx);
     // Resolve the projection policy (step override > harness default > fallback)
     // and split the context budget across layers via allocateBudgets.
@@ -326,120 +488,92 @@ export async function executeLLM(step, input, ctx, layers) {
         ...policy,
         tokenBudget: Math.max(0, policy.tokenBudget - systemPromptTokens),
     };
-    let budgetMap = new Map();
-    if (hasLayers) {
-        const { allocations } = allocateBudgets({
-            layers,
-            totalBudget: policy.tokenBudget,
-            systemPromptTokens,
-            responseReserve: policy.responseReserve,
-        });
-        budgetMap = new Map(allocations.map((a) => [
-            a.layerId,
-            a.allocated,
-        ]));
-    }
-    // Recall once per LLM step: atomic layers run in the hot path; eventual layers
-    // are served from cache. Results drive both the assembled context window and
-    // the per-layer usage breakdown (ctx.lastLayerUsage). Recall fires before the
-    // steering retry loop because retries replay the same context.
+    const budgetMap = computeBudgetMap({
+        layers,
+        policy,
+        systemPromptTokens,
+    });
     const recallQuery = typeof input === 'string' ? input : '';
     const slotOf = new Map((layers ?? []).map((l) => [
         l.id,
         l.slot,
     ]));
-    let recallResults = emptyRecall;
-    if (hasLayers) {
-        const atomic = await baseCtx.harness.recallLayersAtomic(layers, recallQuery, baseCtx, budgetMap);
-        const eventual = await baseCtx.harness.recallLayersEventual(layers, recallQuery, baseCtx, budgetMap);
-        recallResults = [
-            ...atomic,
-            ...eventual,
-        ].sort((a, b) => (slotOf.get(a.layerId) ?? 0) - (slotOf.get(b.layerId) ?? 0));
-        // Apply re-render requests collected from the input-append pipeline.
-        if (rerenderRequests.length > 0) {
-            const rerendered = await baseCtx.harness.executeRerender(rerenderRequests, layers, baseCtx, budgetMap, recallQuery);
-            recallResults = mergeRecallResults([
-                ...recallResults,
-            ], rerendered, slotOf);
-        }
-    }
-    const layerOutputItems = recallResults.flatMap((r) => r.items);
+    const recallResults = await gatherRecallResults({
+        ctx: baseCtx,
+        layers,
+        recallQuery,
+        budgetMap,
+        slotOf,
+        rerenderRequests,
+    });
+    // Split recall output into the cache-stable anchor band and the live band,
+    // replaying pinned anchors and gathering any changes into one supersede
+    // message. Runs once, outside the retry loop, for the same reason recall does:
+    // a retry replays this view rather than building a new one.
+    // A harness that predates anchoring carries no store. Give it a throwaway:
+    // nothing survives the turn, so its layers render fresh every time — the
+    // behaviour it had before the bands existed.
+    const cacheStore = baseCtx.harness.contextCache ?? createContextCacheStore();
+    const banded = await prepareBandedView({
+        recallResults,
+        layers: layers ?? [],
+        execCtx: contextToExecCtx(baseCtx),
+        store: cacheStore,
+        config: baseCtx.harness.config.contextCache,
+        instructions: resolvedInstructions,
+        policy: viewPolicy,
+        systemPromptItems: [],
+        budgets: budgetMap,
+    });
+    stampAnchoringAttributes(baseCtx.span, banded);
     let retries = 0;
+    // Guidance from a steering retry rides at the very end of the view, after the
+    // live band and the supersedes, rather than wherever history happens to put it.
+    let steeringTail = [];
+    let cacheJudged = false;
     while (retries <= MAX_STEERING_RETRIES) {
-        const rawHistoryItems = baseCtx.itemLog.items;
-        const projectedHistoryItems = hasLayers
-            ? await baseCtx.harness.projectHistory(layers, rawHistoryItems, baseCtx)
-            : rawHistoryItems;
-        let assembledItems;
-        if (hasLayers) {
-            // Keep system messages at the front; the projector enforces the token
-            // budget (drops highest-slot layer output, then oldest history).
-            const systemItems = [];
-            const nonSystemHistory = [];
-            for (const item of projectedHistoryItems) {
-                if (item.type === 'message' && item.role === 'system') {
-                    systemItems.push(item);
-                    continue;
-                }
-                nonSystemHistory.push(item);
-            }
-            assembledItems = assembleView({
-                systemPromptItems: systemItems,
-                layerOutputItems,
-                historyItems: nonSystemHistory,
-                policy: viewPolicy,
-            });
-        }
-        else {
-            assembledItems =
-                projectedHistoryItems === rawHistoryItems
-                    ? rawHistoryItems
-                    : [
-                        ...projectedHistoryItems,
-                    ];
-        }
-        const _serverTools = serverToolSpecs.length > 0 ? serverToolSpecs : undefined;
-        // Cancellation reaches INSIDE the model call, not just the step boundary:
-        // the caller's abort signal stops the stream and the tool-round loop mid
-        // flight, so `ctx.abort()` / `harness.cancel()` don't wait out a long
-        // generation before taking effect (spec 09, Cancellation item 2).
-        const signal = isContextImpl(baseCtx) ? baseCtx.abortSignal : undefined;
-        const request = resolvedTools
-            ? {
-                model: resolvedModel,
-                items: assembledItems,
-                instructions: resolvedInstructions,
-                tools: resolvedTools,
-                params: step.params,
-                outputSchema: outputSchema,
-                emit: step.emit,
-                _serverTools,
-                ctx: baseCtx,
-                layers,
-                allowedToolNames,
-                nodeId: step.id,
-                parentSpan: baseCtx.span,
-                signal,
-            }
-            : {
-                model: resolvedModel,
-                items: assembledItems,
-                instructions: resolvedInstructions,
-                params: step.params,
-                outputSchema: outputSchema,
-                emit: step.emit,
-                _serverTools,
-                nodeId: step.id,
-                parentSpan: baseCtx.span,
-                signal,
-            };
+        const assembledItems = await assembleTurnItems({
+            ctx: baseCtx,
+            layers,
+            banded,
+            steeringTail,
+            viewPolicy,
+        });
+        const request = buildModelRequest({
+            step,
+            ctx: baseCtx,
+            layers,
+            resolvedModel,
+            resolvedInstructions,
+            resolvedTools,
+            allowedToolNames,
+            outputSchema,
+            serverToolSpecs,
+            assembledItems,
+        });
         const response = await baseCtx.harness.callModel(request);
         // 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:
         // tokens accumulate across all LLM calls).
         trackUsage(baseCtx, response);
+        // Ask the model's own token report whether the prompt prefix survived. A
+        // clear miss records a re-anchor that the next assembly picks up — pins are
+        // never touched here, so a response steering later rejects cannot leave the
+        // epoch half-rebuilt.
+        // Judged once per assembly, not once per call: a steering retry re-sends
+        // the same view, so counting its response again would reach the give-up
+        // threshold inside a single turn and blind the lineage for good.
+        if (banded.epoch && !cacheJudged) {
+            cacheJudged = true;
+            noteCacheOutcome({
+                store: cacheStore,
+                key: lineageKey(contextToExecCtx(baseCtx)),
+                response,
+                config: resolveCacheConfig(baseCtx.harness.config.contextCache),
+                expectedTokens: systemPromptTokens + banded.epoch.anchorTokens,
+            });
+        }
         // An abort that landed mid-call returns whatever rounds completed before
         // the signal fired. The spend is charged above, but a truncated generation
         // is not this step's output — surface cancellation instead.
@@ -458,34 +592,28 @@ export async function executeLLM(step, input, ctx, layers) {
                 });
             }
             if (decision.action === SteeringAction.Guide && retries < MAX_STEERING_RETRIES) {
-                baseCtx.itemLog.append(createMessage(decision.guidance ?? 'Please adjust your response.', 'developer'));
+                const guidance = createMessage(decision.guidance ?? 'Please adjust your response.', 'developer');
+                // Logged so it persists into the conversation, and carried as the tail
+                // so the retry's view ends on the correction rather than burying it
+                // ahead of the live band. Assembly drops it from history to avoid
+                // showing it twice.
+                baseCtx.itemLog.append(guidance);
+                steeringTail = [
+                    ...steeringTail,
+                    guidance,
+                ];
                 retries++;
                 continue;
             }
         }
-        const toolCalls = [];
-        for (const item of response.items) {
-            baseCtx.itemLog.append(item);
-            if (isFunctionCall(item)) {
-                toolCalls.push(item);
-            }
-        }
-        const meta = {
-            toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
-            usage: response.usage,
-            cost: response.cost,
-            responseItems: response.items,
-        };
-        if (isMutableContext(baseCtx)) {
-            baseCtx.lastStepMeta = meta;
-        }
-        commitLayerUsage(baseCtx, computeLayerUsage({
+        recordTurnOutcome({
             ctx: baseCtx,
-            modelId: resolvedModel,
-            instructions: resolvedInstructions,
-            tools: resolvedTools,
-            recallResults,
-        }));
+            response,
+            resolvedModel,
+            resolvedInstructions,
+            resolvedTools,
+            banded,
+        });
         if (hasLayers) {
             await baseCtx.harness.storeLayers(layers, response, baseCtx);
         }
@@ -579,7 +707,7 @@ export async function executeSpawn(step, input, ctx, executeStep, opts) {
     // Build unified tool set for child from its step tree + layers, plus the
     // parent's unified tools. Sub-agents that read tools dynamically (via
     // `ctx.unifiedTools`) otherwise lose the harness tool pool at the spawn
-    // boundary — a child whose `step.llm` resolves `tools` from context would
+    // boundary — a child whose `callModel` resolves `tools` from context would
     // see nothing. Inheriting the parent's tools keeps the harness toolset
     // available across spawns; the child's own step/layer tools take precedence
     // on name collision (dedup keeps the first occurrence), and children that
@@ -674,7 +802,7 @@ function mergeLayers(existing, provided) {
  * Unlike spawn, provide does not create a new itemLog or clone state.
  * Events flow through to the parent in real-time.
  */
-export async function executeProvide(step, input, ctx, executeStep) {
+export async function executeWithContext(step, input, ctx, executeStep) {
     const baseCtx = frameworkCast(ctx);
     const previousLayers = baseCtx.layers;
     const previousUnifiedTools = baseCtx.unifiedTools;
@@ -729,7 +857,7 @@ async function consumeToolGenerator(params) {
                 event: next.value,
             },
         });
-        // A direct `step.tool` has no model call id — the step id keys its region.
+        // A direct `invokeTool` has no model call id — the step id keys its region.
         emitToolUi({
             ctx: params.ctx,
             tool: params.tool,
@@ -740,20 +868,21 @@ async function consumeToolGenerator(params) {
         });
     }
 }
-export async function executeTool(step, input, ctx, harness, layers) {
+export async function executeInvokeTool(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);
+    const parseResult = await validateSchema(step.tool.input, args);
     if (!parseResult.success) {
         throw new NoeticErrorImpl({
             kind: 'step_failed',
             stepId: step.id,
-            cause: new Error(`Tool input validation failed: ${parseResult.error.message}`),
+            cause: new Error(`Tool input validation failed: ${parseResult.zodError.message}`),
             retriesExhausted: false,
         });
     }
+    const parsedArgs = parseResult.value;
     if (layers && layers.length > 0) {
-        const decision = await harness.beforeToolCall(layers, step.tool.name, parseResult.data, baseCtx);
+        const decision = await harness.beforeToolCall(layers, step.tool.name, parsedArgs, baseCtx);
         if (decision.action !== SteeringAction.Allow) {
             throw new NoeticErrorImpl({
                 kind: 'steering_denied',
@@ -766,18 +895,18 @@ export async function executeTool(step, input, ctx, harness, layers) {
         tool: step.tool,
         callId: step.id,
         phase: 'call',
-        args: parseResult.data,
+        args: parsedArgs,
     });
     try {
         const toolCtx = buildToolExecutionContext(baseCtx, harness);
-        const execResult = step.tool.execute(parseResult.data, toolCtx);
+        const execResult = step.tool.execute(parsedArgs, toolCtx);
         const result = isAsyncGenerator(execResult)
             ? await consumeToolGenerator({
                 generator: execResult,
                 stepId: step.id,
                 tool: step.tool,
                 ctx: baseCtx,
-                args: parseResult.data,
+                args: parsedArgs,
             })
             : await execResult;
         emitToolUi({
@@ -785,7 +914,7 @@ export async function executeTool(step, input, ctx, harness, layers) {
             tool: step.tool,
             callId: step.id,
             phase: 'result',
-            args: parseResult.data,
+            args: parsedArgs,
             output: result,
         });
         return frameworkCast(result);
@@ -796,7 +925,7 @@ export async function executeTool(step, input, ctx, harness, layers) {
             tool: step.tool,
             callId: step.id,
             phase: 'error',
-            args: parseResult.data,
+            args: parsedArgs,
             error: e,
         });
         if (e instanceof NoeticErrorImpl) {