@jangts/agent-core 0.3.5 → 0.3.6

package/dist/cjs/kits/delivery.js

@@ -2,6 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Delivery = void 0;
 exports.defineDelivery = defineDelivery;
+/**
+ * Delivery Kit: run an ordered, synchronous stage pipeline that ends with one result.
+ *
+ * Place in the package: an optional App-side delivery pipeline (for example formatting and
+ * sending one reply). The Kit owns ordering, cancellation checks and outcome validation; the
+ * stages, their state and the actual side effects belong to the App.
+ *
+ * Exports: `defineDelivery`, `Delivery`, and the delivery option/outcome types.
+ */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 /**
  * Compile a delivery pipeline from its declared stages.
@@ -42,33 +52,35 @@ function defineDelivery(options) {
          *   handler results.
          */
         deliver(input, execution) {
-            execution.signal.throwIfAborted();
-            const state = (0, synchronous_js_1.synchronous)(createState(input, execution), 'Delivery state creation must be synchronous');
-            const context = {
-                ...execution,
-                signal: execution.signal,
-                diagnostics: execution.diagnostics,
-                app: input,
-            };
-            for (const stage of stages) {
+            return (0, native_sub_flow_js_1.nativeSubFlowSync)(execution, 'delivery', 'delivery', () => {
                 execution.signal.throwIfAborted();
-                (0, synchronous_js_1.synchronous)(beforeStage?.({ stageId: stage.id, state }, context), 'Delivery hooks must be synchronous');
-                execution.signal.throwIfAborted();
-                if (!stage.handle)
-                    continue;
-                const outcome = (0, synchronous_js_1.synchronous)(stage.handle(state, context), 'Delivery handlers must be synchronous');
-                execution.signal.throwIfAborted();
-                if (!outcome ||
-                    !['continue', 'complete'].includes(outcome.type) ||
-                    (outcome.type === 'complete' && !('value' in outcome)))
-                    throw new TypeError('Delivery handlers require explicit continue/complete');
-                if (outcome.type === 'complete') {
-                    const value = outcome.value;
+                const state = (0, synchronous_js_1.synchronous)(createState(input, execution), 'Delivery state creation must be synchronous');
+                const context = {
+                    ...execution,
+                    signal: execution.signal,
+                    diagnostics: execution.diagnostics,
+                    app: input,
+                };
+                for (const stage of stages) {
+                    execution.signal.throwIfAborted();
+                    (0, synchronous_js_1.synchronous)(beforeStage?.({ stageId: stage.id, state }, context), 'Delivery hooks must be synchronous');
+                    execution.signal.throwIfAborted();
+                    if (!stage.handle)
+                        continue;
+                    const outcome = (0, synchronous_js_1.synchronous)(stage.handle(state, context), 'Delivery handlers must be synchronous');
                     execution.signal.throwIfAborted();
-                    return value;
+                    if (!outcome ||
+                        !['continue', 'complete'].includes(outcome.type) ||
+                        (outcome.type === 'complete' && !('value' in outcome)))
+                        throw new TypeError('Delivery handlers require explicit continue/complete');
+                    if (outcome.type === 'complete') {
+                        const value = outcome.value;
+                        execution.signal.throwIfAborted();
+                        return value;
+                    }
                 }
-            }
-            throw (0, synchronous_js_1.synchronous)(missingResult(), 'Delivery errors must be synchronous');
+                throw (0, synchronous_js_1.synchronous)(missingResult(), 'Delivery errors must be synchronous');
+            });
         },
     });
 }

package/dist/cjs/kits/knowledge/catalog.js

@@ -10,6 +10,7 @@ exports.defineKnowledgeCatalog = defineKnowledgeCatalog;
  *
  * Exports: `defineKnowledgeCatalog`, and the knowledge document/read/snapshot types.
  */
+const native_sub_flow_js_1 = require("../../diagnostics/native-sub-flow.js");
 const catalog_js_1 = require("../../utils/catalog.js");
 const sections_js_1 = require("./sections.js");
 const observer_js_1 = require("../../utils/observer.js");
@@ -68,37 +69,39 @@ function defineKnowledgeCatalog(documents, options = {}) {
         ...(0, catalog_js_1.readonlyCatalog)([...catalog.values()].map((entry) => entry.document), (id) => new TypeError(`Unknown knowledge document: ${id}`)),
         sectionIds,
         assertSelection,
-        read(input) {
-            const { read, entry } = resolve(input), raw = read.selection;
-            const selection = raw.mode === 'document'
-                ? Object.freeze({ mode: 'document' })
-                : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
-            const content = (selection.mode === 'document'
-                ? (0, sections_js_1.knowledgeText)(entry.document.parts)
-                : selection.sectionIds
-                    .map((id) => (0, sections_js_1.knowledgeText)(entry.sections.get(id).parts, selection.mode === 'subtree'))
-                    .join('\n\n')).trim();
-            if (maxChars !== undefined && content.length > maxChars)
-                throw new RangeError('Knowledge selection exceeds its budget');
-            // Preserve the existing opaque snapshot identity format.
-            const identitySelection = selection.mode === 'document'
-                ? selection
-                : { mode: selection.mode, sections: selection.sectionIds };
-            const snapshot = Object.freeze({
-                documentId: read.documentId,
-                selection,
-                revision: entry.document.revision,
-                locale: entry.document.locale,
-                content,
-                id: JSON.stringify([
-                    read.documentId,
-                    entry.document.revision,
-                    entry.document.locale,
-                    identitySelection,
-                ]),
+        read(input, context = {}) {
+            return (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'knowledge', input.documentId, () => {
+                const { read, entry } = resolve(input), raw = read.selection;
+                const selection = raw.mode === 'document'
+                    ? Object.freeze({ mode: 'document' })
+                    : Object.freeze({ mode: raw.mode, sectionIds: Object.freeze([...raw.sectionIds]) });
+                const content = (selection.mode === 'document'
+                    ? (0, sections_js_1.knowledgeText)(entry.document.parts)
+                    : selection.sectionIds
+                        .map((id) => (0, sections_js_1.knowledgeText)(entry.sections.get(id).parts, selection.mode === 'subtree'))
+                        .join('\n\n')).trim();
+                if (maxChars !== undefined && content.length > maxChars)
+                    throw new RangeError('Knowledge selection exceeds its budget');
+                // Preserve the existing opaque snapshot identity format.
+                const identitySelection = selection.mode === 'document'
+                    ? selection
+                    : { mode: selection.mode, sections: selection.sectionIds };
+                const snapshot = Object.freeze({
+                    documentId: read.documentId,
+                    selection,
+                    revision: entry.document.revision,
+                    locale: entry.document.locale,
+                    content,
+                    id: JSON.stringify([
+                        read.documentId,
+                        entry.document.revision,
+                        entry.document.locale,
+                        identitySelection,
+                    ]),
+                });
+                (0, observer_js_1.observeSafely)(observe, snapshot);
+                return snapshot;
             });
-            (0, observer_js_1.observeSafely)(observe, snapshot);
-            return snapshot;
         },
     });
 }

package/dist/cjs/kits/policies.js

@@ -12,6 +12,7 @@ exports.defineRecoveryChain = defineRecoveryChain;
  *
  * Exports: `definePolicySet`, `defineRecoveryChain`, `Policies`, and the policy types.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const catalog_js_1 = require("../utils/catalog.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const rules_js_1 = require("../utils/rules.js");
@@ -70,9 +71,9 @@ function defineRecoveryChain(definitions) {
             },
         });
     });
-    const tryRecover = (input) => {
+    const tryRecover = (input, execution = {}) => {
         for (const policy of catalog) {
-            const result = policy.tryRecover(input);
+            const result = (0, native_sub_flow_js_1.nativeSubFlowSync)(execution, 'recovery', policy.id, () => policy.tryRecover(input));
             if (result.handled)
                 return result;
         }

package/dist/cjs/kits/presentation/outputs.js

@@ -10,6 +10,7 @@ exports.defineOutputCatalog = defineOutputCatalog;
  *
  * Exports: `defineOutputCatalog`, and the output definition/field/provider/result types.
  */
+const native_sub_flow_js_1 = require("../../diagnostics/native-sub-flow.js");
 const schema_adapter_js_1 = require("../../utils/schema-adapter.js");
 const catalog_js_1 = require("../../utils/catalog.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
@@ -324,7 +325,7 @@ function defineOutputCatalog(definitions, options = {}) {
                 throw new TypeError('Use a named output request');
             if (!context?.signal)
                 throw new TypeError('Output composition requires OperationContext');
-            return composeInternal(request.outputId, request.input, context);
+            return (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'output', request.outputId, () => composeInternal(request.outputId, request.input, context));
         },
     });
 }

package/dist/cjs/kits/retrieval.js

@@ -12,6 +12,7 @@ exports.defineRetrieval = defineRetrieval;
  *
  * Exports: `defineRetrieval`, `retrievalQueryKey`, `Retrieval`, and the retrieval port types.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
 const query_key_js_1 = require("../utils/query-key.js");
 const rules_js_1 = require("../utils/rules.js");
@@ -148,7 +149,12 @@ function defineRetrieval(definition) {
         }
         return receipt;
     }
-    return Object.freeze({ id, description, effects, run });
+    return Object.freeze({
+        id,
+        description,
+        effects,
+        run: (input, context) => (0, native_sub_flow_js_1.nativeSubFlowSync)(context, 'retrieval', id, () => run(input, context)),
+    });
 }
 function reason(value, query, context) {
     return () => (typeof value === 'function' ? value(query, context) : value);

package/dist/cjs/kits/tools.js

@@ -92,6 +92,7 @@ class ToolLifecycleRegistry {
         });
         this.diagnostics = this.options.execution?.diagnostics;
         this.invocationPorts = Object.freeze({
+            logger: this.options.logger,
             diagnostics: this.options.diagnostics ?? (() => this.diagnostics),
             signal: this.options.signal,
             journal: this.options.journal,

package/dist/cjs/model/decision-retry.js

@@ -10,6 +10,7 @@ exports.retryMultipleModelCalls = retryMultipleModelCalls;
  *
  * Exports: `retryMultipleModelCalls`.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const errors_js_1 = require("../errors.js");
 /**
  * Retry once when the failure is a rejected multi-call proposal.
@@ -28,6 +29,6 @@ async function retryMultipleModelCalls(request) {
     catch (error) {
         if (!(0, errors_js_1.getErrorInfo)(error).codes.includes('MODEL_MULTIPLE_CALLS'))
             throw error;
-        return request.retry(error);
+        return (0, native_sub_flow_js_1.nativeSubFlowAsync)(request, 'retry', 'MODEL_MULTIPLE_CALLS', () => request.retry(error));
     }
 }

package/dist/cjs/model/runner.js

@@ -13,6 +13,8 @@ exports.ModelRunner = exports.BudgetError = void 0;
  * Exports: `ModelRunner`, the re-exported `BudgetError`, and the runtime/config type
  * re-exports at the bottom of the file.
  */
+const sub_flow_js_1 = require("../diagnostics/sub-flow.js");
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const events_js_1 = require("../execution/events.js");
 const call_budget_js_1 = require("./call-budget.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
@@ -321,6 +323,19 @@ class ModelRunner {
         return snapshot;
     }
     async invoke(request) {
+        const context = typeof request === 'string' ? { logger: undefined, signal: undefined } : request;
+        (0, sub_flow_js_1.requireSubFlowLogger)(context.logger);
+        const callId = (0, invocation_js_1.invocationId)();
+        return (0, native_sub_flow_js_1.nativeSubFlowAsync)({
+            logger: context.logger,
+            signal: (0, cancellation_js_1.combineSignals)(this.signal, context.signal),
+            invocationId: callId,
+        }, 'model', typeof request === 'string'
+            ? defaults_js_1.modelRunnerDefaults.stage
+            : (request.stageId ?? request.prepared?.stageId ?? defaults_js_1.modelRunnerDefaults.stage), () => this.invokeRequest(request, callId));
+    }
+    /** Validate and execute a single request; optional recording is owned by invoke. */
+    async invokeRequest(request, callId) {
         const call = typeof request === 'string' ? { input: request } : request;
         const state = call.prepared === undefined ? undefined : this.preparedCalls.get(call.prepared);
         if (call.prepared !== undefined && (!state || state.used))
@@ -384,7 +399,7 @@ class ModelRunner {
             throw invalid('Prepared model request settings cannot be replaced');
         if (state)
             state.used = true;
-        return this.invokePrepared(stage, input, tokens, transportId, call.diagnostics, prepared, call.signal);
+        return this.invokePrepared(stage, input, tokens, transportId, call.diagnostics, prepared, call.signal, callId);
     }
     /**
      * Acquire the per-runner call slot and execute one call.
@@ -403,7 +418,7 @@ class ModelRunner {
      * @returns The parsed result with invocation metadata.
      * @throws Error When a call is already in flight or the request capacity is exhausted.
      */
-    async invokePrepared(stage, input, tokens, transportId, diagnostics = this.ports.diagnostics, prepared, requestSignal) {
+    async invokePrepared(stage, input, tokens, transportId, diagnostics = this.ports.diagnostics, prepared, requestSignal, callId = (0, invocation_js_1.invocationId)()) {
         const configuredRun = this.ports.diagnostics?.identity?.runId, selectedRun = diagnostics?.identity?.runId;
         if (configuredRun && selectedRun && configuredRun !== selectedRun)
             throw (0, errors_js_1.recordErrorContext)(new TypeError('Model observation parent belongs to a different run'), { stageId: stage, codes: ['MODEL_CONFIG'], isRetryable: false });
@@ -413,7 +428,7 @@ class ModelRunner {
         this.requestGate.active++;
         let failure;
         try {
-            return await this.execute(stage, input, tokens, transportId, (0, cancellation_js_1.combineSignals)(this.signal, requestSignal), diagnostics, prepared);
+            return await this.execute(stage, input, tokens, transportId, (0, cancellation_js_1.combineSignals)(this.signal, requestSignal), diagnostics, prepared, callId);
         }
         catch (error) {
             failure = (0, errors_js_1.recordErrorContext)(error, { stageId: stage });
@@ -444,8 +459,8 @@ class ModelRunner {
      * @returns The parsed result with invocation metadata.
      * @throws Error or ValidationError from any phase, decorated with stage context.
      */
-    async execute(stage, input, tokens, transportId, signal, parentDiagnostics = this.ports.diagnostics, prepared) {
-        const id = (0, invocation_js_1.invocationId)(), startedAtMs = Date.now();
+    async execute(stage, input, tokens, transportId, signal, parentDiagnostics = this.ports.diagnostics, prepared, callId = (0, invocation_js_1.invocationId)()) {
+        const id = callId, startedAtMs = Date.now();
         this.activeCall = undefined;
         const invocationDiagnostics = parentDiagnostics?.child(id, {
             invocationId: id,

package/dist/cjs/structs/execution/workflow-views.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/support/context/nodes.js

@@ -14,6 +14,7 @@ exports.createContextReductionNode = createContextReductionNode;
  * Main exports: `createContextProcessingNode`, `createContextSelectionNode`,
  * `createContextReductionNode` and their result/definition types.
  */
+const native_sub_flow_js_1 = require("../../diagnostics/native-sub-flow.js");
 const processing_js_1 = require("./processing.js");
 const defaults_js_1 = require("../../model/defaults.js");
 const synchronous_js_1 = require("../../utils/synchronous.js");
@@ -129,53 +130,55 @@ function contextNode(definition, execute) {
         onErrorRouteId: definition.onErrorRouteId,
         routes: definition.routes,
         async run(state, context) {
-            // The node timeout is an additional bound; parent cancellation still wins.
-            const signal = (0, cancellation_js_1.combineSignals)(context.signal, AbortSignal.timeout(timeoutMs));
-            const prepared = selectPrepared
-                ? selectPrepared(state, context)
-                : context.model.prepare(typeof request === 'function' ? request(state, context) : request);
-            const input = (0, synchronous_js_1.synchronous)(plan(state, context), 'Context plans must be synchronous');
-            // An empty measurement reports the allowance left after transport, instruction and schema
-            // overhead, so processing must fit inside whichever limit is tighter.
-            const overhead = prepared.measure([]);
-            const fullLimit = Math.min(input.maxInputChars, overhead.maxInputChars);
-            const bodyLimit = fullLimit;
-            (0, rules_js_1.breakWhile)(bodyLimit < 1, 'No input capacity for context');
-            const work = (0, processing_js_1.beginContextProcessing)({
-                fragments: input.fragments,
-                additionalMessages: input.additionalMessages,
-                originalFragments: input.originalFragments,
-                mutableFragmentIds: input.mutableFragmentIds,
-                maxInputChars: bodyLimit,
-            }, policy, {
-                stageId: prepared.stageId,
-                signal,
-                diagnostics: context.diagnostics,
-                compressors,
-                selectors,
-                // Read lazily so handlers see the live budget rather than the value at preparation.
-                remainingCalls: () => prepared.remainingCalls,
-                callModel: (options) => context.model.invoke({
-                    ...options,
-                    modelId: options.modelId ?? prepared.modelId,
+            return (0, native_sub_flow_js_1.nativeSubFlowAsync)(context, 'context', definition.id, async () => {
+                // The node timeout is an additional bound; parent cancellation still wins.
+                const signal = (0, cancellation_js_1.combineSignals)(context.signal, AbortSignal.timeout(timeoutMs));
+                const prepared = selectPrepared
+                    ? selectPrepared(state, context)
+                    : context.model.prepare(typeof request === 'function' ? request(state, context) : request);
+                const input = (0, synchronous_js_1.synchronous)(plan(state, context), 'Context plans must be synchronous');
+                // An empty measurement reports the allowance left after transport, instruction and schema
+                // overhead, so processing must fit inside whichever limit is tighter.
+                const overhead = prepared.measure([]);
+                const fullLimit = Math.min(input.maxInputChars, overhead.maxInputChars);
+                const bodyLimit = fullLimit;
+                (0, rules_js_1.breakWhile)(bodyLimit < 1, 'No input capacity for context');
+                const work = (0, processing_js_1.beginContextProcessing)({
+                    fragments: input.fragments,
+                    additionalMessages: input.additionalMessages,
+                    originalFragments: input.originalFragments,
+                    mutableFragmentIds: input.mutableFragmentIds,
+                    maxInputChars: bodyLimit,
+                }, policy, {
+                    stageId: prepared.stageId,
                     signal,
-                }),
-                ...(overhead.counterId
-                    ? {
-                        tokenBudget: {
-                            counterId: overhead.counterId,
-                            inputLimit: overhead.inputTokenLimit,
-                            measure: (messages) => prepared.measure(messages).inputTokens,
-                        },
-                    }
-                    : {}),
+                    diagnostics: context.diagnostics,
+                    compressors,
+                    selectors,
+                    // Read lazily so handlers see the live budget rather than the value at preparation.
+                    remainingCalls: () => prepared.remainingCalls,
+                    callModel: (options) => context.model.invoke({
+                        ...options,
+                        modelId: options.modelId ?? prepared.modelId,
+                        signal,
+                    }),
+                    ...(overhead.counterId
+                        ? {
+                            tokenBudget: {
+                                counterId: overhead.counterId,
+                                inputLimit: overhead.inputTokenLimit,
+                                measure: (messages) => prepared.measure(messages).inputTokens,
+                            },
+                        }
+                        : {}),
+                });
+                context.report({ payload: { phase: 'processing', fragmentCount: input.fragments.length } });
+                const result = await execute(work, prepared, fullLimit, state, context);
+                // Never report or commit a result produced after cancellation.
+                signal.throwIfAborted();
+                context.report({ payload: { phase: 'processed', report: work.report } });
+                return (0, synchronous_js_1.synchronous)(update(result, state), 'Context node updates must be synchronous');
             });
-            context.report({ payload: { phase: 'processing', fragmentCount: input.fragments.length } });
-            const result = await execute(work, prepared, fullLimit, state, context);
-            // Never report or commit a result produced after cancellation.
-            signal.throwIfAborted();
-            context.report({ payload: { phase: 'processed', report: work.report } });
-            return (0, synchronous_js_1.synchronous)(update(result, state), 'Context node updates must be synchronous');
         },
     };
 }

package/dist/cjs/support/context/processing.js

@@ -26,6 +26,7 @@ exports.processContext = processContext;
  * `finishContextProcessing` (staged runs), the policy/reduction catalogs and the individual
  * validation, measurement and reduction helpers used by workflow nodes.
  */
+const native_sub_flow_js_1 = require("../../diagnostics/native-sub-flow.js");
 const snapshot_js_1 = require("./snapshot.js");
 const audit_js_1 = require("../../context/audit.js");
 const history_js_1 = require("./history.js");
@@ -610,7 +611,9 @@ function finishContextProcessing(state) {
  * @throws {BudgetError} When a handler exhausts its call allowance.
  */
 async function processContext(plan, policy, ports) {
-    const state = beginContextProcessing(plan, policy, ports);
-    await exports.contextPolicyCatalog[policy.mode].run(state);
-    return finishContextProcessing(state);
+    return (0, native_sub_flow_js_1.nativeSubFlowAsync)(ports, 'context', policy.mode, async () => {
+        const state = beginContextProcessing(plan, policy, ports);
+        await exports.contextPolicyCatalog[policy.mode].run(state);
+        return finishContextProcessing(state);
+    });
 }

package/dist/cjs/utils/invocation.js

@@ -46,6 +46,7 @@ function toolInvocation(request, arity) {
         throw new TypeError('Use one tool request with toolId and input');
     }
     return {
+        logger: request.logger,
         toolId: request.toolId,
         input: request.input,
         diagnostics: request.diagnostics,

package/dist/esm/capabilities/invocation.js

@@ -8,6 +8,7 @@
  *
  * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { invocationId } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
 import { diagnosticError } from '../diagnostics/index.js';
@@ -28,12 +29,30 @@ import { NodeReports } from '../execution/reporting.js';
  *   signal checks.
  */
 export function executeInvocation(invocation, input, context, ports = {}) {
+    let logger;
+    try {
+        logger = ports.logger?.(context);
+    }
+    catch {
+        /* Optional recording cannot block execution. */
+    }
+    const callId = invocationId();
+    return nativeSubFlowSync({
+        logger,
+        invocationId: callId,
+        get signal() {
+            return ports.signal?.(context);
+        },
+    }, 'invocation', invocation.id, (scopedLogger) => runInvocation(invocation, input, context, ports, scopedLogger, callId));
+}
+/** Execute the existing synchronous lifecycle without changing journal or error precedence. */
+function runInvocation(invocation, input, context, ports, logger, executionId = invocationId()) {
     const toolId = invocation.id;
     // Identify the call before touching the ports: journal and diagnostics records cannot be
     // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
-    const journal = ports.journal?.(context), id = invocationId(), startedAtMs = Date.now();
+    const journal = ports.journal?.(context), id = executionId, startedAtMs = Date.now();
     const diagnostics = ports.diagnostics?.(context)?.child(id, {
         invocationId: id,
         nodeRole: 'invocation',
@@ -64,6 +83,7 @@ export function executeInvocation(invocation, input, context, ports = {}) {
         // The helper rejects a promise and drains its rejection: a handler that turns async must
         // fail here instead of escaping as an unhandled rejection.
         synchronous(invocation.call(input, context, {
+            logger,
             mode: 'sync',
             invocationId: id,
             signal: signal ?? new AbortController().signal,

package/dist/esm/capabilities/tool-runtime.js

@@ -27,7 +27,14 @@ function execute(definition, input, context, execution) {
         signal.throwIfAborted();
         return value;
     };
-    const operation = { app: context, signal, diagnostics, report, createSubFlowLogger };
+    const operation = {
+        app: context,
+        signal,
+        diagnostics,
+        logger: execution.logger,
+        report,
+        createSubFlowLogger,
+    };
     const authorized = (result) => {
         assertion(result, 'Tool authorization must return void');
         signal.throwIfAborted();

package/dist/esm/capabilities/tools.js

@@ -11,6 +11,7 @@
  *
  * Exports: `ToolRegistry`, `executeInvocation`, and the tool/invocation contracts.
  */
+import { nativeSubFlowSync, nativeSubFlowAsync } from '../diagnostics/native-sub-flow.js';
 import { executionEvents } from '../execution/events.js';
 import { invocationId as nextInvocationId, invocationResult, toolInvocation, } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
@@ -116,7 +117,8 @@ export class ToolRegistry {
      */
     invoke(request) {
         const call = toolInvocation(request, arguments.length);
-        return this.execute(call.toolId, call.input, false, call.diagnostics, call.signal);
+        const callId = nextInvocationId();
+        return nativeSubFlowSync({ ...call, signal: combineSignals(this.ports.signal, call.signal), invocationId: callId }, 'tool', call.toolId, (scopedLogger) => this.execute(call.toolId, call.input, false, call.diagnostics, call.signal, scopedLogger, callId));
     }
     /**
      * Invoke a registered tool and await its result.
@@ -128,7 +130,8 @@ export class ToolRegistry {
      */
     async invokeAsync(request) {
         const call = toolInvocation(request, arguments.length);
-        return (await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal));
+        const callId = nextInvocationId();
+        return nativeSubFlowAsync({ ...call, signal: combineSignals(this.ports.signal, call.signal), invocationId: callId }, 'tool', call.toolId, (scopedLogger) => this.execute(call.toolId, call.input, true, call.diagnostics, call.signal, scopedLogger, callId));
     }
     /**
      * Run one call: validate, parse input, execute, parse output, then record the outcome.
@@ -140,7 +143,7 @@ export class ToolRegistry {
      * @param requestSignal Per-call signal, combined with the request-lifetime signal.
      * @returns The frozen result on success; every failure path throws.
      */
-    execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal) {
+    execute(name, input, asynchronous, parentDiagnostics = this.diagnostics, requestSignal, logger, callId = nextInvocationId()) {
         // A tool call stays inside the run that invoked it: mixing two diagnostic trees would
         // produce records with two parents and break run-scoped correlation.
         if (this.diagnostics?.identity?.runId &&
@@ -152,7 +155,7 @@ export class ToolRegistry {
             throw this.ports.unavailable?.(name) ?? new Error(`Tool is not registered: ${name}`);
         // Either signal may cancel the call; combining them keeps both lifetimes effective.
         const signal = combineSignals(this.ports.signal, requestSignal);
-        const invocationId = nextInvocationId();
+        const invocationId = callId;
         const diagnostics = parentDiagnostics?.child(invocationId, {
             invocationId,
             nodeRole: 'invocation',
@@ -190,24 +193,15 @@ export class ToolRegistry {
         };
         const succeed = (result) => {
             signal.throwIfAborted();
-            let debug = reports.debug();
             if (tool.debugSteps && diagnostics?.enabled('tool.result', 'content')) {
                 try {
-                    debug = reports.debug({
-                        subs: synchronous(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous'),
-                    });
+                    synchronous(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous');
                 }
-                catch (error) {
-                    // Debug material is optional evidence: it must not turn a successful tool call into
-                    // a failure. Defer the error until a consumer actually asks for the sub-steps.
-                    debug = {
-                        usedModel: reports.debug().usedModel,
-                        subSteps: () => {
-                            throw error;
-                        },
-                    };
+                catch {
+                    diagnostics?.emit('node.progress', () => ({ reportError: 'INVALID_NODE_REPORT' }));
                 }
             }
+            const debug = reports.debug();
             signal.throwIfAborted();
             reports.close();
             diagnostics?.emit('tool.result', () => ({
@@ -277,6 +271,7 @@ export class ToolRegistry {
             signal.throwIfAborted();
             phase = 'execute';
             const value = tool.execute(parsed, {
+                logger,
                 mode: asynchronous ? 'async' : 'sync',
                 invocationId,
                 signal,

package/dist/esm/diagnostics/index.d.ts

@@ -1,6 +1,7 @@
 import type { DiagnosticContext, CreateDiagnosticsOptions } from '../structs/diagnostics.js';
 export * from '../structs/diagnostics.js';
 export * from './catalog.js';
+export { SubFlowLogger, ScopedSubFlowLogger } from './sub-flow.js';
 export type * from '../structs/debug.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
 /**