@jangts/agent-core 0.1.1 → 0.2.1

package/dist/cjs/context/journal.js

@@ -1,39 +1,116 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextJournal = void 0;
+/**
+ * Request-local journal of context-relevant execution receipts.
+ *
+ * It records what was produced (model values, tool inputs) and what came back (tool results),
+ * each stamped with a monotonic producer sequence so a snapshot replays in order. Values are
+ * deep-cloned on write and on read: a caller mutating its own object cannot retroactively
+ * change recorded history, and a snapshot is not a live window into the journal.
+ *
+ * This is a projection, not a persistent log store; storage and retention belong to the App.
+ *
+ * Exports: `ContextJournal` and the `ContextRecord` type.
+ */
 const invocation_js_1 = require("../utils/invocation.js");
 /** Request-local context projection of execution receipts; not a separate persistent log store. */
 class ContextJournal {
+    /** Append-only: `producerSequence` is derived from this length, so order is never rewritten. */
     records = [];
+    /** Duplicate invocation ids are rejected instead of overwriting earlier history. */
     invocationIds = new Set();
+    /** Open tool calls, so a result can only close a call that actually started. */
     toolCalls = new Map();
-    model({ stageId, value, invocation }) {
+    /**
+     * Record one model-produced value.
+     *
+     * @param options.stageId Stage that produced the value.
+     * @param options.value Value to record; deep-cloned on write.
+     * @param options.invocation Execution identity whose `invocationId` must not be in the journal.
+     * @returns Nothing.
+     * @throws Error when the invocation id was already recorded.
+     */
+    model({ stageId, value, invocation, }) {
         if (this.invocationIds.has(invocation.invocationId))
             throw new Error('Duplicate journal invocation');
-        this.records.push({ ...invocation, producerSequence: this.records.length + 1, occurredAtMs: Date.now(), type: 'model', stageId, value: structuredClone(value) });
+        this.records.push({
+            ...invocation,
+            // Derived from the append position, so the sequence stays gap-free without a counter.
+            producerSequence: this.records.length + 1,
+            occurredAtMs: Date.now(),
+            type: 'model',
+            stageId,
+            value: structuredClone(value),
+        });
         this.invocationIds.add(invocation.invocationId);
     }
+    /**
+     * Open a tool call.
+     *
+     * @param request Tool id, input and optional invocation metadata. A supplied invocation id is
+     *   kept so Core records and the journal share one identity; otherwise a new id is generated.
+     * @returns The invocation id that must be used to finish the call.
+     * @throws Error when a call with that id is already recorded.
+     */
     beginTool({ toolId, input, invocation }) {
         const invocationId = invocation?.invocationId ?? (0, invocation_js_1.invocationId)();
         if (this.invocationIds.has(invocationId))
             throw new Error('Duplicate journal invocation');
-        const record = { ...invocation, invocationId, startedAtMs: invocation?.startedAtMs ?? Date.now(), durationMs: 0, producerSequence: this.records.length + 1, occurredAtMs: Date.now(), type: 'tool', toolId, input: structuredClone(input) };
+        const record = {
+            ...invocation,
+            invocationId,
+            startedAtMs: invocation?.startedAtMs ?? Date.now(),
+            durationMs: 0,
+            producerSequence: this.records.length + 1,
+            occurredAtMs: Date.now(),
+            type: 'tool',
+            toolId,
+            input: structuredClone(input),
+        };
         this.records.push(record);
         this.invocationIds.add(invocationId);
         this.toolCalls.set(invocationId, { record, finished: false });
         return invocationId;
     }
+    /**
+     * Close an open tool call with its outcome.
+     *
+     * @param request Invocation id, terminal status and result value; the value is cloned into
+     *   the record.
+     * @returns Nothing.
+     * @throws Error when the call is unknown or was already finished.
+     */
     finishTool({ invocationId, status, value }) {
         const entry = this.toolCalls.get(invocationId);
         if (!entry || entry.finished)
             throw new Error('Invalid tool receipt');
         const call = entry.record;
         const occurredAtMs = Date.now();
-        this.records.push({ invocationId, runId: call.runId, spanId: call.spanId, parentSpanId: call.parentSpanId, parentInvocationId: call.parentInvocationId,
-            startedAtMs: call.startedAtMs, durationMs: occurredAtMs - call.startedAtMs,
-            producerSequence: this.records.length + 1, occurredAtMs, type: 'tool-result', toolId: call.toolId, status, value: structuredClone(value) });
+        this.records.push({
+            invocationId,
+            runId: call.runId,
+            spanId: call.spanId,
+            parentSpanId: call.parentSpanId,
+            parentInvocationId: call.parentInvocationId,
+            startedAtMs: call.startedAtMs,
+            durationMs: occurredAtMs - call.startedAtMs,
+            producerSequence: this.records.length + 1,
+            occurredAtMs,
+            type: 'tool-result',
+            toolId: call.toolId,
+            status,
+            value: structuredClone(value),
+        });
+        // Kept after finishing, so a repeated finish is rejected instead of appending a second
+        // result for the same call.
         entry.finished = true;
     }
-    snapshot() { return structuredClone(this.records); }
+    /**
+     * @returns A detached copy of every record, safe for the caller to mutate.
+     */
+    snapshot() {
+        return structuredClone(this.records);
+    }
 }
 exports.ContextJournal = ContextJournal;

package/dist/cjs/context/plan.js

@@ -1,18 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assembleContextPlan = assembleContextPlan;
+/**
+ * Assembly of a `ContextPlan`: the Core-side step between App context processing and the
+ * model input budget.
+ *
+ * A plan may carry trusted originals and an explicit mutation allow-list; when it does, the
+ * current fragments are audited before assembly. Assembly itself only validates, merges and
+ * measures. Reduction, grouping and model selection happen in App-side nodes before this
+ * point.
+ *
+ * Exports: `assembleContextPlan`.
+ */
 const audit_js_1 = require("./audit.js");
 const rules_js_1 = require("../utils/rules.js");
 const assembly_js_1 = require("./assembly.js");
 const fragments_js_1 = require("./fragments.js");
-/** Generic input assembly only. Reduction, grouping and model selection are App-side nodes. */
+/**
+ * Build the model input for a context plan.
+ *
+ * @param plan Fragments, their budget, optional protected user messages, and the optional
+ *   originals/allow-list used for the structural audit.
+ * @returns The assembled context, including appended user messages and the final character
+ *   count that was checked against the budget.
+ * @throws ValidationError when the audit fails, a fragment is invalid or over its budget, or
+ *   the combined input exceeds the budget.
+ * @throws Error when an additional message is not a user message.
+ */
 function assembleContextPlan(plan) {
+    // Audit first: a structural violation must surface as a policy error rather than be masked
+    // by a later budget or field-merge failure on fragments the plan did not allow to change.
     if (plan.originalFragments)
         (0, audit_js_1.auditContextChange)(plan.originalFragments, plan.fragments, new Set(plan.mutableFragmentIds ?? []));
     const context = (0, assembly_js_1.assembleFragments)([...plan.fragments], plan.maxInputChars);
+    // Detach caller-owned messages: the built context must not change if the plan object is
+    // reused or mutated after assembly.
     const additional = structuredClone([...(plan.additionalMessages ?? [])]);
-    (0, rules_js_1.breakWhile)(additional.some(message => message.role !== 'user' || typeof message.content !== 'string'), 'Additional context must be user messages');
+    // Only user messages may be appended: the system instruction is fixed by the fragments above.
+    (0, rules_js_1.breakWhile)(additional.some((message) => message.role !== 'user' || typeof message.content !== 'string'), 'Additional context must be user messages');
     context.messages.push(...additional);
+    // The per-fragment budget already passed; this re-check covers the appended messages, which
+    // are outside every fragment's limit.
     context.inputChars += additional.reduce((sum, message) => sum + message.content.length, 0);
     (0, fragments_js_1.validateContextBudget)(context.inputChars, context.maxInputChars);
     return context;

package/dist/cjs/diagnostics/catalog.js

@@ -1,10 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.coreEventCatalog = void 0;
+/**
+ * Default visibility tier for every event Core can emit.
+ *
+ * The same object is the allow-list used when normalizing persisted records; adding an event to
+ * `CoreEventName` without a tier here fails type checking.
+ */
 exports.coreEventCatalog = {
-    'node.progress': 'metadata', 'model.start': 'metadata',
-    'model.binding': 'metadata', 'model.prepare': 'content', 'model.output': 'content', 'model.parsed': 'content', 'model.end': 'metadata',
+    'node.progress': 'metadata',
+    'model.start': 'metadata',
+    'model.binding': 'metadata',
+    'model.prepare': 'content',
+    'model.output': 'content',
+    'model.parsed': 'content',
+    'model.end': 'metadata',
     'runtime.rejected': 'metadata',
-    'loop.event': 'metadata', 'workflow.event': 'metadata', 'tool.call': 'metadata', 'tool.result': 'metadata',
+    'loop.event': 'metadata',
+    'workflow.event': 'metadata',
+    'tool.call': 'metadata',
+    'tool.result': 'metadata',
     'rule.result': 'metadata',
 };

package/dist/cjs/diagnostics/index.js

@@ -18,6 +18,17 @@ exports.reportedStepStatuses = exports.reportedStepStatusCatalog = void 0;
 exports.createDiagnostics = createDiagnostics;
 exports.diagnosticError = diagnosticError;
 exports.normalizeDiagnosticEvent = normalizeDiagnosticEvent;
+/**
+ * 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.
+ */
 const events_js_1 = require("../execution/events.js");
 const debug_js_1 = require("../structs/debug.js");
 const errors_js_1 = require("../errors.js");
@@ -29,10 +40,26 @@ __exportStar(require("./catalog.js"), exports);
 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; } });
-/** 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.
+ */
 function createDiagnostics(options = {}) {
     return (0, events_js_1.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`.
+ */
 function diagnosticError(error) {
     const info = (0, errors_js_1.getErrorInfo)(error);
     let detail;
@@ -40,43 +67,96 @@ 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.
+ */
 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(catalog_js_1.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(catalog_js_1.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 && !debug_js_1.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 && !debug_js_1.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)
             (0, sub_flow_js_1.payloadSnapshot)(step.payload);
@@ -84,19 +164,59 @@ function normalizeDiagnosticEvent(input) {
     (0, rules_js_1.breakWhile)(raw.usedModel !== undefined && typeof raw.usedModel !== 'boolean', () => new TypeError('Invalid reported model use'));
     if (type === 'node.progress') {
         const progress = raw.payload?.subStep;
-        (0, rules_js_1.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 || !debug_js_1.reportedStepStatuses.includes(progress.status)
-            || (progress.usedModel !== undefined && typeof progress.usedModel !== 'boolean')), () => new TypeError('Invalid reported sub-step progress'));
+        (0, rules_js_1.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 ||
+                !debug_js_1.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,
+    };
 }