@jangts/agent-core 0.1.1 → 0.2.1

package/dist/esm/diagnostics/index.js

@@ -1,3 +1,14 @@
+/**
+ * Core diagnostics surface: one execution fact source shared by live observers and an optional
+ * log consumer.
+ *
+ * `createDiagnostics` configures the consumer, `diagnosticError` turns an arbitrary thrown value
+ * into a loggable record, and `normalizeDiagnosticEvent` re-validates a persisted record before
+ * it is trusted. Payload visibility comes from the event catalog, and a failing consumer never
+ * changes execution.
+ *
+ * Exports: the factory and helpers above, the event catalog, and the diagnostic types.
+ */
 import { createEventScope } from '../execution/events.js';
 import { reportedStepStatuses } from '../structs/debug.js';
 import { getErrorInfo } from '../errors.js';
@@ -7,10 +18,26 @@ import { breakWhile } from '../utils/rules.js';
 export * from '../structs/diagnostics.js';
 export * from './catalog.js';
 export { reportedStepStatusCatalog, reportedStepStatuses } from '../structs/debug.js';
-/** Configure the optional log consumer of the shared execution fact source. */
+/**
+ * Configure the optional log consumer of the shared execution fact source.
+ *
+ * @param options.output Log consumer. Without it, events are still observable but not persisted.
+ * @param options.observe Live observer applied to this scope and every child scope.
+ * @param options.runId Run identity; a random id is generated when omitted.
+ * @param options.spanId Root span id; defaults to `run`.
+ * @returns A diagnostic context whose children share the run, sequence and consumers.
+ */
 export function createDiagnostics(options = {}) {
     return createEventScope(options);
 }
+/**
+ * Convert a thrown value into a plain record suitable as a log payload.
+ *
+ * @param error Any thrown value. Non-Errors are reported as `NonError` with their string form
+ *   and no issue details.
+ * @returns A record with name, message, stack, code, issues and whatever boundary metadata was
+ *   recorded. It never throws: an uninspectable value becomes `UninspectableError`.
+ */
 export function diagnosticError(error) {
     const info = getErrorInfo(error);
     let detail;
@@ -18,43 +45,96 @@ export function diagnosticError(error) {
         if (!(error instanceof Error))
             return { name: 'NonError', message: String(error) };
         const { name, message, stack, code } = error;
-        detail = { name, message, stack, code: code ?? (info.code === 'UNKNOWN_ERROR' ? undefined : info.code) };
+        detail = {
+            name,
+            message,
+            stack,
+            code: code ?? (info.code === 'UNKNOWN_ERROR' ? undefined : info.code),
+        };
     }
     catch {
-        detail = { name: 'UninspectableError', message: 'Error details unavailable', code: info.code === 'UNKNOWN_ERROR' ? undefined : info.code };
+        detail = {
+            name: 'UninspectableError',
+            message: 'Error details unavailable',
+            code: info.code === 'UNKNOWN_ERROR' ? undefined : info.code,
+        };
     }
-    return { ...detail, issues: info.issues,
+    return {
+        ...detail,
+        issues: info.issues,
         ...(info.stageId === undefined ? {} : { stageId: info.stageId }),
-        ...(info.isRetryable === undefined ? {} : { isRetryable: info.isRetryable }) };
+        ...(info.isRetryable === undefined ? {} : { isRetryable: info.isRetryable }),
+    };
 }
-/** Validate the current envelope and return a detached record without interpreting payloads. */
+/**
+ * Validate a persisted diagnostic record and return a detached copy.
+ *
+ * Persisted data is untrusted, so the envelope version, event type, identity, ordering and the
+ * bounded sub-step shape are checked; the payload itself is not interpreted. The copy is deep
+ * cloned, so a store cannot hand back a record that later shares structure with the caller.
+ *
+ * @param input Candidate record, typically parsed JSON from a log store.
+ * @returns A normalized record with `subSteps`, `subStepsDropped` and `subStepsTruncated`
+ *   defaulted.
+ * @throws TypeError when the envelope, identity, node role or reported steps are invalid.
+ * @throws RangeError when a reported payload is too large or too deeply nested.
+ */
 export function normalizeDiagnosticEvent(input) {
     if (!input || typeof input !== 'object')
         throw new TypeError('Invalid diagnostic record');
     const raw = input;
+    // The version gates the whole layout: an older record may use different fields, so it is
+    // rejected instead of best-effort coerced.
     if (raw.version !== 2)
         throw new TypeError('Unsupported diagnostic version');
     const { type, producerSequence, occurredAtMs } = raw;
-    if (typeof type !== 'string' || !Object.hasOwn(coreEventCatalog, type) || typeof raw.runId !== 'string' || !raw.runId
-        || typeof raw.spanId !== 'string' || !raw.spanId || !Number.isSafeInteger(producerSequence) || Number(producerSequence) < 1
-        || typeof occurredAtMs !== 'number' || !Number.isFinite(occurredAtMs) || !Object.hasOwn(raw, 'payload'))
+    if (typeof type !== 'string' ||
+        !Object.hasOwn(coreEventCatalog, type) ||
+        typeof raw.runId !== 'string' ||
+        !raw.runId ||
+        typeof raw.spanId !== 'string' ||
+        !raw.spanId ||
+        !Number.isSafeInteger(producerSequence) ||
+        Number(producerSequence) < 1 ||
+        typeof occurredAtMs !== 'number' ||
+        !Number.isFinite(occurredAtMs) ||
+        !Object.hasOwn(raw, 'payload'))
         throw new TypeError('Invalid diagnostic envelope');
     const { eventId } = raw;
     if (typeof eventId !== 'string' || !eventId)
         throw new TypeError('Invalid diagnostic event identity');
     const steps = raw.subSteps ?? [];
-    if (!Array.isArray(steps) || steps.length > 256 || new Set(steps.map(step => step?.stepId)).size !== steps.length
-        || steps.some(step => !step || step.origin !== 'reported' || typeof step.stepId !== 'string' || !step.stepId.trim()
-            || typeof step.name !== 'string' || typeof step.kind !== 'string' || !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')
-            || (step.usedModel !== undefined && typeof step.usedModel !== 'boolean')
-            || (step.revision !== undefined && (!Number.isSafeInteger(step.revision) || step.revision < 1 || !Number.isFinite(step.createdAtMs)))
-            || ['createdAtMs', 'startedAtMs', 'endedAtMs'].some(key => step[key] !== undefined && (typeof step[key] !== 'number' || !Number.isFinite(step[key]) || step[key] < 0))
-            || (step.nextStepIds !== undefined && (!Array.isArray(step.nextStepIds) || step.nextStepIds.some((id) => typeof id !== 'string'))))
-        || (raw.subStepsDropped !== undefined && (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0))
-        || (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
+    // 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 ||
+        new Set(steps.map((step) => step?.stepId)).size !== steps.length ||
+        steps.some((step) => !step ||
+            step.origin !== 'reported' ||
+            typeof step.stepId !== 'string' ||
+            !step.stepId.trim() ||
+            typeof step.name !== 'string' ||
+            typeof step.kind !== 'string' ||
+            !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') ||
+            (step.usedModel !== undefined && typeof step.usedModel !== 'boolean') ||
+            (step.revision !== undefined &&
+                (!Number.isSafeInteger(step.revision) ||
+                    step.revision < 1 ||
+                    !Number.isFinite(step.createdAtMs))) ||
+            ['createdAtMs', 'startedAtMs', 'endedAtMs'].some((key) => step[key] !== undefined &&
+                (typeof step[key] !== 'number' || !Number.isFinite(step[key]) || step[key] < 0)) ||
+            (step.nextStepIds !== undefined &&
+                (!Array.isArray(step.nextStepIds) ||
+                    step.nextStepIds.some((id) => typeof id !== 'string')))) ||
+        (raw.subStepsDropped !== undefined &&
+            (!Number.isSafeInteger(raw.subStepsDropped) || Number(raw.subStepsDropped) < 0)) ||
+        (raw.subStepsTruncated !== undefined && typeof raw.subStepsTruncated !== 'boolean'))
         throw new TypeError('Invalid reported diagnostic steps');
+    // 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)
         if (step.payload !== undefined)
             payloadSnapshot(step.payload);
@@ -62,19 +142,59 @@ export function normalizeDiagnosticEvent(input) {
     breakWhile(raw.usedModel !== undefined && typeof raw.usedModel !== 'boolean', () => new TypeError('Invalid reported model use'));
     if (type === 'node.progress') {
         const progress = raw.payload?.subStep;
-        breakWhile(progress !== undefined && (!progress || !['write', 'fix'].includes(progress.operation) || typeof progress.stepId !== 'string' || !progress.stepId
-            || !Number.isSafeInteger(progress.sequence) || progress.sequence < 1 || !Number.isSafeInteger(progress.revision) || progress.revision < 1
-            || !Number.isFinite(progress.createdAtMs) || progress.createdAtMs < 0 || !reportedStepStatuses.includes(progress.status)
-            || (progress.usedModel !== undefined && typeof progress.usedModel !== 'boolean')), () => new TypeError('Invalid reported sub-step progress'));
+        breakWhile(progress !== undefined &&
+            (!progress ||
+                !['write', 'fix'].includes(progress.operation) ||
+                typeof progress.stepId !== 'string' ||
+                !progress.stepId ||
+                !Number.isSafeInteger(progress.sequence) ||
+                progress.sequence < 1 ||
+                !Number.isSafeInteger(progress.revision) ||
+                progress.revision < 1 ||
+                !Number.isFinite(progress.createdAtMs) ||
+                progress.createdAtMs < 0 ||
+                !reportedStepStatuses.includes(progress.status) ||
+                (progress.usedModel !== undefined && typeof progress.usedModel !== 'boolean')), () => new TypeError('Invalid reported sub-step progress'));
     }
-    for (const key of ['parentSpanId', 'invocationId', 'parentInvocationId', 'workflowInvocationId', 'workflowNodeId', 'agentId', 'branchId', 'agentVersionId', 'parentBranchId', 'parentAgentVersionId', 'forkPointId', 'definitionId', 'definitionKind', 'definitionRevision', 'nodeId', 'nodeName', 'nodeKind', 'nodeDescription', 'stageId', 'modelId']) {
+    for (const key of [
+        'parentSpanId',
+        'invocationId',
+        'parentInvocationId',
+        'workflowInvocationId',
+        'workflowNodeId',
+        'agentId',
+        'branchId',
+        'agentVersionId',
+        'parentBranchId',
+        'parentAgentVersionId',
+        'forkPointId',
+        'definitionId',
+        'definitionKind',
+        'definitionRevision',
+        'nodeId',
+        'nodeName',
+        'nodeKind',
+        'nodeDescription',
+        'stageId',
+        'modelId',
+    ]) {
         if (raw[key] !== undefined && typeof raw[key] !== 'string')
             throw new TypeError('Invalid diagnostic identity');
     }
-    if (raw.nodeRole !== undefined && !['workflow-node', 'workflow-boundary', 'invocation', 'loop-step'].includes(String(raw.nodeRole)))
+    if (raw.nodeRole !== undefined &&
+        !['workflow-node', 'workflow-boundary', 'invocation', 'loop-step'].includes(String(raw.nodeRole)))
         throw new TypeError('Invalid diagnostic node role');
+    // Detached copy: the caller's object may be reused, frozen or backed by a store buffer.
     const copy = structuredClone(raw);
-    return { ...copy, version: 2, eventId, type, producerSequence, occurredAtMs,
-        subSteps: copy.subSteps ?? [], subStepsDropped: copy.subStepsDropped ?? 0,
-        subStepsTruncated: copy.subStepsTruncated ?? false };
+    return {
+        ...copy,
+        version: 2,
+        eventId,
+        type,
+        producerSequence,
+        occurredAtMs,
+        subSteps: copy.subSteps ?? [],
+        subStepsDropped: copy.subStepsDropped ?? 0,
+        subStepsTruncated: copy.subStepsTruncated ?? false,
+    };
 }

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

@@ -1,8 +1,46 @@
 import type { RecordedSubStep, SubFlowLogger, SubStepProgress, SubFlowValue } from '../structs/debug.js';
 import type { DiagnosticIdentity } from '../structs/diagnostics.js';
-/** Reject accessors, services, cycles and non-JSON values without evaluating application getters. */
+/**
+ * Validate and deep-copy a reported payload.
+ *
+ * Accessors, class instances, cycles and non-JSON values are rejected without evaluating
+ * application getters, so a payload can neither run code nor alias live state. Accepted data is
+ * frozen.
+ *
+ * @param input Object to snapshot. It must be a plain object, not an array.
+ * @returns A deeply frozen JSON-shaped copy.
+ * @throws TypeError when the value is not plain JSON data, contains a getter, or is cyclic.
+ * @throws RangeError when node count, nesting depth, string length or array length exceeds the
+ *   limits below.
+ */
 export declare function payloadSnapshot(input: unknown): Readonly<Record<string, SubFlowValue>>;
-/** Internal constructor; only active execution contexts issue logger instances. */
+/**
+ * Create a logger bound to one active execution visit.
+ *
+ * Only execution contexts inside this package should call it: the resulting object is the sole
+ * way to append reported steps to the current record.
+ *
+ * @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 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 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;
-/** Never call a lookalike's readAll method. */
+/**
+ * Read the steps recorded by a logger issued by this module.
+ *
+ * The instance is resolved through the private registry, so a lookalike's `readAll` method is
+ * never called and a logger cannot be borrowed across executions.
+ *
+ * @param input Candidate logger; must be an instance created by `createSubFlowLogger`.
+ * @param owner Expected owning execution visit. Omit to accept any owner.
+ * @param identity Expected run and span. Omit to accept any diagnostic scope.
+ * @returns The recorded steps in write order, as an immutable list shared with the logger.
+ * @throws TypeError when the value is not a registered logger, belongs to another owner, or
+ *   belongs to another diagnostic scope.
+ */
 export declare function readSubFlowLogger(input: unknown, owner?: object, identity?: Readonly<DiagnosticIdentity>): readonly Readonly<RecordedSubStep>[];