@jangts/agent-core 0.2.5 → 0.3.6

package/dist/esm/execution/workflow-chain.js

@@ -0,0 +1,208 @@
+/** Read-side projection of captured workflow facts; never dispatches or reconstructs topology. */
+import { normalizeDiagnosticEvent } from '../diagnostics/index.js';
+import { freezeView } from './workflow-graph.js';
+const lifecycleTypes = new Set(['enter', 'transition', 'complete', 'error']);
+/** Aggregate main visits by span and keep raw subflow records in their own append order. */
+export function projectWorkflowChain(workflowId, runId, input) {
+    const coverage = structuredClone(input.coverage);
+    const issues = [...coverage.issues];
+    const issue = (code, spanId, eventId) => issues.push({ code, spanId, eventId });
+    const events = input.events
+        .map(normalizeDiagnosticEvent)
+        .filter((e) => e.runId === runId)
+        .sort((a, b) => a.producerSequence - b.producerSequence);
+    const visits = new Map();
+    const ledgers = new Map();
+    const transitions = [];
+    const seen = new Map();
+    for (const raw of events) {
+        const payload = raw.payload && typeof raw.payload === 'object'
+            ? raw.payload
+            : {};
+        const candidate = payload.event;
+        const fact = raw.type === 'workflow.event' && candidate && typeof candidate === 'object'
+            ? candidate
+            : undefined;
+        const belongs = fact?.workflowId === workflowId ||
+            (raw.nodeRole === 'workflow-node' && raw.definitionId === workflowId);
+        if (!belongs || (raw.nodeRole !== undefined && raw.nodeRole !== 'workflow-node'))
+            continue;
+        if (raw.type === 'workflow.event' && !fact) {
+            issue('invalid-workflow-event', raw.spanId, raw.eventId);
+            continue;
+        }
+        const identity = JSON.stringify(raw);
+        if (seen.has(raw.eventId)) {
+            if (seen.get(raw.eventId) !== identity)
+                issue('conflicting-event', raw.spanId, raw.eventId);
+            continue;
+        }
+        seen.set(raw.eventId, identity);
+        if (fact &&
+            (!lifecycleTypes.has(fact.type) ||
+                fact.eventId !== raw.eventId ||
+                fact.workflowId !== workflowId ||
+                (raw.workflowInvocationId !== undefined &&
+                    fact.workflowInvocationId !== raw.workflowInvocationId) ||
+                [
+                    'targetSpanId',
+                    'targetNodeId',
+                    'routeId',
+                    'conditionId',
+                    'errorCode',
+                    'errorEventId',
+                ].some((key) => {
+                    const value = fact[key];
+                    return value !== undefined && typeof value !== 'string';
+                }) ||
+                (fact.route !== undefined && (!Number.isSafeInteger(fact.route) || fact.route < 0)) ||
+                (fact.durationMs !== undefined &&
+                    (!Number.isFinite(fact.durationMs) || fact.durationMs < 0)) ||
+                !Number.isSafeInteger(fact.roundIndex) ||
+                typeof fact.workflowInvocationId !== 'string' ||
+                fact.nodeId !== raw.nodeId ||
+                (fact.spanId !== undefined && fact.spanId !== raw.spanId) ||
+                (fact.runId !== undefined && fact.runId !== runId))) {
+            issue('invalid-workflow-event', raw.spanId, raw.eventId);
+            continue;
+        }
+        if (!raw.nodeId) {
+            issue('missing-node-id', raw.spanId, raw.eventId);
+            continue;
+        }
+        let visit = visits.get(raw.spanId);
+        if (!visit) {
+            visit = {
+                spanId: raw.spanId,
+                nodeId: raw.nodeId,
+                workflowInvocationId: raw.workflowInvocationId ?? fact?.workflowInvocationId,
+                definitionRevision: raw.definitionRevision,
+                name: raw.nodeName,
+                description: raw.nodeDescription,
+                kind: raw.nodeKind,
+                roundIndex: fact?.roundIndex,
+                firstEventSequence: raw.producerSequence,
+                lastEventSequence: raw.producerSequence,
+                status: 'unknown',
+                events: [],
+                subflow: [],
+            };
+            visits.set(raw.spanId, visit);
+            ledgers.set(raw.spanId, new Map());
+        }
+        if (visit.nodeId !== raw.nodeId ||
+            visit.workflowInvocationId !== (raw.workflowInvocationId ?? fact?.workflowInvocationId)) {
+            issue('conflicting-span', raw.spanId, raw.eventId);
+            continue;
+        }
+        visit.lastEventSequence = raw.producerSequence;
+        if (raw.usedModel !== undefined)
+            visit.usedModel = raw.usedModel;
+        if (raw.subStepsDropped || raw.subStepsTruncated)
+            issue('subflow-truncated', raw.spanId, raw.eventId);
+        const ledger = ledgers.get(raw.spanId);
+        for (const step of raw.subSteps ?? []) {
+            const previous = ledger.get(step.stepId);
+            if (!previous)
+                ledger.set(step.stepId, structuredClone(step));
+            else if (JSON.stringify({ ...previous, sourceEventId: undefined, producerSequence: undefined }) !==
+                JSON.stringify(step))
+                issue('conflicting-subflow', raw.spanId, raw.eventId);
+        }
+        const progress = payload.subStep;
+        if (raw.type === 'node.progress' && progress) {
+            const record = progress.stepId ? ledger.get(progress.stepId) : undefined;
+            if (record) {
+                ledger.set(record.stepId, {
+                    ...record,
+                    sourceEventId: raw.eventId,
+                    producerSequence: raw.producerSequence,
+                });
+            }
+            else if (typeof progress.stepId === 'string' && Number.isSafeInteger(progress.sequence)) {
+                ledger.set(progress.stepId, {
+                    ...structuredClone(progress),
+                    origin: 'reported',
+                    sourceEventId: raw.eventId,
+                    producerSequence: raw.producerSequence,
+                });
+            }
+            else
+                issue('invalid-subflow-progress', raw.spanId, raw.eventId);
+            continue;
+        }
+        if (fact || raw.type === 'node.progress') {
+            visit.events.push({
+                eventId: raw.eventId,
+                producerSequence: raw.producerSequence,
+                occurredAtMs: raw.occurredAtMs,
+                type: fact?.type ?? 'progress',
+                phase: fact?.phase,
+                routeId: fact?.routeId,
+                conditionId: fact?.conditionId,
+                errorCode: fact?.errorCode,
+                errorEventId: fact?.errorEventId,
+                payload: payload.payload,
+            });
+        }
+        if (!fact)
+            continue;
+        visit.roundIndex ??= fact.roundIndex;
+        if (fact.type === 'enter') {
+            visit.enteredAtMs = raw.occurredAtMs;
+            visit.status = 'running';
+        }
+        if (fact.type === 'error')
+            visit.status =
+                fact.errorCode === 'CANCELLED' || fact.errorCode === 'TIMEOUT' ? 'cancelled' : 'error';
+        if (fact.type !== 'enter') {
+            visit.endedAtMs = raw.occurredAtMs;
+            visit.durationMs = fact.durationMs;
+            if (fact.type !== 'error' && visit.status !== 'error' && visit.status !== 'cancelled')
+                visit.status = 'success';
+        }
+        if (fact.type === 'transition' ||
+            fact.type === 'complete' ||
+            (fact.type === 'error' && fact.targetNodeId !== undefined))
+            transitions.push({
+                eventId: raw.eventId,
+                producerSequence: raw.producerSequence,
+                occurredAtMs: raw.occurredAtMs,
+                type: fact.type === 'complete' ? 'complete' : 'transition',
+                sourceSpanId: raw.spanId,
+                targetSpanId: fact.targetSpanId,
+                targetNodeId: fact.targetNodeId,
+                routeOrder: fact.route,
+                routeId: fact.routeId,
+                conditionId: fact.conditionId,
+                errorEventId: fact.type === 'error' ? raw.eventId : fact.errorEventId,
+            });
+    }
+    if (!visits.size)
+        throw new RangeError(`No captured workflow visits: ${workflowId} / ${runId}`);
+    for (const visit of visits.values()) {
+        visit.subflow = [...ledgers.get(visit.spanId).values()].sort((a, b) => a.sequence - b.sequence);
+        if (visit.enteredAtMs === undefined)
+            issue('missing-enter', visit.spanId);
+        if (visit.endedAtMs === undefined && coverage.complete === true) {
+            visit.status = 'unknown';
+            issue('missing-exit', visit.spanId);
+        }
+        for (const step of visit.subflow)
+            if (step.operation === undefined ||
+                step.revision === undefined ||
+                step.createdAtMs === undefined)
+                issue('historical-subflow-fields', visit.spanId);
+    }
+    for (const edge of transitions)
+        if (edge.targetSpanId && !visits.has(edge.targetSpanId))
+            issue('missing-target-enter', edge.targetSpanId, edge.eventId);
+    return freezeView({
+        schemaVersion: 1,
+        workflowId,
+        runId,
+        nodes: [...visits.values()],
+        transitions,
+        coverage: { ...coverage, complete: issues.length ? false : coverage.complete, issues },
+    });
+}

package/dist/esm/execution/workflow-graph.d.ts

@@ -0,0 +1,7 @@
+/** Project the validated catalog to pure topology without evaluating route conditions. */
+import type { WorkflowNode } from '../structs/execution/workflow.js';
+import type { WorkflowGraph } from '../structs/execution/workflow-views.js';
+/** Edge identity depends on topology, never on a route label or callback. */
+export declare function projectWorkflowGraph<S, R, C>(workflowId: string, entryNodeId: string, revision: string | undefined, definitions: readonly WorkflowNode<S, R, C>[]): WorkflowGraph;
+/** Freeze detached JSON data recursively so callers cannot alter another consumer's view. */
+export declare function freezeView<T>(value: T): T;

package/dist/esm/execution/workflow-graph.js

@@ -0,0 +1,68 @@
+/** Edge identity depends on topology, never on a route label or callback. */
+export function projectWorkflowGraph(workflowId, entryNodeId, revision, definitions) {
+    const edges = new Map();
+    const nodes = definitions.map((node, order) => {
+        const edgeFor = (kind, targetNodeId) => {
+            const id = JSON.stringify([node.id, kind, targetNodeId ?? null]);
+            if (!edges.has(id))
+                edges.set(id, {
+                    id,
+                    kind,
+                    sourceNodeId: node.id,
+                    targetNodeId,
+                    routeOrders: [],
+                    ...(kind === 'error' ? { errorRouteId: node.onErrorRouteId } : {}),
+                });
+            return edges.get(id);
+        };
+        const routes = node.routes.map((route, order) => {
+            const edge = edgeFor(route.complete ? 'complete' : 'transition', route.targetNodeId);
+            edge.routeOrders.push(order);
+            return {
+                order,
+                routeId: route.id,
+                description: route.description,
+                conditional: !!route.when,
+                conditionId: route.conditionId,
+                edgeId: edge.id,
+            };
+        });
+        if (node.onErrorNodeId)
+            edgeFor('error', node.onErrorNodeId);
+        return {
+            id: node.id,
+            name: node.name ?? node.id,
+            description: node.description,
+            order,
+            startsRound: !!node.startsRound,
+            requires: [...(node.requires ?? [])],
+            provides: [...(node.provides ?? [])],
+            routes,
+            incomingEdgeIds: [],
+            outgoingEdgeIds: [],
+        };
+    });
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    for (const edge of edges.values()) {
+        byId.get(edge.sourceNodeId).outgoingEdgeIds.push(edge.id);
+        if (edge.targetNodeId)
+            byId.get(edge.targetNodeId).incomingEdgeIds.push(edge.id);
+    }
+    return freezeView({
+        schemaVersion: 1,
+        workflowId,
+        revision,
+        entryNodeId,
+        nodes,
+        edges: [...edges.values()],
+    });
+}
+/** Freeze detached JSON data recursively so callers cannot alter another consumer's view. */
+export function freezeView(value) {
+    if (value && typeof value === 'object') {
+        for (const child of Object.values(value))
+            freezeView(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/esm/execution/workflow.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowGraph, WorkflowChain, WorkflowChainSource } from '../structs/execution/workflow-views.js';
 import type { AgentWorkflowDefinition, WorkflowExtension, WorkflowNode } from '../structs/execution/workflow.js';
 /**
  * Executable catalog: validate references and bounded cycles before any handler runs.
@@ -14,6 +15,7 @@ export declare class AgentWorkflow<State, Result, Runtime = undefined> {
     readonly revision?: string;
     /** Optional result guard; when present it must return exactly true. */
     readonly isResult?: (result: Result) => boolean;
+    private readonly chainSource?;
     private readonly nodes;
     /**
      * Build and validate a workflow.
@@ -38,6 +40,10 @@ export declare class AgentWorkflow<State, Result, Runtime = undefined> {
      * @throws TypeError When an override names an unknown node or a node is invalid.
      */
     add(extension: WorkflowExtension<State, Result, Runtime> | AgentWorkflow<State, Result, Runtime>, routes?: WorkflowExtension<State, Result, Runtime>['routes']): AgentWorkflow<State, Result, Runtime>;
+    /** Export topology from the registered snapshot without executing callbacks. */
+    toGraph(): WorkflowGraph;
+    /** Read an authorized run through the bound App source, or an explicit per-call source. */
+    toChain(runId: string, source?: WorkflowChainSource | undefined): Promise<WorkflowChain>;
     /**
      * Look up a node that must exist.
      *

package/dist/esm/execution/workflow.js

@@ -1,3 +1,16 @@
+/**
+ * Validated workflow catalog and round accounting.
+ *
+ * A workflow is declared as data (nodes plus routes) and validated before any handler
+ * runs: references must resolve, every node must be reachable from the entry, and every
+ * cycle must cross a round boundary so the engine's budget stays authoritative. This
+ * module owns the catalog; `engine.ts` owns traversal and execution.
+ *
+ * Exports: `AgentWorkflow`, `defineWorkflow`, `AttemptBudget`, the re-exported
+ * `requireWorkflowValue` and `route`, and the workflow contract types.
+ */
+import { projectWorkflowGraph } from './workflow-graph.js';
+import { projectWorkflowChain } from './workflow-chain.js';
 /**
  * Derive unique route ids for one node.
  *
@@ -51,6 +64,7 @@ export class AgentWorkflow {
     revision;
     /** Optional result guard; when present it must return exactly true. */
     isResult;
+    chainSource;
     nodes = new Map();
     /**
      * Build and validate a workflow.
@@ -68,6 +82,7 @@ export class AgentWorkflow {
         if (!definition.id?.trim() || !entry?.trim() || !definition.nodes.length) {
             throw new TypeError('Invalid workflow');
         }
+        this.chainSource = definition.chainSource?.bind(definition);
         this.id = definition.id;
         this.entryNodeId = entry;
         this.revision = definition.revision;
@@ -104,6 +119,7 @@ export class AgentWorkflow {
         return new AgentWorkflow({
             id: this.id,
             revision: patch.revision,
+            chainSource: this.chainSource,
             entryNodeId: this.entryNodeId,
             isResult: this.isResult,
             nodes: nodes.map((node) => ({
@@ -121,6 +137,18 @@ export class AgentWorkflow {
             })),
         });
     }
+    /** Export topology from the registered snapshot without executing callbacks. */
+    toGraph() {
+        return projectWorkflowGraph(this.id, this.entryNodeId, this.revision, this.definitions);
+    }
+    /** Read an authorized run through the bound App source, or an explicit per-call source. */
+    async toChain(runId, source = this.chainSource) {
+        if (!runId.trim())
+            throw new TypeError('A runId is required');
+        if (!source)
+            throw new TypeError('Workflow chainSource is not configured');
+        return projectWorkflowChain(this.id, runId, await source(runId));
+    }
     /**
      * Look up a node that must exist.
      *
@@ -203,25 +231,26 @@ export class AgentWorkflow {
      * @throws TypeError When the node, a route or a state contract is invalid.
      */
     register(node) {
+        const declaredRoutes = node.routes;
         if (!node.id?.trim() ||
             !node.description?.trim() ||
             this.nodes.has(node.id) ||
-            !node.routes.length ||
+            !declaredRoutes.length ||
             (node.run !== undefined && typeof node.run !== 'function')) {
             throw new TypeError('Invalid or duplicate workflow node');
         }
         validateNodeFields(node);
         if (node.onErrorRouteId !== undefined && (!node.onErrorRouteId.trim() || !node.onErrorNodeId))
             throw new TypeError(`Invalid workflow error route identity: ${node.id}`);
-        const ids = assignRouteIds(node.routes);
-        for (const [index, route] of node.routes.entries()) {
+        const ids = assignRouteIds(declaredRoutes);
+        for (const [index, route] of declaredRoutes.entries()) {
             if ('to' in route ||
                 (route.id !== undefined && !route.id.trim()) ||
                 (route.conditionId !== undefined && (!route.conditionId.trim() || !route.when)))
                 throw new TypeError(`Invalid workflow route identity: ${node.id}`);
             const hasTarget = typeof route.targetNodeId === 'string';
             const hasCompletion = typeof route.complete === 'function';
-            const shadowsFollowingRoutes = !route.when && index !== node.routes.length - 1;
+            const shadowsFollowingRoutes = !route.when && index !== declaredRoutes.length - 1;
             if (hasTarget === hasCompletion ||
                 shadowsFollowingRoutes ||
                 (route.when !== undefined && typeof route.when !== 'function')) {
@@ -235,7 +264,7 @@ export class AgentWorkflow {
                 throw new TypeError(`Invalid workflow state contract: ${node.id}`);
             }
         }
-        const routes = Object.freeze(node.routes.map((route, index) => {
+        const routes = Object.freeze(declaredRoutes.map((route, index) => {
             const id = ids[index];
             const conditionId = route.conditionId?.replace(/\{(nid|rid)\}/g, (_, key) => {
                 if (key === 'nid')
@@ -258,7 +287,6 @@ export class AgentWorkflow {
         // only when it declares it explicitly.
         const startsRound = node.startsRound ?? (node.id === this.entryNodeId ? true : undefined);
         this.nodes.set(node.id, Object.freeze({
-            ...node,
             id: node.id,
             description: node.description,
             name: node.name,

package/dist/esm/kits/aggregation.d.ts

@@ -34,7 +34,7 @@ export declare function defineQueryAggregation<Input, Item, Context>(options: Qu
      * @param context - Host context forwarded unchanged to `execute`, `key` and `merge`.
      * @returns The merged items and their count.
      */
-    collect(inputs: readonly Input[], context: Context): {
+    collect(inputs: readonly Input[], context: Context, execution?: Partial<import("../structs/common.js").ExecutionContext>): {
         total: number;
         items: Item[];
     };

package/dist/esm/kits/aggregation.js

@@ -6,6 +6,7 @@
  *
  * Exports: `mergeByKey`, `defineQueryAggregation`, `Aggregation`.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { synchronous } from '../utils/synchronous.js';
 /**
  * Merge duplicates without moving their first position; selection policy remains host-owned.
@@ -51,21 +52,23 @@ export function defineQueryAggregation(options) {
          * @param context - Host context forwarded unchanged to `execute`, `key` and `merge`.
          * @returns The merged items and their count.
          */
-        collect(inputs, context) {
-            const rows = [], merged = new Map();
-            for (const input of inputs)
-                for (const item of synchronous(execute(input, context), 'Query aggregation must be synchronous')) {
-                    if (!keyFor) {
-                        rows.push(item);
-                        continue;
+        collect(inputs, context, execution = {}) {
+            return nativeSubFlowSync(execution, 'aggregation', 'query-aggregation', () => {
+                const rows = [], merged = new Map();
+                for (const input of inputs)
+                    for (const item of synchronous(execute(input, context), 'Query aggregation must be synchronous')) {
+                        if (!keyFor) {
+                            rows.push(item);
+                            continue;
+                        }
+                        const key = synchronous(keyFor(item, input, context), 'Aggregation keys must be synchronous');
+                        merged.set(key, merge
+                            ? synchronous(merge(item, merged.get(key), input, context), 'Aggregation merge must be synchronous')
+                            : item);
                     }
-                    const key = synchronous(keyFor(item, input, context), 'Aggregation keys must be synchronous');
-                    merged.set(key, merge
-                        ? synchronous(merge(item, merged.get(key), input, context), 'Aggregation merge must be synchronous')
-                        : item);
-                }
-            const items = keyFor ? [...merged.values()] : rows;
-            return { total: items.length, items };
+                const items = keyFor ? [...merged.values()] : rows;
+                return { total: items.length, items };
+            });
         },
     });
 }

package/dist/esm/kits/answering/checks.js

@@ -6,6 +6,7 @@
  *
  * Exports: `defineAnswerCheckCatalog`, and the answer checker types.
  */
+import { nativeSubFlowSync } from '../../diagnostics/native-sub-flow.js';
 import { snapshotAnswerCheck } from './check-result.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { synchronous } from '../../utils/synchronous.js';
@@ -37,7 +38,7 @@ export function defineAnswerCheckCatalog(definitions) {
                 throw new TypeError('Duplicate selected check id');
             for (const id of request.checkIds) {
                 context.signal.throwIfAborted();
-                const result = snapshotAnswerCheck(synchronous(checks.require(id).check(value, context), 'Answer checkers must be synchronous'), id);
+                const result = nativeSubFlowSync(context, 'check', id, () => snapshotAnswerCheck(synchronous(checks.require(id).check(value, context), 'Answer checkers must be synchronous'), id));
                 context.signal.throwIfAborted();
                 if (Object.hasOwn(result, 'value'))
                     value = result.value;

package/dist/esm/kits/answering/flow.js

@@ -7,6 +7,7 @@
  *
  * Exports: `defineAnswerFlow`, and the answer flow/item/result/check types.
  */
+import { nativeSubFlowAsync } from '../../diagnostics/native-sub-flow.js';
 import { booleanResult, synchronous } from '../../utils/synchronous.js';
 import { awaitWithSignal } from '../../utils/cancellation.js';
 import { AgentCoreEngine } from '../../execution/engine.js';
@@ -279,27 +280,29 @@ export function defineAnswerFlow(definition) {
          *   exhausted without a final result.
          */
         async run(request, context) {
-            context.signal.throwIfAborted();
-            validateAnswerBatch(request.inputIds, request.items, maxItems);
-            const cells = request.items.map((item) => ({
-                item: Object.freeze({
-                    id: item.id,
-                    data: item.data,
-                    sourceStatus: item.sourceStatus,
-                    inputIds: Object.freeze([...item.inputIds]),
-                }),
-                hasValue: false,
-                local: { status: 'not-run', issues: [] },
-                review: { status: 'not-run', issues: [] },
-                knownReviewFailure: false,
-            }));
-            return new AgentCoreEngine({
-                maxRounds: maxRepairs + 1,
-                errors: { exhausted: () => new TypeError('Answer flow exhausted') },
-                execution: { signal: context.signal, diagnostics: context.diagnostics },
-            })
-                .bindWorkflow(workflow, context.app)
-                .run({ cells, pending: [], repairBudget: new AttemptBudget(maxRepairs) });
+            return nativeSubFlowAsync(context, 'answer', 'answer-flow', async () => {
+                context.signal.throwIfAborted();
+                validateAnswerBatch(request.inputIds, request.items, maxItems);
+                const cells = request.items.map((item) => ({
+                    item: Object.freeze({
+                        id: item.id,
+                        data: item.data,
+                        sourceStatus: item.sourceStatus,
+                        inputIds: Object.freeze([...item.inputIds]),
+                    }),
+                    hasValue: false,
+                    local: { status: 'not-run', issues: [] },
+                    review: { status: 'not-run', issues: [] },
+                    knownReviewFailure: false,
+                }));
+                return new AgentCoreEngine({
+                    maxRounds: maxRepairs + 1,
+                    errors: { exhausted: () => new TypeError('Answer flow exhausted') },
+                    execution: { signal: context.signal, diagnostics: context.diagnostics },
+                })
+                    .bindWorkflow(workflow, context.app)
+                    .run({ cells, pending: [], repairBudget: new AttemptBudget(maxRepairs) });
+            });
         },
     });
 }

package/dist/esm/kits/answering/tasks.js

@@ -7,6 +7,7 @@
  *
  * Exports: `defineAnswerReaderCatalog`, `defineAnswerTaskCatalog`, and the task/reader types.
  */
+import { nativeSubFlowSync, nativeSubFlowAsync } from '../../diagnostics/native-sub-flow.js';
 import { readonlyCatalog } from '../../utils/catalog.js';
 import { assertion, synchronous } from '../../utils/synchronous.js';
 import { freezeSchema } from '../../utils/object.js';
@@ -96,16 +97,18 @@ export function defineAnswerTaskCatalog(definitions, ports) {
          * @throws TypeError For an unknown task, a parse failure, or a reader returning a Promise.
          */
         read(request, context) {
-            const { input, task, reader } = prepare(request, context);
-            const value = synchronous(reader.read(input, {
-                ...context,
-                app: context.app,
-                signal: context.signal,
-                diagnostics: context.diagnostics,
-                task,
-            }), 'Synchronous answer readers must not return a Promise');
-            context.signal.throwIfAborted();
-            return value;
+            return nativeSubFlowSync(context, 'task', request.taskId, () => {
+                const { input, task, reader } = prepare(request, context);
+                const value = synchronous(reader.read(input, {
+                    ...context,
+                    app: context.app,
+                    signal: context.signal,
+                    diagnostics: context.diagnostics,
+                    task,
+                }), 'Synchronous answer readers must not return a Promise');
+                context.signal.throwIfAborted();
+                return value;
+            });
         },
         /**
          * Read evidence through a task's registered reader, awaiting an async reader.
@@ -113,16 +116,18 @@ export function defineAnswerTaskCatalog(definitions, ports) {
          * @throws TypeError For an unknown task or a parse failure; aborts with the caller's signal.
          */
         async readAsync(request, context) {
-            const { input, task, reader } = prepare(request, context);
-            const value = await awaitWithSignal(reader.read(input, {
-                ...context,
-                app: context.app,
-                signal: context.signal,
-                diagnostics: context.diagnostics,
-                task,
-            }), context.signal);
-            context.signal.throwIfAborted();
-            return value;
+            return nativeSubFlowAsync(context, 'task', request.taskId, async () => {
+                const { input, task, reader } = prepare(request, context);
+                const value = await awaitWithSignal(reader.read(input, {
+                    ...context,
+                    app: context.app,
+                    signal: context.signal,
+                    diagnostics: context.diagnostics,
+                    task,
+                }), context.signal);
+                context.signal.throwIfAborted();
+                return value;
+            });
         },
     });
 }

package/dist/esm/kits/delivery.d.ts

@@ -1,12 +1,3 @@
-/**
- * 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.
- */
 import type { DeliveryOptions } from '../structs/kits/delivery.js';
 import type { ExecutionContext } from '../structs/common.js';
 /**