@jangts/agent-core 0.1.0 → 0.2.0

package/dist/cjs/model/selection-transport.js

@@ -1,37 +1,77 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createModelTransport = createModelTransport;
+/**
+ * Adapt an interaction adapter plus capability catalog into a transport.
+ *
+ * This is the seam between "how a provider expresses a call" and "what the core
+ * accepts": whatever the wire format, the transport must yield one capability id and
+ * one argument object. Capability availability is checked against the catalog captured
+ * at preparation time, so a late registration cannot be called.
+ *
+ * Exports: `createModelTransport`.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const native_functions_js_1 = require("./interactions/native-functions.js");
 const options_js_1 = require("./options.js");
 const model_protocol_js_1 = require("../utils/model-protocol.js");
-/** The transport translates a wire selection into the single Core response protocol. */
+/**
+ * Compose a registered selection transport.
+ *
+ * The capability source may be a static catalog or a function of the stage id; the
+ * resulting definitions are captured when `prepare` runs and are used both to build
+ * the instruction and to reject unknown capability ids at finish time.
+ *
+ * `requireStrictArguments` is a registration-time assertion: a transport cannot demand
+ * strict arguments from an adapter that does not support them.
+ *
+ * @param registration - Adapter, capability source, options and the transport id.
+ * @returns A frozen transport definition whose result is the resolved capability output.
+ * @throws TypeError When strict arguments are unsupported or preparation is invalid.
+ */
 function createModelTransport(registration) {
     const adapter = registration.adapter ?? native_functions_js_1.nativeFunctionInteraction;
     if (registration.requireStrictArguments && !adapter.features.strictArguments)
         throw new TypeError(`Model interaction does not support strict arguments: ${adapter.id}`);
     const source = registration.capabilities, createSource = typeof source === 'function' ? source.bind(registration) : undefined;
     const prepare = adapter.prepare.bind(adapter), options = Object.freeze((0, options_js_1.snapshotModelOptions)(registration.options));
-    return Object.freeze({ id: registration.id, prepare(stageId) {
-            const catalog = createSource ? (0, synchronous_js_1.synchronous)(createSource(stageId), 'Model capability sources must be synchronous') : source;
+    return Object.freeze({
+        id: registration.id,
+        prepare(stageId) {
+            const catalog = createSource
+                ? (0, synchronous_js_1.synchronous)(createSource(stageId), 'Model capability sources must be synchronous')
+                : source;
             const definitions = [...catalog.values()];
             if (!definitions.length)
                 throw new TypeError('Model stage requires registered capabilities');
-            const capabilityIds = new Set(definitions.map(capability => capability.id));
+            const capabilityIds = new Set(definitions.map((capability) => capability.id));
             const prepared = (0, synchronous_js_1.synchronous)(prepare(definitions), 'Model interaction preparation must be synchronous');
             const createResponse = prepared.createResponse.bind(prepared), resolve = catalog.resolve.bind(catalog);
-            return { options: { ...options, ...(0, options_js_1.snapshotModelOptions)(prepared.options) }, schemaChars: prepared.schemaChars, instruction: prepared.instruction,
+            return {
+                options: { ...options, ...(0, options_js_1.snapshotModelOptions)(prepared.options) },
+                schemaChars: prepared.schemaChars,
+                instruction: prepared.instruction,
                 createResponse() {
                     const buffer = createResponse();
                     let call;
-                    return { get outputChars() { return buffer.outputChars; }, get call() { return call; }, push: buffer.push.bind(buffer), finish() {
+                    return {
+                        get outputChars() {
+                            return buffer.outputChars;
+                        },
+                        get call() {
+                            return call;
+                        },
+                        push: buffer.push.bind(buffer),
+                        finish() {
                             const selection = (0, synchronous_js_1.synchronous)(buffer.finish(), 'Model selection parsers must be synchronous');
                             call = selection.call;
                             if (!capabilityIds.has(selection.capabilityId))
                                 (0, model_protocol_js_1.modelProtocolError)('Model capability is unavailable in this prepared call');
                             return (0, synchronous_js_1.synchronous)(resolve(selection, { stageId }), 'Model result parsers must be synchronous');
-                        } };
+                        },
+                    };
                 },
             };
-        } });
+        },
+    });
 }

package/dist/cjs/model/settings.js

@@ -1,9 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveModelSettings = resolveModelSettings;
+/**
+ * Validation and defaulting of model runner settings.
+ *
+ * This is the single place where App-supplied settings become trusted: removed option
+ * names are rejected with a migration hint, defaults are applied, and every numeric
+ * limit is range-checked before the runner binds its provider.
+ *
+ * Exports: `resolveModelSettings`.
+ */
 const defaults_js_1 = require("./defaults.js");
 const rules_js_1 = require("../utils/rules.js");
 const errors_js_1 = require("../errors.js");
+/**
+ * Validate options and fill in baseline defaults.
+ *
+ * Legacy names (`config`, `ports`, `observe`, `signal`, `contextPolicy` and friends) are
+ * rejected rather than ignored, because silently dropping them would change behavior.
+ * Returned limits are frozen; ports keep live App callbacks with their receivers bound.
+ *
+ * @param options - Runner options as supplied by the App.
+ * @returns The bound provider, frozen runtime config, input limit, ports and token limit.
+ * @throws TypeError When any option is invalid, removed or out of range.
+ */
 function resolveModelSettings(options) {
     const provider = options.provider;
     const stream = provider?.stream;
@@ -14,8 +34,16 @@ function resolveModelSettings(options) {
     };
     (0, rules_js_1.breakWhile)([
         { occur: typeof stream !== 'function', error: () => invalid('provider.stream is required') },
-        { occur: 'contextPolicy' in options || 'contextCompressors' in options || 'contextSelectors' in options, error: () => invalid('Configure context processing with explicit Workflow nodes') },
-        { occur: 'config' in options || 'ports' in options || 'observe' in options, error: () => invalid('Use named model settings and execution, sink, observe or errors') },
+        {
+            occur: 'contextPolicy' in options ||
+                'contextCompressors' in options ||
+                'contextSelectors' in options,
+            error: () => invalid('Configure context processing with explicit Workflow nodes'),
+        },
+        {
+            occur: 'config' in options || 'ports' in options || 'observe' in options,
+            error: () => invalid('Use named model settings and execution, sink, observe or errors'),
+        },
     ]);
     const defaulted = (value, fallback) => value === undefined ? fallback : value;
     const config = {
@@ -25,8 +53,10 @@ function resolveModelSettings(options) {
         usage: options.usage,
     };
     const ports = {
-        transports: options.transports, diagnostics: options.execution?.diagnostics,
-        maxSchemaChars: options.maxSchemaChars, tokenBudget: options.tokenBudget,
+        transports: options.transports,
+        diagnostics: options.execution?.diagnostics,
+        maxSchemaChars: options.maxSchemaChars,
+        tokenBudget: options.tokenBudget,
         onOutput: options.sink?.output?.bind(options.sink),
         inputBudgetError: options.errors?.inputBudget?.bind(options.errors),
         outputBudgetError: options.errors?.outputBudget?.bind(options.errors),
@@ -35,15 +65,39 @@ function resolveModelSettings(options) {
     ports.maxSchemaChars = defaulted(ports.maxSchemaChars, defaults_js_1.modelRunnerDefaults.maxSchemaChars);
     const maxInputChars = defaulted(options.maxInputChars, defaults_js_1.modelRunnerDefaults.maxInputChars);
     const maxOutputTokens = defaulted(options.maxOutputTokens, defaults_js_1.modelRunnerDefaults.maxOutputTokens);
-    const integer = (value, minimum, infinity = false) => infinity && value === Infinity
-        || typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+    const integer = (value, minimum, infinity = false) => (infinity && value === Infinity) ||
+        (typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum);
     (0, rules_js_1.breakWhile)([
-        { occur: !integer(config.maxCalls, 0), error: () => invalid('maxCalls must be a nonnegative safe integer') },
-        { occur: !integer(config.callTimeoutMs, 1) || config.callTimeoutMs > 2147483647, error: () => invalid('callTimeoutMs must be a positive supported timeout') },
-        { occur: !integer(maxInputChars, 0, true), error: () => invalid('maxInputChars must be a nonnegative safe integer or Infinity') },
-        { occur: config.maxOutputChars !== undefined && !integer(config.maxOutputChars, 0, true), error: () => invalid('maxOutputChars must be a nonnegative safe integer or Infinity') },
-        { occur: ports.maxSchemaChars !== undefined && !integer(ports.maxSchemaChars, 1), error: () => invalid('maxSchemaChars must be a positive safe integer') },
-        { occur: !integer(maxOutputTokens, 1), error: () => invalid('maxOutputTokens must be a positive safe integer') },
+        {
+            occur: !integer(config.maxCalls, 0),
+            error: () => invalid('maxCalls must be a nonnegative safe integer'),
+        },
+        {
+            occur: !integer(config.callTimeoutMs, 1) || config.callTimeoutMs > 2147483647,
+            error: () => invalid('callTimeoutMs must be a positive supported timeout'),
+        },
+        {
+            occur: !integer(maxInputChars, 0, true),
+            error: () => invalid('maxInputChars must be a nonnegative safe integer or Infinity'),
+        },
+        {
+            occur: config.maxOutputChars !== undefined && !integer(config.maxOutputChars, 0, true),
+            error: () => invalid('maxOutputChars must be a nonnegative safe integer or Infinity'),
+        },
+        {
+            occur: ports.maxSchemaChars !== undefined && !integer(ports.maxSchemaChars, 1),
+            error: () => invalid('maxSchemaChars must be a positive safe integer'),
+        },
+        {
+            occur: !integer(maxOutputTokens, 1),
+            error: () => invalid('maxOutputTokens must be a positive safe integer'),
+        },
     ]);
-    return { provider: Object.freeze({ stream: stream.bind(provider) }), maxOutputTokens, config: Object.freeze(config), maxInputChars, ports };
+    return {
+        provider: Object.freeze({ stream: stream.bind(provider) }),
+        maxOutputTokens,
+        config: Object.freeze(config),
+        maxInputChars,
+        ports,
+    };
 }

package/dist/cjs/model/token-budget.js

@@ -8,34 +8,92 @@ exports.modelInputMessages = modelInputMessages;
 const errors_js_1 = require("../structs/errors.js");
 const rules_js_1 = require("../utils/rules.js");
 const invalid = (message) => new errors_js_1.ValidationError([{ code: 'MODEL_TOKEN_BUDGET', message }]);
+/**
+ * Validate a host-supplied token budget contract.
+ *
+ * @param budget - Budget to check: counter id, context window, optional safety margin, counter.
+ * @throws ValidationError When any field is missing or out of range.
+ */
 function validateModelTokenBudget(budget) {
-    (0, rules_js_1.breakWhile)(!budget.counterId || !Number.isSafeInteger(budget.contextWindowTokens) || budget.contextWindowTokens < 1
-        || !Number.isSafeInteger(budget.safetyMarginTokens ?? 0) || (budget.safetyMarginTokens ?? 0) < 0
-        || typeof budget.countTokens !== 'function', invalid('Invalid model token budget'));
+    (0, rules_js_1.breakWhile)(!budget.counterId ||
+        !Number.isSafeInteger(budget.contextWindowTokens) ||
+        budget.contextWindowTokens < 1 ||
+        !Number.isSafeInteger(budget.safetyMarginTokens ?? 0) ||
+        (budget.safetyMarginTokens ?? 0) < 0 ||
+        typeof budget.countTokens !== 'function', invalid('Invalid model token budget'));
 }
+/**
+ * Compute how many input tokens remain for one call.
+ *
+ * The requested output tokens and the safety margin are subtracted from the context
+ * window, so a call that reserves more than the window is rejected before counting.
+ *
+ * @param budget - Declared context window and safety margin.
+ * @param outputTokens - Tokens reserved for the completion.
+ * @returns The positive input token allowance.
+ * @throws ValidationError When the reservation is invalid or leaves no input capacity.
+ */
 function modelInputTokenLimit(budget, outputTokens) {
     const limit = budget.contextWindowTokens - outputTokens - (budget.safetyMarginTokens ?? 0);
     (0, rules_js_1.breakWhile)(!Number.isSafeInteger(outputTokens) || outputTokens < 1 || limit < 1, invalid('No input capacity after reserving output and safety margin'));
     return limit;
 }
+/**
+ * Count the tokens of a prepared request.
+ *
+ * The counter observes a request, so both messages and declarations are cloned before
+ * being handed over: accidental mutations by the counter must not rewrite the provider
+ * input. The returned count must itself be a nonnegative safe integer.
+ *
+ * @param budget - Budget supplying the counter.
+ * @param messages - Effective messages, including the merged instruction.
+ * @param options - Function declarations and JSON mode as they will be sent.
+ * @returns The token count reported by the host counter.
+ * @throws ValidationError When the counter returns an unusable number.
+ */
 function countModelInput(budget, messages, options) {
     // A counter observes a request; accidental mutations must not rewrite the provider input.
-    const snapshot = messages.map(message => ({ ...message,
-        ...(message.images ? { images: message.images.map(image => ({ ...image })) } : {}),
+    const snapshot = messages.map((message) => ({
+        ...message,
+        ...(message.images ? { images: message.images.map((image) => ({ ...image })) } : {}),
     }));
-    const count = budget.countTokens({ messages: snapshot,
-        functions: options.functions ? structuredClone(options.functions) : undefined, json: options.json });
+    const count = budget.countTokens({
+        messages: snapshot,
+        functions: options.functions ? structuredClone(options.functions) : undefined,
+        json: options.json,
+    });
     (0, rules_js_1.breakWhile)(!Number.isSafeInteger(count) || count < 0, invalid('Token counter must return a nonnegative integer'));
     return count;
 }
+/**
+ * Enforce the measured input against its token allowance.
+ *
+ * @param count - Measured input tokens.
+ * @param limit - Allowance from `modelInputTokenLimit`.
+ * @throws ValidationError When the input exceeds the allowance.
+ */
 function enforceModelInputTokens(count, limit) {
     (0, rules_js_1.breakWhile)(count > limit, invalid(`Model input uses ${count} tokens; available input budget is ${limit}`));
 }
-/** Reused by preflight measurement and the provider call so instructions are counted exactly once. */
+/**
+ * Merge a transport instruction into the message list.
+ *
+ * An existing system message keeps its position and receives the instruction as a new
+ * paragraph; otherwise a system message is prepended. Reusing the same function for
+ * preflight measurement and the provider call is what makes instructions count exactly
+ * once.
+ *
+ * @param base - Caller messages; not mutated.
+ * @param instruction - Optional instruction to merge.
+ * @returns A new message array.
+ */
 function modelInputMessages(base, instruction) {
     if (!instruction)
         return [...base];
-    const index = base.findIndex(message => message.role === 'system');
-    return index < 0 ? [{ role: 'system', content: instruction }, ...base]
-        : base.map((message, position) => position === index ? { ...message, content: `${message.content}\n\n${instruction}` } : message);
+    const index = base.findIndex((message) => message.role === 'system');
+    return index < 0
+        ? [{ role: 'system', content: instruction }, ...base]
+        : base.map((message, position) => position === index
+            ? { ...message, content: `${message.content}\n\n${instruction}` }
+            : message);
 }

package/dist/cjs/model/transports.js

@@ -2,23 +2,76 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPlainTextTransport = createPlainTextTransport;
 exports.normalizeModelTransport = normalizeModelTransport;
+/**
+ * Transport definitions and the built-in plain-text transport.
+ *
+ * A transport owns the wire-level request shape (options, declarations, instruction)
+ * and the collector that decodes streamed parts into one result. The runner never
+ * interprets provider output itself, so adding a protocol means adding a transport
+ * rather than branching in the core.
+ *
+ * Exports: `createPlainTextTransport` and `normalizeModelTransport`.
+ */
 const synchronous_js_1 = require("../utils/synchronous.js");
 const errors_js_1 = require("../structs/errors.js");
 const options_js_1 = require("./options.js");
+/**
+ * Collector that concatenates plain text into one decoded value.
+ *
+ * A non-string part means the provider emitted a native call event, which a plain-text
+ * stage cannot represent; that is reported as a protocol violation instead of being
+ * stringified.
+ *
+ * @param decode - Final conversion from accumulated raw text to the result.
+ * @returns A collector reporting the buffered character count.
+ */
 function textResponse(decode) {
     let raw = '';
-    return { get outputChars() { return raw.length; }, push(part) {
+    return {
+        get outputChars() {
+            return raw.length;
+        },
+        push(part) {
             if (typeof part !== 'string')
-                throw new errors_js_1.ValidationError([{ code: 'MODEL_PROTOCOL', message: 'Text transport does not accept model calls' }]);
+                throw new errors_js_1.ValidationError([
+                    { code: 'MODEL_PROTOCOL', message: 'Text transport does not accept model calls' },
+                ]);
             raw += part;
-        }, finish: () => (0, synchronous_js_1.synchronous)(decode(raw), 'Model result parsers must be synchronous') };
+        },
+        finish: () => (0, synchronous_js_1.synchronous)(decode(raw), 'Model result parsers must be synchronous'),
+    };
 }
-/** Shared Core mechanism, also used by the optional App-side text creator. */
+/**
+ * Build a transport that expects a single plain-text completion.
+ *
+ * JSON mode is forced off because a text stage has no envelope to parse, and the final
+ * text is trimmed so transport-specific whitespace never reaches the caller.
+ *
+ * @param id - Unique transport id, also used as the typed handle in `ModelRunner`.
+ * @param options - Optional request options; only `temperature` is honored.
+ * @returns A frozen transport definition.
+ */
 function createPlainTextTransport(id, options = {}) {
     const settings = Object.freeze({ ...(0, options_js_1.snapshotModelOptions)(options), json: false });
-    return Object.freeze({ id, prepare: (_stageId) => ({ options: settings, schemaChars: 0, createResponse: () => textResponse(raw => raw.trim()) }) });
+    return Object.freeze({
+        id,
+        prepare: (_stageId) => ({
+            options: settings,
+            schemaChars: 0,
+            createResponse: () => textResponse((raw) => raw.trim()),
+        }),
+    });
 }
-/** Pin the supplied implementation and preserve its receiver at registration. */
+/**
+ * Freeze a transport and pin its preparation receiver.
+ *
+ * Binding at registration means a later caller cannot swap the definition's identity
+ * or detach `prepare` from the object that specializes it.
+ *
+ * @param definition - Transport supplied by the App or by a factory.
+ * @returns A frozen definition with a bound `prepare`.
+ * @throws TypeError When the id is blank or `prepare` is missing.
+ */
 function normalizeModelTransport(definition) {
     if (!definition.id?.trim() || typeof definition.prepare !== 'function')
         throw new TypeError('Invalid model transport');

package/dist/cjs/structs/common.js

@@ -1,2 +1,13 @@
 "use strict";
+/**
+ * Package-wide vocabulary shared by every agent-core contract.
+ *
+ * These aliases and envelopes are the neutral layer between App-owned business types and the
+ * Core runtime modules: identifiers stay opaque, application identities are deliberately absent,
+ * and every catalog or result shape is read-only so a registered snapshot cannot be mutated later.
+ *
+ * Exports: `Id`, `TimestampMs`, `DurationMs`, `Observer`, `AsyncSink`, `InvocationStatus`,
+ * `JsonSchema`, `MaybePromise`, `SchemaAdapter`, `Issue`, `CheckResult`, `ReadonlyCatalog`,
+ * `Registry`, `ExecutionOptions`, `ExecutionContext`, `OperationContext`, `SearchHit`.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/structs/debug.js

@@ -1,12 +1,41 @@
 "use strict";
+/**
+ * Self-reported execution detail supplied by App nodes and tools.
+ *
+ * The data here is optional evidence of what an App chose to report, never proof that Core
+ * performed the work, and it is collected only through the diagnostic context that owns the
+ * current node visit. The status catalog below is the single source of truth for legal reported
+ * statuses, their terminal flag and the transitions that `fix` may apply.
+ *
+ * Exports: `reportedStepStatusCatalog`, `reportedStepStatuses`, `ReportedStepStatus`,
+ * `ReportedStep`, `SubFlowValue`, `RecordedSubStep`, `SubFlowStepInput`, `SubFlowStepFix`,
+ * `SubFlowLogger`, `NodeReportingContext`, `SubStepProgress`, `DebugStepsOutput`.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reportedStepStatuses = exports.reportedStepStatusCatalog = void 0;
-/** Optional node-reported debug material, never proof of internal execution. */
+/**
+ * Legal self-reported step statuses and their transitions.
+ *
+ * `terminal: true` means the step is finished and its status can no longer change; `next` lists the
+ * statuses a later `fix` may assign to a non-terminal step.
+ */
 exports.reportedStepStatusCatalog = {
-    unknown: { terminal: false, next: ['unknown', 'planned', 'running', 'success', 'error', 'cancelled', 'skipped'] },
-    planned: { terminal: false, next: ['planned', 'running', 'success', 'error', 'cancelled', 'skipped'] },
+    /** No status reported yet; only `fix` uses this as an intermediate state. */
+    unknown: {
+        terminal: false,
+        next: ['unknown', 'planned', 'running', 'success', 'error', 'cancelled', 'skipped'],
+    },
+    /** Declared by the node but not started. */
+    planned: {
+        terminal: false,
+        next: ['planned', 'running', 'success', 'error', 'cancelled', 'skipped'],
+    },
+    /** Started and still active; may only stay running or finish. */
     running: { terminal: false, next: ['running', 'success', 'error', 'cancelled'] },
-    success: { terminal: true, next: [] }, error: { terminal: true, next: [] },
-    cancelled: { terminal: true, next: [] }, skipped: { terminal: true, next: [] },
+    success: { terminal: true, next: [] },
+    error: { terminal: true, next: [] },
+    cancelled: { terminal: true, next: [] },
+    skipped: { terminal: true, next: [] },
 };
+/** Frozen list of reported statuses in catalog order, used for membership validation. */
 exports.reportedStepStatuses = Object.freeze(Object.keys(exports.reportedStepStatusCatalog));

package/dist/cjs/structs/errors.js

@@ -1,20 +1,45 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowContractError = exports.BudgetError = exports.ValidationError = void 0;
+/**
+ * Rejected input or output that failed one or more registered checks.
+ *
+ * The message is fixed; consumers should read `issues` for the actual reasons.
+ */
 class ValidationError extends Error {
     issues;
+    /**
+     * @param issues - Validation problems, stored verbatim and exposed to the catcher.
+     */
     constructor(issues) {
         super('Agent validation failed');
         this.issues = issues;
     }
 }
 exports.ValidationError = ValidationError;
+/**
+ * A configured allowance (rounds, model calls, attempts) is exhausted.
+ *
+ * The optional message states which allowance ran out; `code` is the stable marker.
+ */
 class BudgetError extends Error {
     code = 'BUDGET';
 }
 exports.BudgetError = BudgetError;
+/**
+ * The workflow definition violates Core's execution contract, as opposed to failing business logic.
+ *
+ * Examples: unknown model binding, asynchronous predicate, unmatched route, missing state field.
+ * It is a programming error, so callers should not treat it as retryable.
+ */
 class WorkflowContractError extends Error {
     code = 'WORKFLOW_CONTRACT';
-    constructor(message) { super(message); this.name = 'WorkflowContractError'; }
+    /**
+     * @param message - Human-readable contract violation; preserved by `Error`.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'WorkflowContractError';
+    }
 }
 exports.WorkflowContractError = WorkflowContractError;

package/dist/cjs/structs/index.js

@@ -14,7 +14,17 @@ 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 });
-/** Shared structures and contracts. Runtime classes here only declare shape or initialize fields. */
+/**
+ * Public entry of the structs layer.
+ *
+ * Structs are the shape-only half of agent-core: declarations and frozen constant catalogs that the
+ * runtime modules (`capabilities`, `context`, `execution`, `model`, `kits`, `support`) both
+ * implement and consume. Runtime classes declared here only describe shape or initialize fields,
+ * so importing this barrel never starts execution.
+ *
+ * Exports: a curated re-export of the shared vocabulary, error classes, diagnostics/event
+ * envelopes, model and workflow contracts, and the optional Kit protocol definitions.
+ */
 __exportStar(require("./capabilities/model.js"), exports);
 __exportStar(require("./model/chat-provider.js"), exports);
 __exportStar(require("./context/fragments.js"), exports);

package/dist/cjs/structs/kits/durable.js

@@ -1,5 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.durableReplayPolicies = exports.durableStatuses = void 0;
+/** Checkpoint lifecycle values, in the order a task passes through them. */
 exports.durableStatuses = ['ready', 'running', 'completed', 'cancelled'];
+/**
+ * How an interrupted step is resumed.
+ *
+ * `safe` re-runs `run` (the step must tolerate repeating its side effect); `reconcile` requires a
+ * `reconcile` handler because the previous attempt may have taken effect already.
+ */
 exports.durableReplayPolicies = ['safe', 'reconcile'];

package/dist/cjs/structs/kits/family.js

@@ -1,4 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.familyOperations = void 0;
+/** Operation names accepted by the family `authorize` hook. */
 exports.familyOperations = ['create', 'fork', 'merge', 'promote'];

package/dist/cjs/structs/kits/interaction.js

@@ -1,4 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INTERACTION_CATEGORIES = void 0;
-exports.INTERACTION_CATEGORIES = Object.freeze(['query', 'action', 'presentation', 'input', 'receipt']);
+/** Frozen list of accepted categories, used for validation and enumeration. */
+exports.INTERACTION_CATEGORIES = Object.freeze([
+    'query',
+    'action',
+    'presentation',
+    'input',
+    'receipt',
+]);

package/dist/cjs/structs/kits/knowledge-publication.js

@@ -1,4 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.knowledgePublicationOperations = void 0;
+/** Operation names accepted by the publication `authorize` hook. */
 exports.knowledgePublicationOperations = ['propose', 'publish', 'reject'];

package/dist/cjs/structs/kits/reflection.js

@@ -1,7 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reflectionFindingKinds = exports.reflectionIdentityFields = void 0;
-exports.reflectionIdentityFields = Object.freeze(['spanId', 'parentSpanId', 'invocationId', 'parentInvocationId',
-    'agentId', 'branchId', 'agentVersionId', 'parentBranchId', 'parentAgentVersionId', 'forkPointId',
-    'workflowInvocationId', 'workflowNodeId', 'nodeRole', 'definitionId']);
+/** Identity fields an evidence item may project from the original diagnostic identity. */
+exports.reflectionIdentityFields = Object.freeze([
+    'spanId',
+    'parentSpanId',
+    'invocationId',
+    'parentInvocationId',
+    'agentId',
+    'branchId',
+    'agentVersionId',
+    'parentBranchId',
+    'parentAgentVersionId',
+    'forkPointId',
+    'workflowInvocationId',
+    'workflowNodeId',
+    'nodeRole',
+    'definitionId',
+]);
+/** Allowed finding kinds, from observed facts to advisory conclusions. */
 exports.reflectionFindingKinds = ['observed', 'hypothesis', 'recommendation'];

package/dist/cjs/structs/model/chat-provider.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatProvider = void 0;
+/**
+ * Streaming model provider.
+ *
+ * Implementations must stop producing when `context.signal` aborts and should surface transport
+ * failures by rejecting the iteration rather than ending it silently.
+ */
 class ChatProvider {
 }
 exports.ChatProvider = ChatProvider;

package/dist/cjs/structs/support/model/completion.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/structs/support/model/messages.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });