@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/support/stream-events.js

@@ -1,7 +1,28 @@
 "use strict";
+/**
+ * Bounded event plumbing for applications that must forward streamed output under cancellation.
+ *
+ * A producer pushes events one at a time and waits for each to be consumed; the consumer pulls
+ * from an async iterable. There is no unbounded queue, so a slow consumer slows the producer
+ * instead of growing memory, and aborting the signal closes both sides.
+ *
+ * Main export: `streamEvents`.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.streamEvents = streamEvents;
-/** One-slot rendezvous: consuming an event releases the producer; no unbounded model-output queue. */
+/**
+ * Bridge a push-style producer to a pull-style async iterable with a one-slot rendezvous.
+ *
+ * The producer must await every `emit` call before emitting again; concurrent emissions are
+ * rejected rather than buffered. The slot is released only after the consumer receives the event,
+ * so backpressure is exact.
+ *
+ * @param operation Producer that receives an `emit` callback and runs to completion.
+ * @param context Execution context carrying the abort signal used to close the rendezvous.
+ * @returns An async iterable yielding each event in production order.
+ * @throws The producer's error, or the signal's abort reason when cancelled. Also rejects an
+ *   `emit` that overlaps another, occurs after close, or is never consumed by the consumer.
+ */
 async function* streamEvents(operation, { signal }) {
     let slot;
     let wake;
@@ -9,24 +30,53 @@ async function* streamEvents(operation, { signal }) {
     let sending = false;
     let failure;
     let rejectSend;
-    const notify = () => { wake?.(); wake = undefined; };
-    const abort = () => { closed = true; rejectSend?.(signal.reason ?? new Error('Stream closed')); notify(); };
+    const notify = () => {
+        wake?.();
+        wake = undefined;
+    };
+    const abort = () => {
+        closed = true;
+        rejectSend?.(signal.reason ?? new Error('Stream closed'));
+        notify();
+    };
     signal.addEventListener('abort', abort, { once: true });
     if (signal.aborted)
         abort();
-    const producer = Promise.resolve().then(() => {
+    const producer = Promise.resolve()
+        .then(() => {
         signal.throwIfAborted();
         // Before the producer starts, only abort can close this rendezvous; the
         // signal check above already rejects it with the original reason.
-        return operation(event => {
+        return operation((event) => {
             if (closed || signal.aborted)
                 return Promise.reject(signal.reason ?? new Error('Stream closed'));
             if (sending)
                 return Promise.reject(new Error('Event producers must await delivery'));
             sending = true;
-            return new Promise((resolve, reject) => { rejectSend = reject; slot = { event, release: () => { sending = false; resolve(); }, cancel: () => { sending = false; reject(new Error('Stream closed before event consumption')); } }; notify(); });
+            return new Promise((resolve, reject) => {
+                rejectSend = reject;
+                slot = {
+                    event,
+                    release: () => {
+                        sending = false;
+                        resolve();
+                    },
+                    cancel: () => {
+                        sending = false;
+                        reject(new Error('Stream closed before event consumption'));
+                    },
+                };
+                notify();
+            });
         });
-    }).catch(error => { failure = { error }; }).finally(() => { done = true; notify(); });
+    })
+        .catch((error) => {
+        failure = { error };
+    })
+        .finally(() => {
+        done = true;
+        notify();
+    });
     try {
         while (true) {
             signal.throwIfAborted();
@@ -51,7 +101,9 @@ async function* streamEvents(operation, { signal }) {
                 return;
             }
             else
-                await new Promise(resolve => { wake = resolve; });
+                await new Promise((resolve) => {
+                    wake = resolve;
+                });
         }
     }
     finally {

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

@@ -1,5 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createToolRegistry = void 0;
+/**
+ * Re-export barrel: exposes the Core tool registry factory to Support consumers.
+ *
+ * Core owns the registry implementation; Support only re-exports it so applications can bind a
+ * `ToolCatalog` without importing internal paths. No behavior is added here.
+ */
 var tool_runtime_js_1 = require("../capabilities/tool-runtime.js");
 Object.defineProperty(exports, "createToolRegistry", { enumerable: true, get: function () { return tool_runtime_js_1.createToolRegistry; } });

package/dist/cjs/support/tools.js

@@ -2,42 +2,111 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineTool = defineTool;
 exports.defineToolCatalog = defineToolCatalog;
+/**
+ * Tool support: turn typed application tool definitions into a Core-schedulable tool catalog.
+ *
+ * A tool declaration pairs an input schema with authorization, execution and output parsing. The
+ * catalog projects those tools into model capabilities and binds them to the Core tool registry
+ * when a runtime request supplies the application. Support only assembles the registration; Core
+ * still performs authorization, invocation, budgets and cancellation.
+ *
+ * Main exports: `defineTool` and `defineToolCatalog`.
+ */
 const model_js_1 = require("../capabilities/model.js");
 const tool_runtime_js_1 = require("./tool-runtime.js");
 const schema_js_1 = require("./schema.js");
 const catalog_js_1 = require("../utils/catalog.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
+/**
+ * Validate one tool declaration and freeze a detached copy of it.
+ *
+ * `authorize` must settle with `void`; a rejection has to be thrown, so a returned `false` cannot
+ * silently pass. Handlers are bound to the declaration object, and the input schema is
+ * re-snapshotted so later mutation cannot widen the accepted input.
+ *
+ * @param definition Tool declaration whose `id` is preserved as a literal type.
+ * @returns A frozen tool definition with a snapshotted `inputSchema`.
+ * @throws {TypeError} When `id`, `kind` or `description` is blank, when a handler is missing, or
+ *   when `authorize` returns a value instead of throwing.
+ */
 function defineTool(definition) {
     const { id, kind, description } = definition;
     if (!id?.trim() || !kind?.trim() || !description?.trim())
         throw new TypeError('Invalid tool identity');
-    if (typeof definition.authorize !== 'function' || typeof definition.execute !== 'function' || typeof definition.parseOutput !== 'function')
+    if (typeof definition.authorize !== 'function' ||
+        typeof definition.execute !== 'function' ||
+        typeof definition.parseOutput !== 'function')
         throw new TypeError('Missing tool handler');
     const inputSchema = (0, schema_js_1.defineSchema)(definition.inputSchema);
     const authorize = definition.authorize.bind(definition);
-    return Object.freeze({ id, kind, description, inputSchema,
+    return Object.freeze({
+        id,
+        kind,
+        description,
+        inputSchema,
         authorize(input, context) {
             return (0, synchronous_js_1.maybeAssertion)(authorize(input, context), 'Authorization must return void; rejection must throw');
         },
         execute: definition.execute.bind(definition),
         debugSteps: definition.debugSteps?.bind(definition),
-        parseOutput: definition.parseOutput.bind(definition), });
+        parseOutput: definition.parseOutput.bind(definition),
+    });
 }
+/**
+ * Compile tool declarations into a frozen catalog with model capabilities and runtime binding.
+ *
+ * Each tool becomes a model capability whose resolver returns `{ toolId, input }`; the model only
+ * chooses among registered tools, it never invokes them directly.
+ *
+ * @param definitions Tool declarations in catalog order.
+ * @returns A frozen catalog with `capabilities`, `select` and `bind`.
+ * @throws {TypeError} When a tool declaration is invalid or a tool ID is duplicated.
+ */
 function defineToolCatalog(definitions) {
-    const entries = definitions.map(definition => defineTool(definition));
-    const view = (0, catalog_js_1.readonlyCatalog)(entries, id => new TypeError(`Unknown tool: ${id}`));
-    const capabilities = new model_js_1.ModelCapabilityRegistry(entries.map(tool => ({ id: tool.id, description: tool.description, inputSchema: (0, schema_js_1.defineSchema)({ jsonSchema: tool.inputSchema.jsonSchema, parse: (input) => input }),
+    const entries = definitions.map((definition) => defineTool(definition));
+    const view = (0, catalog_js_1.readonlyCatalog)(entries, (id) => new TypeError(`Unknown tool: ${id}`));
+    const capabilities = new model_js_1.ModelCapabilityRegistry(entries.map((tool) => ({
+        id: tool.id,
+        description: tool.description,
+        inputSchema: (0, schema_js_1.defineSchema)({
+            jsonSchema: tool.inputSchema.jsonSchema,
+            parse: (input) => input,
+        }),
         resolve: (input) => ({ toolId: tool.id, input }),
     }))).seal();
-    return Object.freeze({ ...view, capabilities,
-        select(ids) { capabilities.select(ids); return defineToolCatalog(ids.map(id => view.require(id))); },
+    return Object.freeze({
+        ...view,
+        capabilities,
+        /**
+         * Narrow the catalog to the given tool IDs, preserving their declaration order.
+         *
+         * @param ids Registered tool IDs to keep.
+         * @returns A new catalog containing only the selected tools.
+         * @throws {TypeError} When an ID is not registered in this catalog.
+         */
+        select(ids) {
+            capabilities.select(ids);
+            return defineToolCatalog(ids.map((id) => view.require(id)));
+        },
+        /**
+         * Bind the catalog to one application runtime request.
+         *
+         * @param request Runtime request supplying the app and optional execution/error ports.
+         * @returns A frozen runtime whose `invoke`/`invokeSync` delegate to the Core tool registry.
+         * @throws {TypeError} When the request does not carry an `app`.
+         */
         bind(request) {
             if (!request || !('app' in request))
                 throw new TypeError('A runtime request requires app');
             const registry = (0, tool_runtime_js_1.createToolRegistry)(entries, request.app, {
-                execution: request.execution, errors: request.errors,
+                execution: request.execution,
+                errors: request.errors,
             });
-            return Object.freeze({ capabilities, get events() { return registry.events; },
+            return Object.freeze({
+                capabilities,
+                get events() {
+                    return registry.events;
+                },
                 invokeSync: registry.invoke.bind(registry),
                 invoke: registry.invokeAsync.bind(registry),
             });

package/dist/cjs/support/transport/index.js

@@ -14,5 +14,12 @@ 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 });
+/**
+ * Transport helpers for hosts that own their own HTTP response lifecycle.
+ *
+ * `./sse.js` covers server-sent events (reading, encoding and cancellable writes) and
+ * `./json.js` covers framed JSON scanning. Both are mechanical utilities: the host decides which
+ * traffic, frames and content are acceptable.
+ */
 __exportStar(require("./sse.js"), exports);
 __exportStar(require("./json.js"), exports);

package/dist/cjs/support/transport/json.js

@@ -34,7 +34,13 @@ function* scan(text) {
     if (depth || quoted)
         throw new Error('Incomplete JSON transport');
 }
-/** Extract complete object-shaped spans in surrounding text, without parsing or selecting them. */
+/**
+ * Extract complete object-shaped spans from surrounding text, without parsing or selecting them.
+ *
+ * @param text Streamed text possibly containing JSON objects and unrelated content.
+ * @returns Raw object spans in source order.
+ * @throws {Error} When the text ends inside an unterminated object or string.
+ */
 function scanJsonObjectFrames(text) {
     const frames = [];
     for (const part of scan(text))
@@ -42,10 +48,26 @@ function scanJsonObjectFrames(text) {
             frames.push(part.text);
     return frames;
 }
-/** Scan complete object frames only; never repair, truncate or interpret their fields. */
+/**
+ * Parse complete object frames under explicit count and size limits.
+ *
+ * Only whitespace may appear outside frames; a stray closing brace is tolerated only up to
+ * `maxExtraClosings`, which covers transports that repeat the delimiter after the payload.
+ *
+ * @param text Streamed text to scan.
+ * @param limits Frame count, size and stray-closer allowances; validated before scanning.
+ * @returns Parsed frames in source order.
+ * @throws {TypeError} When a limit is not a safe integer or falls outside its allowed range.
+ * @throws {Error} When a limit is exceeded, content outside a frame is not whitespace, or the
+ *   transport ends before at least one complete frame exists.
+ */
 function parseJsonFrames(text, limits) {
-    if (!Number.isSafeInteger(limits.maxFrames) || limits.maxFrames < 1
-        || !Number.isSafeInteger(limits.maxExtraClosings) || limits.maxExtraClosings < 0)
+    if (!Number.isSafeInteger(limits.maxFrames) ||
+        limits.maxFrames < 1 ||
+        !Number.isSafeInteger(limits.maxExtraClosings) ||
+        limits.maxExtraClosings < 0 ||
+        (limits.maxFrameChars !== undefined &&
+            (!Number.isSafeInteger(limits.maxFrameChars) || limits.maxFrameChars < 1)))
         throw new TypeError('Invalid JSON frame limits');
     const frames = [];
     let extraClosings = 0;
@@ -53,6 +75,8 @@ function parseJsonFrames(text, limits) {
         if (part.kind === 'frame') {
             if (frames.length >= limits.maxFrames)
                 throw new Error('JSON frame limit exceeded');
+            if (limits.maxFrameChars !== undefined && part.text.length > limits.maxFrameChars)
+                throw new Error('JSON frame size exceeded');
             frames.push(JSON.parse(part.text));
         }
         else if (part.text === '}') {

package/dist/cjs/support/transport/sse.js

@@ -11,12 +11,35 @@ Object.defineProperty(exports, "readSse", { enumerable: true, get: function () {
 Object.defineProperty(exports, "SseIdleTimeoutError", { enumerable: true, get: function () { return sse_1.SseIdleTimeoutError; } });
 var abortable_stream_1 = require("@jangts/streaming/abortable-stream");
 Object.defineProperty(exports, "abortableStream", { enumerable: true, get: function () { return abortable_stream_1.abortableStream; } });
+/**
+ * Encode one event in the server-sent events wire format.
+ *
+ * Every line of `data` gets its own `data:` field, because a raw newline would start a new field.
+ *
+ * @param event Event name and payload to encode.
+ * @returns The complete frame, terminated by a blank line.
+ * @throws {TypeError} When the event name contains a newline, which would corrupt the frame.
+ */
 function encodeSseEvent(event) {
     if (/[\r\n]/.test(event.event))
         throw new TypeError('SSE event name cannot contain a newline');
-    return `event: ${event.event}\n${event.data.split(/\r\n|\r|\n/).map(line => `data: ${line}\n`).join('')}\n`;
+    return `event: ${event.event}\n${event.data
+        .split(/\r\n|\r|\n/)
+        .map((line) => `data: ${line}\n`)
+        .join('')}\n`;
 }
-/** The host owns its HTTP response and lifecycle; this utility handles cancellable backpressure. */
+/**
+ * Write one encoded frame and wait for drain when the writer reports backpressure.
+ *
+ * The signal is re-checked around the write and the drain wait, so cancellation does not leave a
+ * pending write considered successful.
+ *
+ * @param request Writer plus the already encoded frame.
+ * @param context Execution context carrying the abort signal.
+ * @returns Resolves once the frame is accepted or the writer drains.
+ * @throws The signal's abort reason, or {@link TypeError} when `write` does not return a boolean
+ *   synchronously.
+ */
 async function writeSseFrame({ writer, frame }, { signal }) {
     signal.throwIfAborted();
     const ready = (0, synchronous_js_1.booleanResult)(writer.write(frame), 'SSE writes must return boolean synchronously');

package/dist/cjs/utils/break-observer.js

@@ -3,12 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.configureBreakWhile = configureBreakWhile;
 exports.observeBreak = observeBreak;
 let onBreak;
+// Re-entrancy guard: an observer that itself calls breakWhile would otherwise recurse
+// until the stack overflows.
 let notifying = false;
-/** Hosts may install a diagnostic observer; no logging or persistence is enabled by default. */
+/**
+ * Install the host-owned break observer.
+ *
+ * No logging or persistence is enabled by default; passing no argument (or an empty
+ * config) removes any previously installed observer.
+ *
+ * @param config - Observation configuration; `onBreak` receives one frozen event per rejection.
+ */
 function configureBreakWhile(config = {}) {
     onBreak = config.onBreak;
 }
-/** Diagnostic failures must never replace the original interruption. */
+/**
+ * Notify the installed observer about a rejection.
+ *
+ * The original interruption is authoritative: observer failures, and rejections of the
+ * promise an observer returns, are swallowed.
+ *
+ * @param error - The value that is about to be thrown by `breakWhile`.
+ * @param tags - Call-site tags supplied by the caller of `breakWhile`.
+ * @param rule - The failing check, whose own tags are merged into the reported set.
+ */
 function observeBreak(error, tags, rule) {
     if (!onBreak || notifying)
         return;

package/dist/cjs/utils/cancellation.js

@@ -5,8 +5,24 @@ exports.combineSignals = combineSignals;
 exports.awaitWithSignal = awaitWithSignal;
 exports.awaitAssertion = awaitAssertion;
 exports.createDeadlineSignal = createDeadlineSignal;
+/**
+ * Cancellation and deadline plumbing shared by the model runner and the engine.
+ *
+ * Every helper here treats an abort signal as a pure lifetime bound: it may only
+ * shorten waiting, never extend it, and it never replaces a caller-supplied parent
+ * signal. Exports: `isTimeoutReason`, `combineSignals`, `awaitWithSignal`,
+ * `awaitAssertion` and `createDeadlineSignal`.
+ */
 const synchronous_js_1 = require("./synchronous.js");
-/** Cancellation reasons are arbitrary thrown values, including hostile objects. */
+/**
+ * Detect a deadline expiry as opposed to any other cancellation.
+ *
+ * The reason of an aborted signal is an arbitrary thrown value, including hostile
+ * objects whose `name` getter throws, so the lookup is guarded.
+ *
+ * @param reason - Value delivered as `signal.reason`.
+ * @returns True when the reason is named `TimeoutError`.
+ */
 function isTimeoutReason(reason) {
     try {
         return reason?.name === 'TimeoutError';
@@ -15,12 +31,36 @@ function isTimeoutReason(reason) {
         return false;
     }
 }
-/** Optional request signals only shorten the lifetime; deduplicate without replacing a parent. */
+/**
+ * Merge optional signals into one lifetime bound.
+ *
+ * Duplicates are removed first so a signal appearing both as an execution parent and
+ * as a request signal does not allocate a redundant composite. When nothing is
+ * supplied a fresh, never-aborting signal is returned, which keeps callers free of
+ * undefined checks.
+ *
+ * @param sources - Candidate signals in precedence-free order; `undefined` entries are ignored.
+ * @returns A signal that aborts as soon as any supplied signal aborts.
+ */
 function combineSignals(...sources) {
-    const signals = [...new Set(sources.filter((signal) => signal !== undefined))];
-    return signals.length > 1 ? AbortSignal.any(signals) : signals[0] ?? new AbortController().signal;
+    const signals = [
+        ...new Set(sources.filter((signal) => signal !== undefined)),
+    ];
+    return signals.length > 1
+        ? AbortSignal.any(signals)
+        : (signals[0] ?? new AbortController().signal);
 }
-/** Abandon waiting, but keep observing late rejection and remove the abort listener. */
+/**
+ * Race a pending value against an abort signal.
+ *
+ * Abandoning the wait does not cancel the underlying work: a late rejection is still
+ * consumed to avoid an unhandled rejection, and the abort listener is always removed.
+ *
+ * @param value - Value or promise to await; `undefined` keeps the same await semantics.
+ * @param signal - Optional lifetime bound; without it the value is awaited unchanged.
+ * @returns The resolved value.
+ * @throws The signal reason when aborted, or the rejection of `value`.
+ */
 async function awaitWithSignal(value, signal) {
     if (!signal)
         return value;
@@ -38,14 +78,37 @@ async function awaitWithSignal(value, signal) {
         signal.removeEventListener('abort', abort);
     }
 }
-/** Authorization and validation hooks may await, but only void means success. */
+/**
+ * Run an assertion that may be asynchronous, bounded by a signal.
+ *
+ * Only a `void` result counts as success, so a hook that discards its decision as a
+ * boolean is rejected rather than silently treated as passing. The signal is checked
+ * before and after the hook so a decision produced after cancellation is discarded.
+ *
+ * @param check - Hook invoked once; may return a promise.
+ * @param signal - Lifetime bound for the hook and its result.
+ * @param message - Message for the TypeError raised when the hook does not return void.
+ * @returns A promise resolved once the assertion passed.
+ * @throws The signal reason when aborted, the hook's rejection, or the assertion TypeError.
+ */
 async function awaitAssertion(check, signal, message) {
     signal.throwIfAborted();
     const result = await awaitWithSignal(check(), signal);
     signal.throwIfAborted();
     (0, synchronous_js_1.assertion)(result, message);
 }
-/** Chunk timers exceeding the platform limit without shortening the persisted deadline. */
+/**
+ * Abort at an absolute wall-clock deadline, combined with a parent signal.
+ *
+ * Timers above the platform maximum are chunked instead of being clamped, so the
+ * persisted deadline is never shortened. The deadline is recomputed from the clock on
+ * each chunk, which keeps the effective expiry correct across timer drift.
+ *
+ * @param deadline - Absolute deadline in epoch milliseconds.
+ * @param parent - Additional lifetime bound, typically the execution signal.
+ * @param now - Clock source; injectable for tests.
+ * @returns The combined `signal` and a `dispose` function that cancels the pending timer.
+ */
 function createDeadlineSignal(deadline, parent, now = Date.now) {
     const controller = new AbortController();
     let timer;
@@ -57,6 +120,11 @@ function createDeadlineSignal(deadline, parent, now = Date.now) {
             timer = setTimeout(schedule, Math.min(remaining, 2147483647));
     };
     schedule();
-    return { signal: combineSignals(parent, controller.signal), dispose() { if (timer !== undefined)
-            clearTimeout(timer); } };
+    return {
+        signal: combineSignals(parent, controller.signal),
+        dispose() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
 }

package/dist/cjs/utils/catalog.js

@@ -1,7 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readonlyCatalog = readonlyCatalog;
-/** Entries are compiled/snapshotted by the owning module; this exposes no mutable Map. */
+/**
+ * Build a frozen catalog from an iterable of definitions.
+ *
+ * Ids must be non-empty after trimming and unique; both violations surface as a
+ * TypeError during construction rather than on first lookup.
+ *
+ * @param definitions - Definitions to snapshot; iteration order is preserved in `definitions`.
+ * @param missing - Factory for the error thrown by `require` when an id is absent.
+ * @returns A frozen catalog; `get` is unguarded while `require` throws via `missing`.
+ * @throws TypeError When an id is blank or duplicated.
+ */
 function readonlyCatalog(definitions, missing) {
     const byId = new Map();
     for (const definition of definitions) {
@@ -10,9 +20,14 @@ function readonlyCatalog(definitions, missing) {
         byId.set(definition.id, definition);
     }
     const snapshot = Object.freeze([...byId.values()]);
-    return Object.freeze({ definitions: snapshot, ids: () => Object.freeze([...byId.keys()]),
-        values: () => byId.values(), entries: () => byId.entries(), has: (id) => byId.has(id),
-        get: (id) => byId.get(id), require(id) {
+    return Object.freeze({
+        definitions: snapshot,
+        ids: () => Object.freeze([...byId.keys()]),
+        values: () => byId.values(),
+        entries: () => byId.entries(),
+        has: (id) => byId.has(id),
+        get: (id) => byId.get(id),
+        require(id) {
             const value = byId.get(id);
             if (value === undefined)
                 throw missing(id);

package/dist/cjs/utils/debug.js

@@ -3,14 +3,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureSubSteps = captureSubSteps;
 const sub_flow_js_1 = require("../diagnostics/sub-flow.js");
 const synchronous_js_1 = require("./synchronous.js");
-/** Only execution-owned logger instances can produce new child log arrays. */
+/**
+ * Read the current sub-step log of one execution visit.
+ *
+ * A missing reader or a logger that yields nothing produces the empty shape, which
+ * lets callers spread the result unconditionally. Failures are reported as one
+ * dropped step instead of propagating, because diagnostics must not break execution.
+ *
+ * @param read - Getter for the current logger; omitted when the caller has no logger.
+ * @param identity - Diagnostic identity copied onto each captured step.
+ * @returns Frozen `subSteps`, the number of dropped steps and whether the log was truncated.
+ */
 function captureSubSteps(read, identity) {
     const empty = { subSteps: Object.freeze([]), subStepsDropped: 0, subStepsTruncated: false };
     if (!read)
         return empty;
     try {
         const logger = (0, synchronous_js_1.synchronous)(read(), 'Debug steps must be synchronous');
-        return logger === undefined ? empty : { ...empty, subSteps: (0, sub_flow_js_1.readSubFlowLogger)(logger, undefined, identity) };
+        return logger === undefined
+            ? empty
+            : { ...empty, subSteps: (0, sub_flow_js_1.readSubFlowLogger)(logger, undefined, identity) };
     }
     catch {
         return { ...empty, subStepsDropped: 1 };

package/dist/cjs/utils/index.js

@@ -15,6 +15,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.retrievalQueryKey = exports.modelProtocolError = exports.commonPrefixLength = void 0;
+/**
+ * Generic helpers shared by every other module of `@jangts/agent-core`.
+ *
+ * Nothing here knows about business prompts, stages or transports: this barrel only
+ * re-exports rule traversal, text comparison, model protocol errors and retrieval
+ * query keys. Consumers inside the package import the concrete module directly;
+ * this entry exists so cross-module reuse has one stable surface.
+ */
 __exportStar(require("./rules.js"), exports);
 var text_js_1 = require("./text.js");
 Object.defineProperty(exports, "commonPrefixLength", { enumerable: true, get: function () { return text_js_1.commonPrefixLength; } });

package/dist/cjs/utils/interaction-definition.js

@@ -1,13 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pinCommandDefinition = pinCommandDefinition;
-/** Read contract properties explicitly so prototype methods/getters survive composition. */
+/**
+ * Produce a detached copy of the contract fields of a command definition.
+ *
+ * Callbacks are rebound to the original definition so `this` keeps pointing at the
+ * source object; `undefined` entries are dropped so optional fields stay absent.
+ *
+ * @param definition - Source definition, possibly carrying inherited members.
+ * @returns A new partial definition containing only the declared contract fields.
+ */
 function pinCommandDefinition(definition) {
-    const snapshot = { ...definition, fields: definition.fields, category: definition.category, version: definition.version,
-        description: definition.description, terminal: definition.terminal, discriminator: definition.discriminator,
-        ownedFields: definition.ownedFields, additionalProperties: definition.additionalProperties, optionalPresence: definition.optionalPresence,
-        modes: definition.modes, tags: definition.tags, checks: definition.checks,
+    const snapshot = {
+        ...definition,
+        fields: definition.fields,
+        category: definition.category,
+        version: definition.version,
+        description: definition.description,
+        terminal: definition.terminal,
+        discriminator: definition.discriminator,
+        ownedFields: definition.ownedFields,
+        additionalProperties: definition.additionalProperties,
+        optionalPresence: definition.optionalPresence,
+        modes: definition.modes,
+        tags: definition.tags,
+        checks: definition.checks,
         error: typeof definition.error === 'function' ? definition.error.bind(definition) : definition.error,
-        refine: definition.refine?.bind(definition), format: definition.format?.bind(definition) };
+        refine: definition.refine?.bind(definition),
+        format: definition.format?.bind(definition),
+    };
     return Object.fromEntries(Object.entries(snapshot).filter(([, value]) => value !== undefined));
 }