@jangts/agent-core 0.3.5 → 0.3.6

package/dist/esm/diagnostics/index.js

@@ -17,6 +17,7 @@ import { payloadSnapshot } from './sub-flow.js';
 import { breakWhile } from '../utils/rules.js';
 export * from '../structs/diagnostics.js';
 export * from './catalog.js';
+export { SubFlowLogger, ScopedSubFlowLogger } from './sub-flow.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
 /**
  * Configure the optional log consumer of the shared execution fact source.
@@ -107,7 +108,7 @@ export 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' ||
@@ -118,7 +119,15 @@ export function normalizeDiagnosticEvent(input) {
             !Number.isSafeInteger(step.sequence) ||
             step.sequence < 1 ||
             (step.status !== undefined && !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) ||
@@ -133,6 +142,37 @@ export 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.
+        breakWhile(!['write', 'fix'].includes(step.operation) || step.sequence <= lastSequence, () => new TypeError('Invalid sub-flow record order'));
+        lastSequence = step.sequence;
+        if (step.operation === 'write') {
+            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);
+            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)
@@ -145,8 +185,14 @@ export function normalizeDiagnosticEvent(input) {
         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/esm/diagnostics/native-sub-flow.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Optional fixed sub-flow records for native execution boundaries.
+ *
+ * Callers choose the logger explicitly. A full logger issues a scoped delegate for this call; already-scoped Kit contexts reuse
+ * their delegate. Neither path creates storage or changes execution and cancellation.
+ * Logging failures are isolated from the wrapped operation.
+ *
+ * Exports: nativeSubFlowCatalog, nativeSubFlowSync, nativeSubFlowAsync.
+ */
+import type { SubFlowLog, ScopedSubFlowLogger } from '../structs/debug.js';
+/** Fixed metadata shared by native producers; pure getters and formatters are not producers. */
+export declare const nativeSubFlowCatalog: {
+    readonly model: {
+        readonly name: "Model call";
+        readonly kind: "model";
+        readonly type: "model.call";
+    };
+    readonly tool: {
+        readonly name: "Tool call";
+        readonly kind: "tool";
+        readonly type: "tool.call";
+    };
+    readonly invocation: {
+        readonly name: "Invocation";
+        readonly kind: "invocation";
+        readonly type: "handler.call";
+    };
+    readonly retrieval: {
+        readonly name: "Retrieval";
+        readonly kind: "retrieval";
+        readonly type: "retrieval.run";
+    };
+    readonly task: {
+        readonly name: "Read answer evidence";
+        readonly kind: "retrieval";
+        readonly type: "evidence.read";
+    };
+    readonly check: {
+        readonly name: "Check answer";
+        readonly kind: "validation";
+        readonly type: "answer.check";
+    };
+    readonly output: {
+        readonly name: "Compose output";
+        readonly kind: "presentation";
+        readonly type: "output.compose";
+    };
+    readonly answer: {
+        readonly name: "Answer flow";
+        readonly kind: "answering";
+        readonly type: "answer.run";
+    };
+    readonly retry: {
+        readonly name: "Retry model proposal";
+        readonly kind: "recovery";
+        readonly type: "model.retry";
+    };
+    readonly context: {
+        readonly name: "Process context";
+        readonly kind: "context";
+        readonly type: "context.process";
+    };
+    readonly recovery: {
+        readonly name: "Recovery attempt";
+        readonly kind: "recovery";
+        readonly type: "recovery.try";
+    };
+    readonly delivery: {
+        readonly name: "Deliver result";
+        readonly kind: "delivery";
+        readonly type: "delivery.run";
+    };
+    readonly aggregation: {
+        readonly name: "Aggregate queries";
+        readonly kind: "retrieval";
+        readonly type: "queries.collect";
+    };
+    readonly knowledge: {
+        readonly name: "Read knowledge";
+        readonly kind: "retrieval";
+        readonly type: "knowledge.read";
+    };
+};
+type Producer = keyof typeof nativeSubFlowCatalog;
+type Context = {
+    readonly logger?: SubFlowLog;
+    readonly signal?: AbortSignal;
+    readonly invocationId?: string;
+};
+/** Preserve a synchronous boundary while pairing an optional write with one result revision. */
+export declare function nativeSubFlowSync<Value>(context: Context, producer: Producer, id: string, invoke: (logger?: ScopedSubFlowLogger) => Value): Value;
+/** Await the original operation without introducing another timeout or cancellation race. */
+export declare function nativeSubFlowAsync<Value>(context: Context, producer: Producer, id: string, invoke: (logger?: ScopedSubFlowLogger) => Value | PromiseLike<Value>): Promise<Value>;
+export {};

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

@@ -0,0 +1,101 @@
+import { SubFlowLogger, requireSubFlowLogger, bindNativeSubFlowLogger } from './sub-flow.js';
+/** Fixed metadata shared by native producers; pure getters and formatters are not producers. */
+export const 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 SubFlowLogger
+                ? 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({
+                ...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. */
+export function nativeSubFlowSync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        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. */
+export async function nativeSubFlowAsync(context, producer, id, invoke) {
+    if (producer === 'model' || producer === 'tool' || producer === 'invocation')
+        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;
+    }
+}

package/dist/esm/diagnostics/sub-flow.d.ts

@@ -1,5 +1,12 @@
-import type { RecordedSubStep, SubFlowLogger, SubStepProgress, SubFlowValue } from '../structs/debug.js';
+import type { RecordedSubStep, SubFlowLog, SubFlowStepInput, SubFlowStepFix, SubStepProgress, SubFlowValue } from '../structs/debug.js';
 import type { DiagnosticIdentity } from '../structs/diagnostics.js';
+type Step = RecordedSubStep & Required<Pick<RecordedSubStep, 'createdAtMs' | 'revision' | 'status'>>;
+/** Validate a committed snapshot without consulting its logger or invoking App code. */
+export declare function captureSubFlowSnapshot(steps: readonly Readonly<RecordedSubStep>[] | undefined, identity?: Readonly<DiagnosticIdentity>): {
+    subSteps: readonly Readonly<RecordedSubStep>[];
+    subStepsDropped: number;
+    subStepsTruncated: boolean;
+};
 /**
  * Validate and deep-copy a reported payload.
  *
@@ -14,6 +21,48 @@ import type { DiagnosticIdentity } from '../structs/diagnostics.js';
  *   limits below.
  */
 export declare function payloadSnapshot(input: unknown): Readonly<Record<string, SubFlowValue>>;
+/** Stable diagnostic reasons; untrusted error text and caller payloads never reach the console. */
+declare const rejectionReasons: {
+    readonly inactive: "logger is detached or execution is cancelled";
+    readonly scope: "target does not belong to this subnode";
+    readonly target: "original write record was not found";
+    readonly fields: "input contains a forbidden field";
+    readonly transition: "status transition is not allowed";
+    readonly sealed: "an established fact cannot be overwritten";
+    readonly limit: "recording limit exceeded";
+    readonly input: "invalid input or result patch";
+};
+type RejectionReason = keyof typeof rejectionReasons;
+/** Unexported issuance token prevents constructing counterfeit full or scoped loggers. */
+declare const loggerToken: unique symbol;
+type Store = SubFlowLog & {
+    owns(stepId: string | -1, subnodeId: string): boolean;
+    isActive(): boolean;
+    nextNativeSubnodeId(kind: string, definitionId: string): string;
+    warn(operation: 'write' | 'fix', reason: RejectionReason): void;
+};
+/** Full execution-owned recorder. Owns its store and may issue restricted delegates. */
+export declare class SubFlowLogger implements SubFlowLog {
+    #private;
+    constructor(token: typeof loggerToken, store: Store);
+    write(input: SubFlowStepInput): string | -1;
+    fix(stepId: string | -1, patch: SubFlowStepFix): boolean;
+    readAll(): readonly Readonly<RecordedSubStep>[];
+    /** Issue a delegate for an App-owned logical group; no execution or scheduling is implied. */
+    fork(subnodeId: string): ScopedSubFlowLogger;
+}
+/** Non-inheriting delegate. Stores only the original logger and its bound subnode identity. */
+export declare class ScopedSubFlowLogger implements SubFlowLog {
+    #private;
+    constructor(token: typeof loggerToken, logger: SubFlowLogger, subnodeId: string);
+    write(input: Omit<SubFlowStepInput, 'subnodeId'>): string | -1;
+    fix(stepId: string | -1, patch: SubFlowStepFix): boolean;
+    readAll(): readonly Readonly<RecordedSubStep>[];
+}
+/** Runtime check complements nominal invocation types; scoped or forged inputs cannot invoke. */
+export declare function requireSubFlowLogger(logger: unknown): asserts logger is SubFlowLogger | undefined;
+/** Allocate a short node-local group; the owning node visit already supplies the namespace. */
+export declare function bindNativeSubFlowLogger(logger: SubFlowLogger, kind: string, definitionId: string): ScopedSubFlowLogger;
 /**
  * Create a logger bound to one active execution visit.
  *
@@ -22,14 +71,14 @@ export declare function payloadSnapshot(input: unknown): Readonly<Record<string,
  *
  * @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.
  */
-export declare function createSubFlowLogger(owner: object, active: () => boolean, content: () => boolean, changed: (logger: SubFlowLogger, progress: SubStepProgress) => void, identity?: Readonly<DiagnosticIdentity>): SubFlowLogger;
+export declare function createSubFlowLogger(owner: object, active: () => boolean, content: () => boolean, changed: (logger: SubFlowLogger, progress: SubStepProgress, steps: readonly Step[]) => void, identity?: Readonly<DiagnosticIdentity>): SubFlowLogger;
 /**
  * Read the steps recorded by a logger issued by this module.
  *
@@ -44,3 +93,6 @@ export declare function createSubFlowLogger(owner: object, active: () => boolean
  *   belongs to another diagnostic scope.
  */
 export declare function readSubFlowLogger(input: unknown, owner?: object, identity?: Readonly<DiagnosticIdentity>): readonly Readonly<RecordedSubStep>[];
+/** Release execution callbacks while preserving the instance's immutable query history. */
+export declare function detachSubFlowLogger(logger: SubFlowLogger): void;
+export {};