@jangts/agent-core 0.3.5 → 0.5.0

package/dist/cjs/capabilities/model.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ModelCapabilityRegistry = exports.modelProtocolError = void 0;
+exports.ModelToolRegistry = exports.modelProtocolError = void 0;
 /**
- * Declarative catalog of model capabilities for a request or one stage projection.
+ * Declarative catalog of model tools for a request or one stage projection.
  *
  * A capability pairs an id and description with an input schema and a synchronous resolver,
  * letting stage code parse model-supplied arguments and produce a typed value. Registration
@@ -12,15 +12,16 @@ exports.ModelCapabilityRegistry = exports.modelProtocolError = void 0;
  * The registry is mutable until `seal()`. `select()` derives a sealed subset for a stage and
  * shares the already-frozen entries rather than re-validating or re-wrapping them.
  *
- * Exports: `ModelCapabilityRegistry`, `modelProtocolError`, and the capability types.
+ * Exports: `ModelToolRegistry`, `modelProtocolError`, and the capability types.
  */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const model_protocol_js_1 = require("../utils/model-protocol.js");
 const schema_adapter_js_1 = require("../utils/schema-adapter.js");
+const tool_conditions_js_1 = require("./tool-conditions.js");
 var model_protocol_js_2 = require("../utils/model-protocol.js");
 Object.defineProperty(exports, "modelProtocolError", { enumerable: true, get: function () { return model_protocol_js_2.modelProtocolError; } });
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
-class ModelCapabilityRegistry {
+class ModelToolRegistry {
     /** Insertion-ordered entries; iteration order is the declaration order of the catalog. */
     definitionsById = new Map();
     /** Sealing is one-way: stage-time code must never extend the catalog it is executing. */
@@ -51,13 +52,22 @@ class ModelCapabilityRegistry {
         if (!capability.id?.trim() ||
             !capability.description?.trim() ||
             schema?.type !== 'object' ||
-            typeof capability.resolve !== 'function' ||
+            (capability.resolve !== undefined && typeof capability.resolve !== 'function') ||
+            (capability.active !== undefined &&
+                typeof capability.active !== 'function' &&
+                typeof capability.active !== 'boolean') ||
             this.definitionsById.has(capability.id))
             throw new TypeError('Invalid or duplicate model capability');
         // Clone and freeze the schema, and pin `parse`, so the stored entry is independent of
         // the definition object the host may keep mutating.
         const inputSchema = (0, schema_adapter_js_1.snapshotSchemaAdapter)(capability.inputSchema, 'Model input parsers must be synchronous');
-        const resolver = capability.resolve.bind(capability);
+        const resolver = capability.resolve?.bind(capability) ?? ((value) => value);
+        const asIntent = (0, tool_conditions_js_1.bindIntent)((0, tool_conditions_js_1.snapshotIntent)(typeof capability.asIntent === 'function'
+            ? capability.asIntent.bind(capability)
+            : capability.asIntent), capability);
+        const active = typeof capability.active === 'function'
+            ? capability.active.bind(capability)
+            : capability.active;
         // Bind once here: a later caller cannot substitute its own receiver for the resolver.
         const resolve = (value, context) => (0, synchronous_js_1.synchronous)(resolver(value, context), 'Model capability resolvers must be synchronous');
         this.definitionsById.set(capability.id, Object.freeze({
@@ -65,6 +75,8 @@ class ModelCapabilityRegistry {
             description: capability.description,
             inputSchema,
             resolve,
+            ...(asIntent !== undefined ? { asIntent } : {}),
+            ...(active !== undefined ? { active } : {}),
         }));
         return this;
     }
@@ -81,7 +93,7 @@ class ModelCapabilityRegistry {
         return this.definitionsById.entries();
     }
     /**
-     * Register several capabilities.
+     * Register several tools.
      *
      * @param definitions Declarations applied in iteration order.
      * @returns This registry, for chaining.
@@ -142,21 +154,53 @@ class ModelCapabilityRegistry {
      * @throws TypeError when the selection is empty or contains a duplicate id.
      * @throws Error when an id was never registered.
      */
-    select(ids) {
+    select(ids, context) {
         if (!ids.length || new Set(ids).size !== ids.length)
             throw new TypeError('Invalid capability selection');
-        const selected = new ModelCapabilityRegistry();
+        const selected = new ModelToolRegistry();
         for (const id of ids) {
             const capability = this.definitionsById.get(id);
             if (!capability)
                 throw new Error(`Model capability is not registered: ${id}`);
+            if (arguments.length > 1) {
+                if (!(0, tool_conditions_js_1.toolActive)(capability.active, context))
+                    continue;
+            }
+            else if (capability.active === false) {
+                // Boolean activation is evaluable without a host context; predicate activation still
+                // needs an explicit context projection.
+                continue;
+            }
             // Registration already detached/froze the schema and pinned its handlers.
             // Stage projections share those immutable entries, not another clone and
             // another layer of parser/resolver wrappers for every selection.
-            selected.definitionsById.set(id, capability);
+            selected.definitionsById.set(id, arguments.length > 1 ? this.bound(capability, context) : capability);
         }
         return selected.seal();
     }
+    /** Discover active demand-facing tools without tying the projection to a workflow entry. */
+    withIntent(context) {
+        const selected = new ModelToolRegistry();
+        for (const tool of this.definitionsById.values()) {
+            if (!(0, tool_conditions_js_1.toolActive)(tool.active, context))
+                continue;
+            const description = (0, tool_conditions_js_1.intentDescription)(tool.asIntent, tool.description, context);
+            if (description !== undefined)
+                selected.definitionsById.set(tool.id, Object.freeze({ ...this.bound(tool, context), description }));
+        }
+        return selected.seal();
+    }
+    /** Pin the host context and recheck activation before accepting a model proposal. */
+    bound(tool, context) {
+        return Object.freeze({
+            ...tool,
+            resolve: (input, stage) => {
+                if (!(0, tool_conditions_js_1.toolActive)(tool.active, context))
+                    (0, model_protocol_js_1.modelProtocolError)('Tool is inactive');
+                return tool.resolve(input, stage);
+            },
+        });
+    }
     /**
      * Parse model-supplied arguments and run the selected capability.
      *
@@ -171,11 +215,11 @@ class ModelCapabilityRegistry {
         const { stageId } = context;
         // Model output is untrusted: unknown ids and non-object arguments are protocol failures,
         // not ordinary `undefined` results.
-        const capability = this.definitionsById.get(selection.capabilityId) ??
+        const capability = this.definitionsById.get(selection.toolId) ??
             (0, model_protocol_js_1.modelProtocolError)('Model capability is unavailable in this stage');
         if (!selection.input || typeof selection.input !== 'object' || Array.isArray(selection.input))
             (0, model_protocol_js_1.modelProtocolError)('Model capability input must be an object');
         return (0, synchronous_js_1.synchronous)(capability.resolve(capability.inputSchema.parse(selection.input), { stageId }), 'Model capability parsers must be synchronous');
     }
 }
-exports.ModelCapabilityRegistry = ModelCapabilityRegistry;
+exports.ModelToolRegistry = ModelToolRegistry;

package/dist/cjs/capabilities/tool-conditions.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshotIntent = snapshotIntent;
+exports.bindIntent = bindIntent;
+exports.toolActive = toolActive;
+exports.intentDescription = intentDescription;
+/** Tool metadata validation and synchronous activation shared by registration and execution. */
+const synchronous_js_1 = require("../utils/synchronous.js");
+/** Validate and snapshot discovery metadata without evaluating host predicates. */
+function snapshotIntent(value) {
+    if (value === undefined || value === true || typeof value === 'function')
+        return value;
+    if (typeof value === 'string') {
+        if (!value.trim())
+            throw new TypeError('Intent description must not be blank');
+        return value;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Invalid asIntent metadata');
+    if (value.description !== undefined &&
+        (typeof value.description !== 'string' || !value.description.trim()))
+        throw new TypeError('Invalid intent description');
+    if (value.when !== undefined && typeof value.when !== 'function')
+        throw new TypeError('Invalid intent predicate');
+    const delegates = value.delegates;
+    if (delegates !== undefined &&
+        (!Array.isArray(delegates) ||
+            !delegates.length ||
+            delegates.some((id) => typeof id !== 'string' || !id.trim()) ||
+            new Set(delegates).size !== delegates.length))
+        throw new TypeError('Invalid intent delegates');
+    return Object.freeze({
+        description: value.description,
+        ...(value.when !== undefined ? { when: value.when } : {}),
+        ...(delegates ? { delegates: Object.freeze([...delegates]) } : {}),
+    });
+}
+/** Bind an optional object-form predicate to its owning Tool, without touching other forms. */
+function bindIntent(value, owner) {
+    if (!value || typeof value !== 'object' || typeof value.when !== 'function')
+        return value;
+    return Object.freeze({ ...value, when: value.when.bind(owner) });
+}
+/** Check activation and reject asynchronous or nonboolean predicate results. */
+function toolActive(condition, context) {
+    if (condition === undefined)
+        return true;
+    if (typeof condition === 'boolean')
+        return condition;
+    if (typeof condition !== 'function')
+        throw new TypeError('Invalid tool active condition');
+    return (0, synchronous_js_1.booleanResult)(condition(context), 'Tool predicates must be synchronous', 'Tool predicates must return boolean');
+}
+/** Resolve the demand-facing description only when discovery is enabled. */
+function intentDescription(metadata, fallback, context) {
+    if (metadata === undefined)
+        return undefined;
+    if (typeof metadata === 'string')
+        return metadata;
+    if (metadata === true)
+        return fallback;
+    if (typeof metadata === 'function')
+        return toolActive(metadata, context) ? fallback : undefined;
+    return toolActive(metadata.when, context) ? (metadata.description ?? fallback) : undefined;
+}

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

@@ -6,13 +6,14 @@ exports.createToolRegistry = createToolRegistry;
  *
  * A `ToolDefinition` is the App-facing declaration: a schema adapter plus authorize, execute
  * and parseOutput handlers. This module pins those handlers to their definition and adapts
- * them to the lower-level `ExecutableTool` contract, while keeping the synchronous and
+ * them to the lower-level `ErasedTool` contract, while keeping the synchronous and
  * asynchronous boundaries explicit: `invokeAsync` awaits authorization and execution,
  * `invoke` rejects a promise from either.
  *
  * Exports: `createToolRegistry`.
  */
 const synchronous_js_1 = require("../utils/synchronous.js");
+const tool_conditions_js_1 = require("./tool-conditions.js");
 const tools_js_1 = require("./tools.js");
 /**
  * Run authorization and execution for one call, in that order.
@@ -21,16 +22,25 @@ const tools_js_1 = require("./tools.js");
  * violation instead of being silently ignored. Cancellation is checked before and after each
  * phase so an aborted request never produces a successful value.
  */
-function execute(definition, input, context, execution) {
+function execute(definition, input, context, execution, unavailable) {
     const { signal, mode, diagnostics, report, createSubFlowLogger } = execution;
     signal.throwIfAborted();
+    if (!(0, tool_conditions_js_1.toolActive)(definition.active, context))
+        throw unavailable?.(definition.id) ?? new Error(`Tool is inactive: ${definition.id}`);
     // Re-check after the handler returned: work that completed during cancellation must not be
     // reported as a success.
     const complete = (value) => {
         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) => {
         (0, synchronous_js_1.assertion)(result, 'Tool authorization must return void');
         signal.throwIfAborted();
@@ -61,6 +71,7 @@ function execute(definition, input, context, execution) {
  */
 function createToolRegistry(definitions, context, options) {
     const registry = new tools_js_1.ToolRegistry(options);
+    const unavailable = options.errors?.unavailable?.bind(options.errors);
     registry.registerAll(definitions.map((definition) => {
         // Every entry point pins the same canonical handlers, including callers
         // that use this creator directly rather than defineToolCatalog.
@@ -70,6 +81,9 @@ function createToolRegistry(definitions, context, options) {
             kind,
             description,
             inputSchema,
+            active: typeof definition.active === 'function'
+                ? definition.active.bind(definition)
+                : definition.active,
             authorize: authorize.bind(definition),
             execute: handle.bind(definition),
             parseOutput: parseOutput.bind(definition),
@@ -83,7 +97,7 @@ function createToolRegistry(definitions, context, options) {
             // definition cannot change what this registry validates.
             parseInput: inputSchema.parse.bind(inputSchema),
             parseOutput: bound.parseOutput,
-            execute: (input, execution) => execute(bound, input, context, execution),
+            execute: (input, execution) => execute(bound, input, context, execution, unavailable),
         };
     }));
     registry.seal();

package/dist/cjs/capabilities/tools.js

@@ -14,6 +14,7 @@ exports.executeInvocation = exports.ToolRegistry = void 0;
  *
  * Exports: `ToolRegistry`, `executeInvocation`, and the tool/invocation contracts.
  */
+const native_sub_flow_js_1 = require("../diagnostics/native-sub-flow.js");
 const events_js_1 = require("../execution/events.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
@@ -119,7 +120,8 @@ class ToolRegistry {
      */
     invoke(request) {
         const call = (0, invocation_js_1.toolInvocation)(request, arguments.length);
-        return this.execute(call.toolId, call.input, false, call.diagnostics, call.signal);
+        const callId = (0, invocation_js_1.invocationId)();
+        return (0, native_sub_flow_js_1.nativeSubFlowSync)({ ...call, signal: (0, cancellation_js_1.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.
@@ -131,7 +133,8 @@ class ToolRegistry {
      */
     async invokeAsync(request) {
         const call = (0, invocation_js_1.toolInvocation)(request, arguments.length);
-        return (await this.execute(call.toolId, call.input, true, call.diagnostics, call.signal));
+        const callId = (0, invocation_js_1.invocationId)();
+        return (0, native_sub_flow_js_1.nativeSubFlowAsync)({ ...call, signal: (0, cancellation_js_1.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.
@@ -143,7 +146,7 @@ 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 = (0, invocation_js_1.invocationId)()) {
         // 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 &&
@@ -155,7 +158,7 @@ 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 = (0, cancellation_js_1.combineSignals)(this.ports.signal, requestSignal);
-        const invocationId = (0, invocation_js_1.invocationId)();
+        const invocationId = callId;
         const diagnostics = parentDiagnostics?.child(invocationId, {
             invocationId,
             nodeRole: 'invocation',
@@ -193,24 +196,15 @@ class ToolRegistry {
         };
         const succeed = (result) => {
             signal.throwIfAborted();
-            let debug = reports.debug();
             if (tool.debugSteps && diagnostics?.enabled('tool.result', 'content')) {
                 try {
-                    debug = reports.debug({
-                        subs: (0, synchronous_js_1.synchronous)(tool.debugSteps(result, reporting), 'Tool debug reports must be synchronous'),
-                    });
+                    (0, synchronous_js_1.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', () => ({
@@ -280,6 +274,7 @@ class ToolRegistry {
             signal.throwIfAborted();
             phase = 'execute';
             const value = tool.execute(parsed, {
+                logger,
                 mode: asynchronous ? 'async' : 'sync',
                 invocationId,
                 signal,

package/dist/cjs/context/audit.js

@@ -35,13 +35,10 @@ function auditContextChange(original, current, mutable) {
         const changed = JSON.stringify(before.value) !== JSON.stringify(after.value);
         (0, rules_js_1.breakWhile)(changed &&
             (!mutable.has(before.id) || before.role === 'system' || before.trust === 'instruction'), fail(`Protected context changed: ${before.id}`));
-        if (changed &&
-            before.value !== null &&
-            after.value !== null &&
-            typeof before.value === 'object' &&
-            typeof after.value === 'object')
-            // Only the field set is compared here; field order is not meaningful for context data.
-            (0, rules_js_1.breakWhile)(JSON.stringify(Object.keys(before.value).sort()) !==
-                JSON.stringify(Object.keys(after.value).sort()), fail('Context fields must be preserved'));
+        if (changed && typeof before.value === 'object' && typeof after.value === 'object')
+            // A null value carries no fields. Treat it as an empty field set so turning it into an
+            // object, or dropping an object back to null, is still rejected as a structural change.
+            (0, rules_js_1.breakWhile)(JSON.stringify(Object.keys(before.value ?? {}).sort()) !==
+                JSON.stringify(Object.keys(after.value ?? {}).sort()), fail('Context fields must be preserved'));
     }
 }

package/dist/cjs/context/index.js

@@ -22,15 +22,14 @@ exports.assembleContextPlan = exports.assembleFragments = void 0;
  * Core owns the guarantees here. A fragment declares its trust, lifetime and character
  * budget in one place; assembly validates those declarations and refuses to truncate;
  * auditing rejects structural change to protected fragments. Selection, ordering, compression
- * and model choice remain App-side nodes that run before this boundary.
+ * and model choice remain App-side nodes that run before this boundary. Optional Kit helpers
+ * such as evidence checks are imported from their own `/kits/*` entries, not from here.
  *
- * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal`, the fragment helpers,
- * and the evidence Kit helpers consumed alongside assembled context.
+ * Exports: `assembleFragments`, `assembleContextPlan`, `ContextJournal` and the fragment helpers.
  */
 __exportStar(require("./fragments.js"), exports);
 var assembly_js_1 = require("./assembly.js");
 Object.defineProperty(exports, "assembleFragments", { enumerable: true, get: function () { return assembly_js_1.assembleFragments; } });
 __exportStar(require("./journal.js"), exports);
-__exportStar(require("../kits/evidence.js"), exports);
 var plan_js_1 = require("./plan.js");
 Object.defineProperty(exports, "assembleContextPlan", { enumerable: true, get: function () { return plan_js_1.assembleContextPlan; } });

package/dist/cjs/diagnostics/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.reportedStepStatuses = exports.reportedStepStatusCatalog = void 0;
+exports.reportedStepStatuses = exports.reportedStepStatusCatalog = exports.ScopedSubFlowLogger = exports.SubFlowLogger = void 0;
 exports.createDiagnostics = createDiagnostics;
 exports.diagnosticError = diagnosticError;
 exports.normalizeDiagnosticEvent = normalizeDiagnosticEvent;
@@ -37,6 +37,9 @@ const sub_flow_js_1 = require("./sub-flow.js");
 const rules_js_1 = require("../utils/rules.js");
 __exportStar(require("../structs/diagnostics.js"), exports);
 __exportStar(require("./catalog.js"), exports);
+var sub_flow_js_2 = require("./sub-flow.js");
+Object.defineProperty(exports, "SubFlowLogger", { enumerable: true, get: function () { return sub_flow_js_2.SubFlowLogger; } });
+Object.defineProperty(exports, "ScopedSubFlowLogger", { enumerable: true, get: function () { return sub_flow_js_2.ScopedSubFlowLogger; } });
 var debug_js_2 = require("../structs/debug.js");
 Object.defineProperty(exports, "reportedStepStatusCatalog", { enumerable: true, get: function () { return debug_js_2.reportedStepStatusCatalog; } });
 Object.defineProperty(exports, "reportedStepStatuses", { enumerable: true, get: function () { return debug_js_2.reportedStepStatuses; } });
@@ -129,7 +132,7 @@ function normalizeDiagnosticEvent(input) {
     // The count and size bounds match what the sub-flow logger enforces, so a record produced by
     // Core can never be rejected here; only hand-edited or foreign records can.
     if (!Array.isArray(steps) ||
-        steps.length > 256 ||
+        steps.length > 1024 ||
         new Set(steps.map((step) => step?.stepId)).size !== steps.length ||
         steps.some((step) => !step ||
             step.origin !== 'reported' ||
@@ -140,7 +143,15 @@ function normalizeDiagnosticEvent(input) {
             !Number.isSafeInteger(step.sequence) ||
             step.sequence < 1 ||
             (step.status !== undefined && !debug_js_1.reportedStepStatuses.includes(step.status)) ||
-            ['parentStepId', 'relatedDefinitionId', 'caseId', 'summary'].some((key) => step[key] !== undefined && typeof step[key] !== 'string') ||
+            [
+                'type',
+                'subnodeId',
+                'parentStepId',
+                'relatedDefinitionId',
+                'relatedInvocationId',
+                'caseId',
+                'summary',
+            ].some((key) => step[key] !== undefined && typeof step[key] !== 'string') ||
             (step.usedModel !== undefined && typeof step.usedModel !== 'boolean') ||
             (step.revision !== undefined &&
                 (!Number.isSafeInteger(step.revision) ||
@@ -155,6 +166,37 @@ function normalizeDiagnosticEvent(input) {
             (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0)) ||
         (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
         throw new TypeError('Invalid reported diagnostic steps');
+    const originals = new Map();
+    let lastSequence = 0;
+    for (const step of steps) {
+        if (step.operation === undefined)
+            continue; // Historical projected snapshots remain readable.
+        (0, rules_js_1.breakWhile)(!['write', 'fix'].includes(step.operation) || step.sequence <= lastSequence, () => new TypeError('Invalid sub-flow record order'));
+        lastSequence = step.sequence;
+        if (step.operation === 'write') {
+            (0, rules_js_1.breakWhile)(step.targetStepId !== undefined || step.revision !== 1, () => new TypeError('Invalid sub-flow write record'));
+            originals.set(step.stepId, {
+                revision: 1,
+                subnodeId: step.subnodeId,
+                type: step.type,
+                relatedInvocationId: step.relatedInvocationId,
+            });
+        }
+        else {
+            const previous = originals.get(step.targetStepId);
+            (0, rules_js_1.breakWhile)(previous === undefined ||
+                step.revision !== previous.revision + 1 ||
+                step.subnodeId !== previous.subnodeId ||
+                step.type !== previous.type ||
+                step.relatedInvocationId !== previous.relatedInvocationId, () => new TypeError('Invalid sub-flow fix reference'));
+            originals.set(step.targetStepId, {
+                revision: step.revision,
+                subnodeId: step.subnodeId,
+                type: step.type,
+                relatedInvocationId: step.relatedInvocationId,
+            });
+        }
+    }
     // Structural check only: the returned snapshot is discarded because the clone below already
     // produces the detached copy kept by the normalized record.
     for (const step of steps)
@@ -167,8 +209,14 @@ function normalizeDiagnosticEvent(input) {
         (0, rules_js_1.breakWhile)(progress !== undefined &&
             (!progress ||
                 !['write', 'fix'].includes(progress.operation) ||
+                ['type', 'subnodeId', 'relatedInvocationId'].some((key) => progress[key] !== undefined &&
+                    typeof progress[key] !== 'string') ||
                 typeof progress.stepId !== 'string' ||
                 !progress.stepId ||
+                (progress.targetStepId !== undefined &&
+                    (progress.operation !== 'fix' ||
+                        typeof progress.targetStepId !== 'string' ||
+                        !progress.targetStepId)) ||
                 !Number.isSafeInteger(progress.sequence) ||
                 progress.sequence < 1 ||
                 !Number.isSafeInteger(progress.revision) ||

package/dist/cjs/diagnostics/native-sub-flow.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeSubFlowCatalog = void 0;
+exports.nativeSubFlowSync = nativeSubFlowSync;
+exports.nativeSubFlowAsync = nativeSubFlowAsync;
+const sub_flow_js_1 = require("./sub-flow.js");
+/** Fixed metadata shared by native producers; pure getters and formatters are not producers. */
+exports.nativeSubFlowCatalog = {
+    model: { name: 'Model call', kind: 'model', type: 'model.call' },
+    tool: { name: 'Tool call', kind: 'tool', type: 'tool.call' },
+    invocation: { name: 'Invocation', kind: 'invocation', type: 'handler.call' },
+    retrieval: { name: 'Retrieval', kind: 'retrieval', type: 'retrieval.run' },
+    task: { name: 'Read answer evidence', kind: 'retrieval', type: 'evidence.read' },
+    check: { name: 'Check answer', kind: 'validation', type: 'answer.check' },
+    output: { name: 'Compose output', kind: 'presentation', type: 'output.compose' },
+    answer: { name: 'Answer flow', kind: 'answering', type: 'answer.run' },
+    retry: { name: 'Retry model proposal', kind: 'recovery', type: 'model.retry' },
+    context: { name: 'Process context', kind: 'context', type: 'context.process' },
+    recovery: { name: 'Recovery attempt', kind: 'recovery', type: 'recovery.try' },
+    delivery: { name: 'Deliver result', kind: 'delivery', type: 'delivery.run' },
+    aggregation: { name: 'Aggregate queries', kind: 'retrieval', type: 'queries.collect' },
+    knowledge: { name: 'Read knowledge', kind: 'retrieval', type: 'knowledge.read' },
+};
+/** Start one fixed record; its revision is best-effort and never controls the operation. */
+function begin(context, producer, id) {
+    let logger;
+    try {
+        logger =
+            context.logger instanceof sub_flow_js_1.SubFlowLogger
+                ? (0, sub_flow_js_1.bindNativeSubFlowLogger)(context.logger, producer, id)
+                : context.logger;
+    }
+    catch {
+        /* A recording limit must not turn a valid operation into a failure. */
+    }
+    let step = -1;
+    try {
+        if (logger)
+            step = logger.write({
+                ...exports.nativeSubFlowCatalog[producer],
+                relatedDefinitionId: id,
+                ...(context.invocationId === undefined
+                    ? {}
+                    : { relatedInvocationId: context.invocationId }),
+                status: 'running',
+            });
+    }
+    catch {
+        /* Optional recording must not change execution. */
+    }
+    return {
+        logger,
+        finish: (status) => {
+            try {
+                if (logger && step !== -1)
+                    logger.fix(step, { status });
+            }
+            catch {
+                /* A broken or detached logger cannot replace the operation result. */
+            }
+        },
+    };
+}
+/** Signal access is diagnostic metadata and cannot replace an operation failure. */
+function failureStatus(context) {
+    try {
+        return context.signal?.aborted ? 'cancelled' : 'error';
+    }
+    catch {
+        return 'error';
+    }
+}
+/** Preserve a synchronous boundary while pairing an optional write with one result revision. */
+function nativeSubFlowSync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        (0, sub_flow_js_1.requireSubFlowLogger)(context.logger);
+    if (!context.logger)
+        return invoke();
+    const { logger, finish } = begin(context, producer, id);
+    try {
+        const value = invoke(logger);
+        finish('success');
+        return value;
+    }
+    catch (error) {
+        finish(failureStatus(context));
+        throw error;
+    }
+}
+/** Await the original operation without introducing another timeout or cancellation race. */
+async function nativeSubFlowAsync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        (0, sub_flow_js_1.requireSubFlowLogger)(context.logger);
+    if (!context.logger)
+        return invoke();
+    const { logger, finish } = begin(context, producer, id);
+    try {
+        const value = await invoke(logger);
+        finish('success');
+        return value;
+    }
+    catch (error) {
+        finish(failureStatus(context));
+        throw error;
+    }
+}