@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/structs/diagnostics.d.ts

@@ -1,64 +1,104 @@
+/**
+ * Diagnostic envelope, event catalog and recording context for agent-core.
+ *
+ * One execution fact is produced once; it may be observed live and, when enabled, projected into a
+ * log sink. This module declares the names, payload shapes, identity fields and content classes
+ * that both paths share, so a consumer never needs a parallel event description.
+ *
+ * Exports: `CoreEventPayloads`, `CoreEventName`, `CoreEventDescriptor`, `DiagnosticIdentity`,
+ * `DiagnosticSpanFields`, `CoreEvent`, `CoreLogOutput`, `DiagnosticContext`,
+ * `CreateDiagnosticsOptions`, `CoreDiagnosticRecord`.
+ */
 import type { DebugStepsOutput, RecordedSubStep } from './debug.js';
 import type { WorkflowEvent } from './execution/workflow.js';
 import type { ModelCallTrace } from './model/runtime.js';
 import type { ModelMessage } from './model/messages.js';
+/** Payload of every Core event, keyed by event name. Fields are the event's own facts only. */
 export interface CoreEventPayloads {
+    /** One loop round transition raised by the engine. */
     'loop.event': import('./execution/engine.js').LoopEvent;
+    /** Model binding selection and its per-phase timing; recorded around one model invocation. */
     'model.binding': {
+        /** Configured model binding id. */
         modelId: string;
+        /** Invocation the binding served. */
         invocationId: string;
+        /** Phase outcome: `running` while active, otherwise terminal. */
         status: 'running' | 'success' | 'error' | 'cancelled';
+        /** Lifecycle phase this fact belongs to. */
         phase: 'input' | 'invoke' | 'output';
+        /** Elapsed milliseconds for the phase; absent while running. */
         durationMs?: number;
+        /** Error classification when the phase failed. */
         errorCode?: string;
     };
+    /** Snapshot of the prepared request, emitted before the provider is called. */
     'model.prepare': {
         stageId: string;
+        /** Transport selected for the call. */
         transportId: string;
+        /** Messages actually sent, after context assembly and budget checks. */
         messages: readonly ModelMessage[];
+        /** Transport-specific request options; opaque to Core consumers. */
         options: unknown;
+        /** Context measurement or projection attached by the caller. */
         context?: unknown;
     };
+    /** One streamed model part, in arrival order. */
     'model.output': {
         stageId: string;
+        /** Position of the call within its runner. */
         callSequence: number;
+        /** Zero-based index of the part within the response. */
         partIndex: number;
         part: import('./model/messages.js').ModelPart;
     };
+    /** Parsed output of a response, once the collector resolved it. */
     'model.parsed': {
         stageId: string;
         callSequence: number;
         value?: unknown;
     };
+    /** End of a model call, successful or not, with its accumulated trace. */
     'model.end': {
         stageId: string;
         state: Readonly<ModelCallTrace>;
+        /** Failure that ended the call; absent on success. */
         error?: unknown;
+        /** Number of parts actually received, for truncated-stream detection. */
         receivedParts: number;
     };
+    /** A Core input or state condition rejected execution. */
     'runtime.rejected': {
         stageId?: string;
         error: unknown;
     };
+    /** Progress reported by an active workflow node. */
     'node.progress': {
         payload?: unknown;
+        /** Sub-step delivery fact; separate from the node's own payload. */
         subStep?: import('./debug.js').SubStepProgress;
+        /** Set when the node's report violated the reporting contract. */
         reportError?: 'INVALID_NODE_REPORT';
     };
+    /** Start of one model call, emitted before any output part. */
     'model.start': {
         stageId: string;
         callSequence: number;
         transportId: string;
     };
+    /** Workflow lifecycle fact raised by the engine. */
     'workflow.event': {
         event: WorkflowEvent;
         payload?: unknown;
     };
+    /** A tool call was accepted for execution. */
     'tool.call': {
         toolId: string;
         invocationId: string;
         input?: unknown;
     };
+    /** A tool call settled, successfully or not. */
     'tool.result': {
         toolId: string;
         invocationId: string;
@@ -66,88 +106,166 @@ export interface CoreEventPayloads {
         error?: unknown;
         errorCode?: string;
         status: import('./common.js').InvocationStatus;
+        /** Elapsed milliseconds for the tool execution. */
         durationMs: number;
     };
+    /** A declarative rule rejected processing, with its ownership tags. */
     'rule.result': {
         tags: readonly string[];
         error: unknown;
     };
 }
+/** Union of every Core event name; the key set of `CoreEventPayloads`. */
 export type CoreEventName = keyof CoreEventPayloads;
+/**
+ * Event classification used when deciding whether a sink accepts an event.
+ *
+ * `metadata` events carry identity, timing and status only; `content` events may carry user,
+ * model or tool content and therefore require an explicit acceptance decision.
+ */
 export interface CoreEventDescriptor {
     event: CoreEventName;
     content: 'metadata' | 'content';
 }
 /** Execution identity only: never message, account or HTTP identity. */
 export interface DiagnosticIdentity {
+    /** Root run id shared by every fact of one logical run. */
     readonly runId: string;
+    /** Span that produced the fact. */
     readonly spanId: string;
+    /** Enclosing span; absent for a root span. */
     readonly parentSpanId?: string;
+    /** Invocation that produced the fact, when the fact belongs to one. */
     readonly invocationId?: string;
+    /** Enclosing invocation, when one invocation triggers another. */
     readonly parentInvocationId?: string;
+    /** Role the emitting span plays in the execution graph. */
     readonly nodeRole?: 'workflow-node' | 'workflow-boundary' | 'invocation' | 'loop-step';
+    /** App-owned agent identity. */
     readonly agentId?: string;
+    /** App-owned branch identity. */
     readonly branchId?: string;
+    /** App-owned immutable version identity of the agent definition. */
     readonly agentVersionId?: string;
+    /** Branch this branch was forked from, when applicable. */
     readonly parentBranchId?: string;
+    /** Version of the parent branch at the fork point. */
     readonly parentAgentVersionId?: string;
+    /** App-owned fork marker shared by the forked branch and its origin. */
     readonly forkPointId?: string;
+    /** Workflow invocation the fact belongs to. */
     readonly workflowInvocationId?: string;
+    /** Workflow node invocation the fact belongs to. */
     readonly workflowNodeId?: string;
+    /** Kind of the workflow/agent definition that dispatched the node. */
     readonly definitionKind?: string;
+    /** Id of that definition. */
     readonly definitionId?: string;
+    /** Revision of that definition; distinguishes executions of different definition states. */
     readonly definitionRevision?: string;
+    /** Node id inside the workflow. */
     readonly nodeId?: string;
+    /** Human-readable node name. */
     readonly nodeName?: string;
+    /** Node kind as declared by the App. */
     readonly nodeKind?: string;
+    /** Optional node description for diagnostics display. */
     readonly nodeDescription?: string;
+    /** Model stage that produced the fact. */
     readonly stageId?: string;
+    /** Model binding used, when the fact concerns a model call. */
     readonly modelId?: string;
 }
+/** Identity fields a child span may override; the parent supplies run, span and parent span. */
 export type DiagnosticSpanFields = Omit<DiagnosticIdentity, 'runId' | 'spanId' | 'parentSpanId'>;
+/**
+ * A recorded Core fact.
+ *
+ * Every variant carries the same envelope: a version marker, unique event id, producing span's
+ * identity, a per-producer monotonic sequence, the occurrence instant and optional reported
+ * sub-steps. `subStepsDropped`/`subStepsTruncated` state that reported detail was bounded.
+ */
 export type CoreEvent = {
     [K in CoreEventName]: DiagnosticIdentity & {
+        /** Envelope version; consumers must reject anything else. */
         version: 2;
+        /** Unique id of this fact, stable across observers and log writers. */
         eventId: string;
+        /** Discriminator matching `payload`. */
         type: K;
+        /** Monotonic counter owned by the producing scope; starts at 1 for each producer. */
         producerSequence: number;
+        /** Instant the fact occurred, in epoch milliseconds. */
         occurredAtMs: number;
+        /** Event-specific facts. */
         payload: CoreEventPayloads[K];
+        /** Whether the reported step used a model; omitted when the producer did not state it. */
         usedModel?: boolean;
+        /** Reported sub-steps attached to this fact, bounded and already validated. */
         subSteps: readonly RecordedSubStep[];
+        /** Number of reported sub-steps omitted by the recorder's bounds. */
         subStepsDropped: number;
+        /** True when reported sub-steps were truncated, so the attached list is incomplete. */
         subStepsTruncated: boolean;
     };
 }[CoreEventName];
+/** Destination for recorded facts; implementations decide filtering and durability. */
 export interface CoreLogOutput {
+    /** Returns false to skip an event entirely; absent means accept every event. */
     accepts?(descriptor: CoreEventDescriptor): boolean;
+    /** Persists one fact. Rejections propagate to the emitting call. */
     write(event: CoreEvent): void | Promise<void>;
 }
+/**
+ * Recording scope bound to one execution identity.
+ *
+ * A child scope inherits the sink and observer of its parent; only identity changes.
+ */
 export interface DiagnosticContext {
+    /** Identity of the current scope, when the scope is bound to an execution. */
     readonly identity?: Readonly<DiagnosticIdentity>;
+    /** Cheap pre-check so callers can skip building expensive payloads. */
     enabled(event: CoreEventName, content?: 'metadata' | 'content'): boolean;
+    /**
+     * Records one fact.
+     *
+     * @param event - Event name; determines the payload type.
+     * @param payload - Thunk invoked only when the event is enabled.
+     * @param debug - Optional reported debug material attached to the fact.
+     */
     emit<K extends CoreEventName>(event: K, payload: () => CoreEventPayloads[K], debug?: DebugStepsOutput): void;
     /** Ordered content delivery uses the same fact, while consumer failures propagate. */
     deliver<K extends CoreEventName>(event: K, payload: () => CoreEventPayloads[K], sink: (event: Extract<CoreEvent, {
         type: K;
     }>) => void | Promise<void>): Promise<void>;
+    /** Derives a child span; `fields` fills values the child knows but the parent does not. */
     child(spanId: string, fields?: Readonly<DiagnosticSpanFields>): DiagnosticContext;
     /** Bind live observation without changing the log destination or request identity. */
     withObserver(observer: import('./execution/events.js').ExecutionObserver): DiagnosticContext;
 }
+/** Options for creating a root diagnostic scope. */
 export interface CreateDiagnosticsOptions {
+    /** Log destination; omission disables persistence while observation can still work. */
     readonly output?: CoreLogOutput;
+    /** Live observer of the same facts, independent of `output`. */
     readonly observe?: import('./execution/events.js').ExecutionObserver;
+    /** Root run id; generated when omitted. */
     readonly runId?: string;
+    /** Root span id; generated when omitted. */
     readonly spanId?: string;
 }
-/** Persisted data is untrusted: normalization checks the current envelope, not arbitrary payloads. */
+/**
+ * Persisted data is untrusted: normalization checks the current envelope, not arbitrary payloads.
+ */
 export interface CoreDiagnosticRecord extends DiagnosticIdentity {
+    /** Envelope version this record was written with. */
     readonly version: 2;
     readonly eventId: string;
     readonly type: CoreEventName;
+    /** Per-producer monotonic sequence; at least 1. */
     readonly producerSequence: number;
     readonly occurredAtMs: number;
+    /** Unvalidated payload; only the envelope above is checked during normalization. */
     readonly payload: unknown;
     readonly usedModel?: boolean;
     readonly subSteps: readonly RecordedSubStep[];

package/dist/esm/structs/errors.d.ts

@@ -1,27 +1,68 @@
+/**
+ * Error types and error-metadata contracts used by agent-core.
+ *
+ * Errors remain plain `Error` subclasses so hosts can catch them without importing a hierarchy;
+ * stage and retryability metadata is attached beside the value (see `src/errors.ts`) instead of
+ * replacing the original thrown value or its identity.
+ *
+ * Exports: `ValidationError`, `BudgetError`, `WorkflowContractError`, `AgentErrorInfo`,
+ * `ErrorContext`.
+ */
 import type { Issue } from './common.js';
+/**
+ * Rejected input or output that failed one or more registered checks.
+ *
+ * The message is fixed; consumers should read `issues` for the actual reasons.
+ */
 export declare class ValidationError extends Error {
     readonly issues: readonly Issue[];
+    /**
+     * @param issues - Validation problems, stored verbatim and exposed to the catcher.
+     */
     constructor(issues: readonly Issue[]);
 }
+/**
+ * A configured allowance (rounds, model calls, attempts) is exhausted.
+ *
+ * The optional message states which allowance ran out; `code` is the stable marker.
+ */
 export declare class BudgetError extends Error {
     readonly code = "BUDGET";
 }
+/**
+ * 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.
+ */
 export declare class WorkflowContractError extends Error {
     readonly code = "WORKFLOW_CONTRACT";
+    /**
+     * @param message - Human-readable contract violation; preserved by `Error`.
+     */
     constructor(message: string);
 }
-/** Stable metadata for App diagnostics. Unknown retryability is deliberately omitted. */
+/** Stable error metadata for App diagnostics. Unknown retryability is deliberately omitted. */
 export interface AgentErrorInfo {
+    /** Primary code: the error's own `code`, or a derived/fallback classification. */
     readonly code: string;
+    /** Every code observed while inspecting the error and its causes, primary code first. */
     readonly codes: readonly string[];
+    /** Structured issues found on the error; empty when the source reported none. */
     readonly issues: readonly Readonly<Issue>[];
+    /** Execution stage that recorded the error, when the boundary annotated it. */
     readonly stageId?: string;
+    /** Present only when the source stated retryability; absence means unknown. */
     readonly isRetryable?: boolean;
+    /** Original thrown value, kept for identity and host-specific handling. */
     readonly cause: unknown;
 }
 /** Boundary metadata is recorded internally, without replacing the original thrown value. */
 export interface ErrorContext {
+    /** Stage that first observed the error; later annotations keep the earliest value. */
     readonly stageId?: string;
+    /** Codes contributed by the boundary, merged with those found on the error itself. */
     readonly codes?: readonly string[];
+    /** Retryability asserted by the boundary; omitted when it cannot be determined. */
     readonly isRetryable?: boolean;
 }

package/dist/esm/structs/errors.js

@@ -1,14 +1,39 @@
+/**
+ * Rejected input or output that failed one or more registered checks.
+ *
+ * The message is fixed; consumers should read `issues` for the actual reasons.
+ */
 export 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;
     }
 }
+/**
+ * A configured allowance (rounds, model calls, attempts) is exhausted.
+ *
+ * The optional message states which allowance ran out; `code` is the stable marker.
+ */
 export class BudgetError extends Error {
     code = 'BUDGET';
 }
+/**
+ * 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.
+ */
 export 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';
+    }
 }

package/dist/esm/structs/execution/engine.d.ts

@@ -1,21 +1,44 @@
+/**
+ * Agent loop contract: one bounded step executed repeatedly until it completes.
+ *
+ * The engine owns round counting, cancellation and budget exhaustion; the App supplies a `CoreStep`
+ * that decides whether the loop continues or finishes. Loop facts are emitted as `loop.event` so
+ * a host can observe progress without reading engine internals.
+ *
+ * Exports: `LoopEvent`, `StepOutcome`, `CoreStep`, `AgentCoreEngineOptions`.
+ */
 import type { ExecutionContext, ExecutionOptions, MaybePromise } from '../common.js';
+/** Progress fact for one loop round, correlated with the enclosing diagnostics span. */
 export interface LoopEvent {
+    /** Unique id of this fact. */
     readonly eventId: string;
+    /** `enter` opens a round, `continue`/`complete` close it, `error` reports failure. */
     readonly type: 'enter' | 'continue' | 'complete' | 'error';
+    /** Zero-based round index; a new round starts only when the step asks to continue. */
     readonly roundIndex: number;
+    /** Phase that failed on `error`: boundary checks, the step itself, or budget accounting. */
     readonly phase?: 'boundary' | 'run' | 'budget';
+    /** Stable error classification when `type` is `error`. */
     readonly errorCode?: string;
 }
-export type StepOutcome<Value> = {
+/** Decision a step returns to the engine. */
+export type StepOutcome<Value> = 
+/** Run another round; consumes one round from the budget. */
+{
     readonly type: 'continue';
 } | {
     readonly type: 'complete';
     readonly value: Value;
 };
+/** One loop iteration. Must be re-entrant: the same step object runs every round. */
 export type CoreStep<Result> = (roundIndex: number, context: ExecutionContext & import('../debug.js').NodeReportingContext) => MaybePromise<StepOutcome<Result>>;
+/** Engine construction options. */
 export interface AgentCoreEngineOptions {
+    /** Round budget; must be a positive safe integer. Defaults to 8 rounds. */
     maxRounds?: number;
+    /** Cancellation and diagnostics shared by every round. */
     execution?: ExecutionOptions;
+    /** Builds the error thrown when the round budget is exhausted (defaults to a `BudgetError`). */
     errors?: {
         exhausted?: () => Error;
     };

package/dist/esm/structs/execution/events.d.ts

@@ -1,10 +1,22 @@
+/**
+ * Live execution observation contract.
+ *
+ * The same fact that diagnostics may persist can also be observed while it happens. Observers
+ * receive metadata by default; content-bearing events require an explicit `accepts` decision so a
+ * host cannot leak user or model content by accident.
+ *
+ * Exports: `CoreEvent` (type re-export), `ExecutionEventDescriptor`, `ExecutionObserver`.
+ */
 import type { CoreEvent, CoreEventDescriptor, DiagnosticIdentity } from '../diagnostics.js';
 /** The same execution fact is observed live and optionally projected into a log. */
 export type { CoreEvent } from '../diagnostics.js';
+/** Event name, content class and the producing execution identity. */
 export interface ExecutionEventDescriptor extends CoreEventDescriptor, DiagnosticIdentity {
 }
+/** Live consumer of Core facts. */
 export interface ExecutionObserver {
     /** Metadata-only by default. Content requires an explicit accepts decision. */
     accepts?(descriptor: Readonly<ExecutionEventDescriptor>): boolean;
+    /** Handles one fact; a rejected promise propagates to the emitting call. */
     event(event: Readonly<CoreEvent>): void | Promise<void>;
 }

package/dist/esm/structs/execution/workflow.d.ts

@@ -1,29 +1,56 @@
+/**
+ * Workflow contract: a state graph whose nodes report their own use of model and tools.
+ *
+ * A definition declares nodes, ordered routes and an optional result predicate. The engine walks
+ * the graph, validates `requires`/`provides`, applies route order and records one `WorkflowEvent`
+ * per decision. All declarations here are metadata; execution stays in the engine so Core remains
+ * the only place that owns round budgets, cancellation and state commits.
+ *
+ * Exports: `WorkflowContext`, `WorkflowRoute`, `WorkflowNodeReport`, `WorkflowNode`,
+ * `AgentWorkflowDefinition`, `WorkflowEvent`, `WorkflowFailure`, `WorkflowExtension`,
+ * `WorkflowModel`.
+ */
 import type { OperationContext } from '../common.js';
 import type { DiagnosticContext } from '../diagnostics.js';
 import type { ModelTransportDefinition } from '../model/runtime.js';
 import type { NodeReportingContext } from '../debug.js';
+/** Model request for a workflow: diagnostics arrive through the node context, never per call. */
 type WorkflowModelRequest<Transport> = import('../model/runtime.js').ModelCallRequest<Transport> & {
     readonly diagnostics?: never;
     readonly modelId?: string;
 };
+/** Execution facts available to every node of a running workflow. */
 export interface WorkflowContext<Runtime = undefined> extends OperationContext<Runtime>, NodeReportingContext {
     /** Zero-based bounded round; phases within a round do not consume another round. */
     readonly roundIndex: number;
     /** Report progress while this node is active; Core supplies its execution identity. */
     report(update: WorkflowNodeReport): void;
+    /** Diagnostic scope of this node visit, when recording is enabled. */
     readonly diagnostics?: DiagnosticContext;
+    /** Model access limited by the workflow's configured calls and budget. */
     readonly model: WorkflowModel;
     readonly tools: {
         /** Per-call cancellation can shorten, never replace, the Workflow lifetime. */
         invoke(request: Omit<import('../capabilities/tools.js').ToolInvocationRequest, 'diagnostics'>): Promise<import('../invocation.js').ToolResult<unknown>>;
     };
+    /** Failure that led into this node, present only while entering an `onErrorNodeId` target. */
     readonly error?: unknown;
+    /** Event id of that failure, for correlation in host logs. */
     readonly errorEventId?: string;
 }
+/**
+ * One route out of a node.
+ *
+ * Routes are evaluated in array order and the first match wins. A route either continues at
+ * `targetNodeId` or completes the workflow through `complete`; declaring both is invalid.
+ */
 export type WorkflowRoute<State, Result, Runtime = undefined> = {
+    /** Stable route id reported in events; required only when hosts need to audit the choice. */
     readonly id?: string;
     readonly description?: string;
+    /** Stable condition id reported when this route was selected. */
     readonly conditionId?: string;
+    /** Omission means unconditional selection at this position; otherwise must return boolean now. */
     readonly when?: (state: Readonly<State>, context: WorkflowContext<Runtime>) => boolean;
 } & ({
     readonly targetNodeId: string;
@@ -32,37 +59,61 @@ export type WorkflowRoute<State, Result, Runtime = undefined> = {
     readonly targetNodeId?: never;
     readonly complete: (state: Readonly<State>, context: WorkflowContext<Runtime>) => Result;
 });
+/** Detail an App node reports about its current visit. */
 export interface WorkflowNodeReport {
     /** This visit's own use only; omitted means unknown. */
     readonly usedModel?: boolean;
+    /** App-defined progress detail; collected only when content logging is enabled. */
     readonly payload?: unknown;
+    /** Logger owned by this visit, used to report sub-steps. */
     readonly subs?: import('../debug.js').SubFlowLogger;
 }
+/** One node of the graph. */
 export type WorkflowNode<State, Result, Runtime = undefined> = {
+    /** Stable node id referenced by routes and error handling. */
     readonly id: string;
+    /** Required explanation of what the node does; also used in diagnostics. */
     readonly description: string;
+    /** Display name; defaults to `id` when omitted. */
     readonly name?: string;
     /** Optional application-reported detail, collected only when content logging is enabled. */
     readonly report?: (update: Readonly<Partial<State>> | void, context: NodeReportingContext) => WorkflowNodeReport;
+    /**
+     * Reserves a fresh round on entry.
+     *
+     * Use it for steps that may legitimately repeat; entering such a node when the round budget is
+     * exhausted fails with the configured exhausted error.
+     */
     readonly startsRound?: boolean;
+    /** Node entered when `run`/`provides`/`route` fails; contract errors always propagate instead. */
     readonly onErrorNodeId?: string;
+    /** Route id reported with the recovery transition. */
     readonly onErrorRouteId?: string;
+    /** State keys that must be present before this node runs; enforced by the engine. */
     readonly requires?: readonly (keyof State & string)[];
+    /** State keys this node is expected to produce; validated after `run`. */
     readonly provides?: readonly (keyof State & string)[];
+    /** Candidate successors, evaluated in order. */
     readonly routes: readonly WorkflowRoute<State, Result, Runtime>[];
     /** Return only changed fields. Core commits them after cancellation and output checks. */
     readonly run?: (state: Readonly<State>, context: WorkflowContext<Runtime>) => void | Partial<State> | Promise<void | Partial<State>>;
 };
+/** The graph an engine executes. */
 export type AgentWorkflowDefinition<State, Result, Runtime = undefined> = {
+    /** Stable workflow id, also reported in every event. */
     readonly id: string;
+    /** Definition revision; lets hosts distinguish executions of different graph versions. */
     readonly revision?: string;
     readonly nodes: readonly WorkflowNode<State, Result, Runtime>[];
+    /** Synchronous result adjudicator; returning anything other than `true` is a contract error. */
     readonly isResult?: (result: Result) => boolean;
+    /** First node to enter; defaults to the first declared node, which must start a round. */
     readonly entryNodeId?: string;
 };
 /** Metadata only: never includes state, prompt, parameters, results or raw errors. */
 export interface WorkflowEvent {
     readonly eventId: string;
+    /** Id of the failure that caused this transition, when recovering from an error. */
     readonly errorEventId?: string;
     readonly workflowId: string;
     readonly agentId?: string;
@@ -78,15 +129,22 @@ export interface WorkflowEvent {
     readonly roundIndex: number;
     readonly targetNodeId?: string;
     readonly type: 'enter' | 'transition' | 'complete' | 'error';
+    /** Elapsed milliseconds for the phase the event reports. */
     readonly durationMs?: number;
+    /** Zero-based index of the selected route in `node.routes`. */
     readonly route?: number;
+    /** Id of the selected route, when it declared one. */
     readonly routeId?: string;
+    /** Id of the selected condition, when the route declared one. */
     readonly conditionId?: string;
+    /** Logical phase that produced the event. */
     readonly phase?: 'boundary' | 'requires' | 'run' | 'provides' | 'route' | 'complete' | 'result';
+    /** Route that failed on `route`, `complete` or `result` phases. */
     readonly failedRouteId?: string;
     readonly runId?: string;
     readonly spanId?: string;
     readonly parentSpanId?: string;
+    /** Error classification for `error` events. */
     readonly errorCode?: string;
 }
 /** Error retained only while entering a registered failure phase. */
@@ -94,11 +152,21 @@ export interface WorkflowFailure {
     error: unknown;
     errorEventId?: string;
 }
+/** Additional nodes and routes merged into an existing definition. */
 export interface WorkflowExtension<State, Result, App> {
+    /** Nodes appended to the definition; ids must not collide with existing nodes. */
     readonly nodes: readonly WorkflowNode<State, Result, App>[];
+    /** Replacement route lists keyed by node id; other nodes keep their declared routes. */
     readonly routes?: Readonly<Record<string, readonly WorkflowRoute<State, Result, App>[]>>;
+    /** Extension revision, recorded so mixed definitions remain auditable. */
     readonly revision?: string;
 }
+/**
+ * Model and tool access for one workflow invocation.
+ *
+ * Every call is charged to the workflow's shared budget. Overloads select the transport: a prepared
+ * call, the default plain-text transport, or one registered transport with its typed result.
+ */
 export interface WorkflowModel {
     invoke<Result>(request: WorkflowModelRequest<never> & {
         readonly prepared: import('../model/runtime.js').PreparedModelCall<Result>;
@@ -118,8 +186,11 @@ export interface WorkflowModel {
     prepare(request: import('../model/runtime.js').ModelPrepareRequest<string | ModelTransportDefinition> & {
         readonly modelId?: string;
     }): import('../model/runtime.js').PreparedModelCall;
+    /** Calls still available to this workflow after ancestor reservations. */
     readonly remainingCalls: number;
+    /** Calls completed by this workflow's own runner. */
     readonly callCount: number;
+    /** Calls consumed across this workflow and its descendants. */
     readonly totalCallCount: number;
 }
 export {};

package/dist/esm/structs/index.d.ts

@@ -1,4 +1,14 @@
-/** 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.
+ */
 export * from './capabilities/model.js';
 export * from './model/chat-provider.js';
 export * from './context/fragments.js';

package/dist/esm/structs/index.js

@@ -1,4 +1,14 @@
-/** 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.
+ */
 export * from './capabilities/model.js';
 export * from './model/chat-provider.js';
 export * from './context/fragments.js';