@jangts/agent-core 0.2.5 → 0.3.6

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

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopedSubFlowLogger = exports.SubFlowLogger = void 0;
+exports.captureSubFlowSnapshot = captureSubFlowSnapshot;
 exports.payloadSnapshot = payloadSnapshot;
+exports.requireSubFlowLogger = requireSubFlowLogger;
+exports.bindNativeSubFlowLogger = bindNativeSubFlowLogger;
 exports.createSubFlowLogger = createSubFlowLogger;
 exports.readSubFlowLogger = readSubFlowLogger;
+exports.detachSubFlowLogger = detachSubFlowLogger;
 /**
  * Bounded, self-reported sub-flow logging.
  *
@@ -13,7 +18,7 @@ exports.readSubFlowLogger = readSubFlowLogger;
  * Issued loggers are tracked in a module-private registry, so only the execution that created
  * one can read it. A lookalike object with a `readAll` method is never accepted.
  *
- * Exports: `payloadSnapshot`, `createSubFlowLogger`, `readSubFlowLogger`.
+ * Exports: `payloadSnapshot`, `createSubFlowLogger`, `readSubFlowLogger`, `captureSubFlowSnapshot`.
  */
 const rules_js_1 = require("../utils/rules.js");
 const invocation_js_1 = require("../utils/invocation.js");
@@ -23,12 +28,29 @@ const debug_js_1 = require("../structs/debug.js");
  * private so a structurally identical object cannot impersonate a real logger.
  */
 const instances = new WeakMap();
+/** Only recorder-issued snapshots may enter a diagnostic fact, within their original span. */
+const snapshots = new WeakMap();
+/** Validate a committed snapshot without consulting its logger or invoking App code. */
+function captureSubFlowSnapshot(steps, identity) {
+    const empty = { subSteps: Object.freeze([]), subStepsDropped: 0, subStepsTruncated: false };
+    if (steps === undefined)
+        return empty;
+    const scope = snapshots.get(steps);
+    if (!scope ||
+        (identity &&
+            (scope.identity?.runId !== identity.runId || scope.identity?.spanId !== identity.spanId)))
+        return { ...empty, subStepsDropped: 1 };
+    return { ...empty, subSteps: steps };
+}
 /** Fields accepted by `write`; anything else is rejected so a declaration cannot smuggle state. */
 const writeFields = [
+    'type',
+    'subnodeId',
     'name',
     'kind',
     'parentStepId',
     'relatedDefinitionId',
+    'relatedInvocationId',
     'status',
     'usedModel',
     'startedAtMs',
@@ -50,10 +72,13 @@ const fixFields = [
 ];
 /** Per-field character caps, bounding what one reported step can add to a persisted record. */
 const textLimits = {
+    type: 256,
+    subnodeId: 1024,
     name: 256,
     kind: 128,
     parentStepId: 256,
     relatedDefinitionId: 256,
+    relatedInvocationId: 256,
     caseId: 256,
     summary: 1024,
 };
@@ -175,6 +200,126 @@ function fill(previous, patch) {
     }
     return Object.freeze(result);
 }
+/** Stable diagnostic reasons; untrusted error text and caller payloads never reach the console. */
+const rejectionReasons = {
+    inactive: 'logger is detached or execution is cancelled',
+    scope: 'target does not belong to this subnode',
+    target: 'original write record was not found',
+    fields: 'input contains a forbidden field',
+    transition: 'status transition is not allowed',
+    sealed: 'an established fact cannot be overwritten',
+    limit: 'recording limit exceeded',
+    input: 'invalid input or result patch',
+};
+const rejectionMessages = {
+    'Unknown sub-flow field': 'fields',
+    'Unknown sub-flow step': 'target',
+    'Invalid sub-flow status transition': 'transition',
+    'Terminal sub-flow status is sealed': 'transition',
+    'Terminal sub-flow model use is sealed': 'sealed',
+    'Cannot undo reported model use': 'sealed',
+    'Cannot overwrite a sub-flow time': 'sealed',
+    'Cannot overwrite sub-flow successors': 'sealed',
+    'Cannot overwrite a sub-flow summary': 'sealed',
+    'Sub-flow log limit exceeded': 'limit',
+};
+/** Map only known own data messages; arbitrary thrown values are described generically. */
+function rejectionReason(error) {
+    try {
+        const message = error instanceof Error ? Object.getOwnPropertyDescriptor(error, 'message')?.value : undefined;
+        return typeof message === 'string' && Object.hasOwn(rejectionMessages, message)
+            ? rejectionMessages[message]
+            : 'input';
+    }
+    catch {
+        return 'input';
+    }
+}
+/** Unexported issuance token prevents constructing counterfeit full or scoped loggers. */
+const loggerToken = Symbol('sub-flow-logger');
+const stores = new WeakMap();
+/** Full execution-owned recorder. Owns its store and may issue restricted delegates. */
+class SubFlowLogger {
+    #store;
+    constructor(token, store) {
+        if (token !== loggerToken)
+            throw new TypeError('Use context.createSubFlowLogger()');
+        this.#store = store;
+        stores.set(this, store);
+        Object.freeze(this);
+    }
+    write(input) {
+        return this.#store.write(input);
+    }
+    fix(stepId, patch) {
+        return this.#store.fix(stepId, patch);
+    }
+    readAll() {
+        return this.#store.readAll();
+    }
+    /** Issue a delegate for an App-owned logical group; no execution or scheduling is implied. */
+    fork(subnodeId) {
+        if (typeof subnodeId !== 'string' || !subnodeId.trim() || subnodeId.length > 1024)
+            throw new TypeError('Invalid subnode id');
+        return new ScopedSubFlowLogger(loggerToken, this, subnodeId);
+    }
+}
+exports.SubFlowLogger = SubFlowLogger;
+/** Non-inheriting delegate. Stores only the original logger and its bound subnode identity. */
+class ScopedSubFlowLogger {
+    #logger;
+    #subnodeId;
+    constructor(token, logger, subnodeId) {
+        if (token !== loggerToken)
+            throw new TypeError('Use logger.fork(subnodeId)');
+        this.#logger = logger;
+        this.#subnodeId = subnodeId;
+        Object.freeze(this);
+    }
+    write(input) {
+        if (!stores.get(this.#logger).isActive()) {
+            stores.get(this.#logger).warn('write', 'inactive');
+            return -1;
+        }
+        try {
+            fields(input, writeFields.filter((field) => field !== 'subnodeId'));
+            // Copy descriptors so private content getters remain subject to the original policy.
+            const bound = Object.defineProperties({}, Object.getOwnPropertyDescriptors(input));
+            Object.defineProperty(bound, 'subnodeId', { value: this.#subnodeId, enumerable: true });
+            return this.#logger.write(bound);
+        }
+        catch (error) {
+            stores.get(this.#logger).warn('write', rejectionReason(error));
+            return -1;
+        }
+    }
+    fix(stepId, patch) {
+        const store = stores.get(this.#logger);
+        if (!store.isActive()) {
+            store.warn('fix', 'inactive');
+            return false;
+        }
+        if (!store.owns(stepId, this.#subnodeId)) {
+            store.warn('fix', 'scope');
+            return false;
+        }
+        return this.#logger.fix(stepId, patch);
+    }
+    readAll() {
+        return this.#logger.readAll();
+    }
+}
+exports.ScopedSubFlowLogger = ScopedSubFlowLogger;
+/** Runtime check complements nominal invocation types; scoped or forged inputs cannot invoke. */
+function requireSubFlowLogger(logger) {
+    if (logger !== undefined && (!(logger instanceof SubFlowLogger) || !instances.has(logger)))
+        throw new TypeError('Native invocation requires a full SubFlowLogger');
+}
+/** Allocate a short node-local group; the owning node visit already supplies the namespace. */
+function bindNativeSubFlowLogger(logger, kind, definitionId) {
+    requireSubFlowLogger(logger);
+    return logger.fork(stores.get(logger).nextNativeSubnodeId(kind, definitionId));
+}
 /**
  * Create a logger bound to one active execution visit.
  *
@@ -183,51 +328,95 @@ function fill(previous, patch) {
  *
  * @param owner Object that owns the visit. `readSubFlowLogger` compares this identity before
  *   returning any step.
- * @param active Reports whether the visit is still open; a closed logger rejects writes.
+ * @param active Reports whether the visit is still open; a detached logger returns write=-1 and fix=false.
  * @param content Reports whether content-level detail is enabled. When false, summaries and
  *   payloads are dropped before anything is stored.
- * @param changed Called after each accepted write or fix with the progress delta to publish.
+ * @param changed Runtime receiver called after each accepted write/fix with its delta and immutable snapshot.
  * @param identity Diagnostic run and span the logger belongs to; used to reject cross-scope reads.
  * @returns A frozen logger instance.
  */
 function createSubFlowLogger(owner, active, content, changed, identity) {
+    let root;
     class Logger {
         #steps = Object.freeze([]);
-        #changes = 0;
+        #records = Object.freeze([]);
+        #warnings = new Set();
+        #nativeCalls = new Map();
         constructor() {
-            instances.set(this, { owner, identity, read: () => this.#steps });
+            instances.set(this, {
+                owner,
+                identity,
+                read: () => this.#records,
+                detach: () => {
+                    // Retained read-only instances must not keep the runtime or App consumers alive.
+                    owner = {};
+                    instances.get(this).owner = owner;
+                    active = () => false;
+                    content = () => false;
+                    changed = () => { };
+                },
+            });
+            snapshots.set(this.#records, { identity });
             Object.freeze(this);
         }
-        #assertActive() {
-            // A logger that outlived its execution would append evidence to a finished request.
-            (0, rules_js_1.breakWhile)(!active(), () => new TypeError('Sub-flow logger belongs to a closed execution'));
-        }
         #save(step, operation) {
-            this.#assertActive();
-            // A fix replaces the step with the same id in place; a write always appends.
+            if (!active())
+                return false;
+            // Logical heads validate revisions; only the immutable ledger is published or queried.
             const next = operation === 'write'
                 ? [...this.#steps, step]
                 : this.#steps.map((item) => (item.stepId === step.stepId ? step : item));
             // Successors must resolve inside this logger, otherwise the recorded graph would have
             // dangling edges.
             (0, rules_js_1.breakWhile)(step.nextStepIds?.some((id) => !next.some((item) => item.stepId === id)), () => new TypeError('Sub-flow successors must belong to this logger'));
-            // The step and size caps equal the persisted-record limits; the change cap bounds
-            // write/fix churn even when the final step count stays small.
-            (0, rules_js_1.breakWhile)(next.length > 256 || this.#changes >= 1024 || JSON.stringify(next).length > 65536, () => new RangeError('Sub-flow log limit exceeded'));
-            this.#steps = Object.freeze(next);
-            this.#changes++;
-            changed(this, {
+            const record = Object.freeze({
+                ...step,
                 operation,
-                stepId: step.stepId,
-                sequence: step.sequence,
-                revision: step.revision,
-                createdAtMs: step.createdAtMs,
-                status: step.status,
-                ...(step.usedModel === undefined ? {} : { usedModel: step.usedModel }),
+                stepId: operation === 'write' ? step.stepId : (0, invocation_js_1.invocationId)(),
+                ...(operation === 'fix' ? { targetStepId: step.stepId } : {}),
+                sequence: this.#records.length + 1,
+                createdAtMs: Date.now(),
             });
+            const records = Object.freeze([...this.#records, record]);
+            (0, rules_js_1.breakWhile)(next.length > 256 || records.length > 1024 || JSON.stringify(records).length > 65536, () => new RangeError('Sub-flow log limit exceeded'));
+            if (!active())
+                return false;
+            this.#steps = Object.freeze(next);
+            this.#records = records;
+            snapshots.set(records, { identity });
+            changed(root, {
+                operation,
+                type: record.type,
+                subnodeId: record.subnodeId,
+                relatedInvocationId: record.relatedInvocationId,
+                stepId: record.stepId,
+                ...(record.targetStepId ? { targetStepId: record.targetStepId } : {}),
+                sequence: record.sequence,
+                revision: record.revision,
+                createdAtMs: record.createdAtMs,
+                status: record.status,
+                ...(record.usedModel === undefined ? {} : { usedModel: record.usedModel }),
+            }, records);
+            return true;
         }
         write(input) {
-            this.#assertActive();
+            if (!active()) {
+                this.warn('write', 'inactive');
+                return -1;
+            }
+            try {
+                const id = this.#append(input);
+                if (id === -1)
+                    this.warn('write', 'inactive');
+                return id;
+            }
+            catch (error) {
+                this.warn('write', rejectionReason(error));
+                return -1;
+            }
+        }
+        /** Validate a new record before committing it; public write returns -1 on failure. */
+        #append(input) {
             fields(input, writeFields);
             (0, rules_js_1.breakWhile)(input.nextStepIds !== undefined && !Array.isArray(input.nextStepIds), () => new TypeError('Invalid sub-flow successors'));
             const now = Date.now(), status = input.status === undefined ? 'planned' : input.status;
@@ -236,16 +425,21 @@ function createSubFlowLogger(owner, active, content, changed, identity) {
             const step = {
                 origin: 'reported',
                 stepId: (0, invocation_js_1.invocationId)(),
-                sequence: this.#steps.length + 1,
+                sequence: this.#records.length + 1,
                 revision: 1,
                 createdAtMs: now,
+                type: input.type ?? input.kind,
+                ...(input.subnodeId === undefined ? {} : { subnodeId: input.subnodeId }),
                 name: input.name,
-                kind: input.kind,
+                kind: input.kind ?? input.type,
                 status,
                 ...(input.parentStepId === undefined ? {} : { parentStepId: input.parentStepId }),
                 ...(input.relatedDefinitionId === undefined
                     ? {}
                     : { relatedDefinitionId: input.relatedDefinitionId }),
+                ...(input.relatedInvocationId === undefined
+                    ? {}
+                    : { relatedInvocationId: input.relatedInvocationId }),
                 ...(input.caseId === undefined ? {} : { caseId: input.caseId }),
                 ...(input.usedModel === undefined ? {} : { usedModel: input.usedModel }),
                 ...(input.startedAtMs === undefined && status !== 'running'
@@ -268,11 +462,30 @@ function createSubFlowLogger(owner, active, content, changed, identity) {
             }
             validate(step);
             (0, rules_js_1.breakWhile)(step.parentStepId && !this.#steps.some((item) => item.stepId === step.parentStepId), () => new TypeError('Sub-flow parent must belong to this logger'));
-            this.#save(Object.freeze(step), 'write');
-            return step.stepId;
+            return this.#save(Object.freeze(step), 'write') ? step.stepId : -1;
         }
         fix(stepId, patch) {
-            this.#assertActive();
+            if (!active()) {
+                this.warn('fix', 'inactive');
+                return false;
+            }
+            if (stepId === -1) {
+                this.warn('fix', 'target');
+                return false;
+            }
+            try {
+                const fixed = this.#applyFix(stepId, patch);
+                if (!fixed)
+                    this.warn('fix', 'inactive');
+                return fixed;
+            }
+            catch (error) {
+                this.warn('fix', rejectionReason(error));
+                return false;
+            }
+        }
+        /** Validate a revision completely before committing it; public fix reports failure as false. */
+        #applyFix(stepId, patch) {
             fields(patch, fixFields);
             const previous = this.#steps.find((step) => step.stepId === stepId);
             // The assertion above only satisfies the type checker; this check rejects an unknown id.
@@ -328,13 +541,42 @@ function createSubFlowLogger(owner, active, content, changed, identity) {
                     });
             }
             validate(step);
-            this.#save(Object.freeze(step), 'fix');
+            return this.#save(Object.freeze(step), 'fix');
+        }
+        owns(stepId, subnodeId) {
+            return this.#steps.some((step) => step.stepId === stepId && step.subnodeId === subnodeId);
+        }
+        isActive() {
+            return active();
+        }
+        /** Count starts, including failed/cancelled calls; each node visit owns a fresh store. */
+        nextNativeSubnodeId(kind, definitionId) {
+            const key = JSON.stringify([kind, definitionId]);
+            const next = (this.#nativeCalls.get(key) ?? 0) + 1;
+            this.#nativeCalls.set(key, next);
+            return `${kind}:${encodeURIComponent(definitionId)}:${next}`;
+        }
+        /** Deduplicate safe developer warnings in the sole owning store, including delegated calls. */
+        warn(operation, reason) {
+            const key = `${operation}:${reason}`;
+            if (this.#warnings.has(key))
+                return;
+            this.#warnings.add(key);
+            try {
+                console.warn(`[agent-core:subflow] ${operation} rejected: ${rejectionReasons[reason]}`);
+            }
+            catch {
+                /* A console extension cannot change logging return values. */
+            }
         }
         readAll() {
-            return this.#steps;
+            return this.#records;
         }
     }
-    return new Logger();
+    const store = new Logger();
+    root = new SubFlowLogger(loggerToken, store);
+    instances.set(root, instances.get(store));
+    return root;
 }
 /**
  * Read the steps recorded by a logger issued by this module.
@@ -357,3 +599,7 @@ function readSubFlowLogger(input, owner, identity) {
             instance.identity?.spanId !== identity.spanId), () => new TypeError('Sub-flow logger belongs to another diagnostic scope'));
     return instance.read();
 }
+/** Release execution callbacks while preserving the instance's immutable query history. */
+function detachSubFlowLogger(logger) {
+    instances.get(logger)?.detach();
+}

package/dist/cjs/execution/engine.js

@@ -658,6 +658,7 @@ class AgentCoreEngine {
                     throw new errors_js_2.WorkflowContractError('Prepared model call belongs to another execution or model');
                 const runner = owner?.runner ?? runnerFor(request.modelId);
                 return runner.invoke({
+                    logger: request.logger,
                     stageId: request.stageId,
                     maxOutputTokens: request.maxOutputTokens,
                     transport: request.transport,
@@ -897,14 +898,14 @@ class AgentCoreEngine {
             try {
                 const result = (0, synchronous_js_1.synchronous)(report(), 'Workflow reports must be synchronous');
                 reports?.receive(result);
-                detail = { payload: structuredClone(result.payload), subs: result.subs };
+                detail = { payload: structuredClone(result.payload) };
             }
             catch {
                 /* A report cannot suppress the workflow event. */
             }
         }
         reports?.close();
-        diagnostics?.emit('workflow.event', () => ({ event, ...(detail?.payload === undefined ? {} : { payload: detail.payload }) }), reports?.debug(detail));
+        diagnostics?.emit('workflow.event', () => ({ event, ...(detail?.payload === undefined ? {} : { payload: detail.payload }) }), reports?.debug());
         return event;
     }
     /**

package/dist/cjs/execution/events.js

@@ -12,7 +12,7 @@ exports.executionEvents = executionEvents;
  *
  * Exports: `createEventScope` and `executionEvents`.
  */
-const debug_js_1 = require("../utils/debug.js");
+const sub_flow_js_1 = require("../diagnostics/sub-flow.js");
 const invocation_js_1 = require("../utils/invocation.js");
 const errors_js_1 = require("../errors.js");
 const catalog_js_1 = require("../diagnostics/catalog.js");
@@ -66,9 +66,7 @@ function createEventScope(options = {}) {
         };
         const fact = (event, payload, debug) => {
             const value = payload();
-            const reported = scope.enabled(event, 'content')
-                ? (0, debug_js_1.captureSubSteps)(debug?.subSteps, identity)
-                : (0, debug_js_1.captureSubSteps)(undefined);
+            const reported = (0, sub_flow_js_1.captureSubFlowSnapshot)(scope.enabled(event, 'content') ? debug?.recordedSubSteps : undefined, identity);
             return {
                 ...identity,
                 ...reported,
@@ -219,7 +217,9 @@ function metadataPayload(type, payload) {
 function eventSnapshot(record, content = true) {
     const metadata = () => ({
         ...record,
-        ...(0, debug_js_1.captureSubSteps)(undefined),
+        subSteps: [],
+        subStepsDropped: 0,
+        subStepsTruncated: false,
         payload: metadataPayload(record.type, record.payload),
     });
     try {

package/dist/cjs/execution/reporting.js

@@ -26,6 +26,7 @@ class NodeReports {
     active = true;
     logger;
     usedModel;
+    steps = Object.freeze([]);
     /**
      * @param diagnostics - Diagnostic scope of the visit; omitted when observation is off.
      * @param signal - Execution signal; an aborted signal suppresses all further reports.
@@ -39,6 +40,9 @@ class NodeReports {
     /** End the visit; later reports and logger creation are ignored or rejected. */
     close() {
         this.active = false;
+        if (this.logger)
+            (0, sub_flow_js_1.detachSubFlowLogger)(this.logger);
+        this.logger = undefined;
     }
     /**
      * Validate a report and retain its model-use flag.
@@ -51,34 +55,18 @@ class NodeReports {
      */
     receive(update) {
         (0, rules_js_1.breakWhile)(!update || typeof update !== 'object', () => new TypeError('Invalid node report'));
+        (0, rules_js_1.breakWhile)(Object.hasOwn(update, 'subs'), () => new TypeError('Sub-flow logs are recorded automatically'));
         const usedModel = update.usedModel;
         (0, rules_js_1.breakWhile)(usedModel !== undefined &&
             (typeof usedModel !== 'boolean' || (this.usedModel === true && !usedModel)), () => new TypeError('Invalid reported model use'));
         if (usedModel !== undefined)
             this.usedModel = usedModel;
     }
-    /**
-     * Build the debug view of this visit.
-     *
-     * Getters keep the values live while the fact is being built; `subSteps` prefers the
-     * logger supplied in the report and falls back to the visit's own logger.
-     *
-     * @param update - Optional report whose logger replaces the visit logger.
-     * @returns A debug output object consumed by the diagnostic pipeline.
-     */
-    debug(update) {
-        const self = this;
+    /** Return the runtime-owned snapshot already received from write/fix. */
+    debug() {
         return {
-            get usedModel() {
-                return self.usedModel;
-            },
-            subSteps: () => {
-                const supplied = update?.subs;
-                const logger = supplied === undefined ? this.logger : supplied;
-                if (logger !== undefined)
-                    (0, sub_flow_js_1.readSubFlowLogger)(logger, this);
-                return logger;
-            },
+            usedModel: this.usedModel,
+            recordedSubSteps: this.steps.length ? this.steps : undefined,
         };
     }
     /**
@@ -95,7 +83,7 @@ class NodeReports {
             return;
         try {
             this.receive(update);
-            this.diagnostics?.emit('node.progress', () => this.diagnostics?.enabled('node.progress', 'content') ? { payload: update.payload } : {}, this.debug(update));
+            this.diagnostics?.emit('node.progress', () => this.diagnostics?.enabled('node.progress', 'content') ? { payload: update.payload } : {}, this.debug());
         }
         catch {
             this.diagnostics?.emit('node.progress', () => ({ reportError: 'INVALID_NODE_REPORT' }));
@@ -104,8 +92,9 @@ class NodeReports {
     /**
      * Create (once) the logger that records sub-steps for this visit.
      *
-     * Sub-steps are only collected when progress or the terminal event carries content, so
-     * a metadata-only observer pays no logging cost.
+     * Status metadata is retained for the active visit. Summary and payload capture require
+     * content permission from progress or the terminal event. The bound runtime receives
+     * every accepted revision before notifying consumers.
      *
      * @returns The visit's logger, identical on repeated calls.
      * @throws TypeError When the visit is already closed or the execution was aborted.
@@ -113,10 +102,11 @@ class NodeReports {
     createSubFlowLogger() {
         (0, rules_js_1.breakWhile)(!this.active || this.signal?.aborted, () => new TypeError('Cannot create a logger for a closed execution'));
         return (this.logger ??= (0, sub_flow_js_1.createSubFlowLogger)(this, () => this.active && !this.signal?.aborted, () => this.diagnostics?.enabled('node.progress', 'content') === true ||
-            this.diagnostics?.enabled(this.terminalEvent, 'content') === true, (logger, progress) => this.diagnostics?.emit('node.progress', () => ({ subStep: progress }), {
-            usedModel: this.usedModel,
-            subSteps: () => logger,
-        }), this.diagnostics?.identity));
+            this.diagnostics?.enabled(this.terminalEvent, 'content') === true, (_logger, progress, steps) => {
+            // Commit before notifying consumers; failed listeners cannot lose the accepted revision.
+            this.steps = steps;
+            this.diagnostics?.emit('node.progress', () => ({ subStep: progress }), this.debug());
+        }, this.diagnostics?.identity));
     }
 }
 exports.NodeReports = NodeReports;