@jangts/agent-core 0.1.1 → 0.2.0

package/dist/esm/execution/branch.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Branch identity snapshot.
+ *
+ * A branch records which agent version a run belongs to and, for forked runs, where it
+ * branched from. Snapshots are validated once so every later comparison is a plain
+ * value comparison rather than a re-validation.
+ *
+ * Exports: `snapshotBranch`.
+ */
 import type { AgentBranch } from './engine.js';
-/** Core identity contract, also used by App-side Family storage adapters. */
+/**
+ * Validate and freeze a branch identity.
+ *
+ * Required ids identify the branch itself; optional ids describe the fork origin. Ids are
+ * bounded in length so they remain usable as keys in App storage.
+ *
+ * @param source - Branch identity supplied by the host or generated by the engine.
+ * @returns A frozen identity with the same field set.
+ * @throws Error When a required id is missing or any id is blank or too long.
+ */
 export declare function snapshotBranch(source: AgentBranch): AgentBranch;

package/dist/esm/execution/branch.js

@@ -1,10 +1,26 @@
 import { breakWhile } from '../utils/rules.js';
-/** Core identity contract, also used by App-side Family storage adapters. */
+/**
+ * Validate and freeze a branch identity.
+ *
+ * Required ids identify the branch itself; optional ids describe the fork origin. Ids are
+ * bounded in length so they remain usable as keys in App storage.
+ *
+ * @param source - Branch identity supplied by the host or generated by the engine.
+ * @returns A frozen identity with the same field set.
+ * @throws Error When a required id is missing or any id is blank or too long.
+ */
 export function snapshotBranch(source) {
     breakWhile(!source, 'Invalid branch identity');
     const { agentId, branchId, agentVersionId, parentBranchId, parentAgentVersionId, forkPointId } = source;
     const valid = (id) => typeof id === 'string' && !!id.trim() && id.length <= 200;
-    breakWhile(![agentId, branchId, agentVersionId].every(valid)
-        || [parentBranchId, parentAgentVersionId, forkPointId].some(id => id !== undefined && !valid(id)), 'Invalid branch identity');
-    return Object.freeze({ agentId, branchId, agentVersionId, parentBranchId, parentAgentVersionId, forkPointId });
+    breakWhile(![agentId, branchId, agentVersionId].every(valid) ||
+        [parentBranchId, parentAgentVersionId, forkPointId].some((id) => id !== undefined && !valid(id)), 'Invalid branch identity');
+    return Object.freeze({
+        agentId,
+        branchId,
+        agentVersionId,
+        parentBranchId,
+        parentAgentVersionId,
+        forkPointId,
+    });
 }

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

@@ -9,11 +9,25 @@ type InvokeTool = (request: import('../structs/capabilities/tools.js').ToolInvoc
 type ToolBinding = {
     invoke: InvokeTool;
 } | Pick<ToolRegistry, 'invokeAsync'>;
+/** The subset of a runner an engine may drive; kept small so the App can supply it. */
 export type AgentModelRuntime = Pick<ModelRunner, 'invoke' | 'prepare' | 'execution' | 'remainingCalls' | 'callCount' | 'totalCallCount'>;
+/**
+ * Model binding accepted by the engine.
+ *
+ * Execution scope belongs to the engine, so a bound model may not carry its own signal or
+ * execution options.
+ */
 export type AgentModelBinding = ModelRunnerOptions & {
     execution?: never;
     signal?: never;
 };
+/**
+ * Engine construction options.
+ *
+ * Combines round budget and error factories with exactly one model shape (a single bound
+ * model or a named catalog), an optional tool runtime, an optional branch identity, and
+ * an optional workflow together with its App dependencies.
+ */
 export type AgentCoreEngineSetup<State, Result, App = undefined> = AgentCoreEngineOptions & {
     readonly branch?: AgentBranch;
     readonly tools?: ToolBinding;
@@ -34,29 +48,66 @@ export type AgentCoreEngineSetup<State, Result, App = undefined> = AgentCoreEngi
 } : {
     readonly app: App;
 })));
+/**
+ * Immutable identity of one branch of an agent.
+ *
+ * The three required ids are generated per engine unless the host restores a branch; the
+ * optional ids are only present on a fork and record the exact origin, so a forked run
+ * can be attributed without consulting external storage.
+ */
 export interface AgentBranch {
+    /** Agent the branch belongs to. */
     readonly agentId: string;
+    /** Branch identifier, unique within the agent. */
     readonly branchId: string;
+    /** Agent version the branch was created from. */
     readonly agentVersionId: string;
+    /** Parent branch id; present only for a fork. */
     readonly parentBranchId?: string;
+    /** Agent version of the parent branch; present only for a fork. */
     readonly parentAgentVersionId?: string;
+    /** Checkpoint the branch was forked at; present only for a fork. */
     readonly forkPointId?: string;
 }
+/**
+ * In-memory checkpoint with a copy-on-read accessor.
+ *
+ * The stored data is already a clone, and `read` clones again, so a caller cannot mutate
+ * the checkpoint by mutating what it read.
+ */
 export interface AgentCheckpoint<Data> {
+    /** Checkpoint identifier, unique within the engine. */
     readonly id: string;
+    /** Branch the checkpoint was taken on. */
     readonly source: AgentBranch;
+    /** @returns A fresh clone of the checkpoint data. */
     read(): Data;
 }
-/** Host-owned serializable data, never a saved credential, model budget or executable handler. */
+/**
+ * Host-owned serializable data, never a saved credential, model budget or executable handler.
+ */
 export interface AgentCheckpointRecord<Data> {
+    /** Checkpoint identifier, preserved across export and restore. */
     readonly id: string;
+    /** Validated branch identity captured at checkpoint time. */
     readonly source: AgentBranch;
+    /** Detached data payload; serializable by the host. */
     readonly data: Data;
 }
-/** Bounded execution shared by applications; business rules are registered by each host. */
+/**
+ * Bounded execution shared by applications; business rules are registered by each host.
+ *
+ * Configuration is bound before a run and may be bound only once per model, tool runtime
+ * and workflow. A run resolves its signal from the engine, the request runtime and the
+ * caller, then executes either the bound workflow or a supplied step function until the
+ * round budget, cancellation or a completion stops it.
+ */
 export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
+    /** Workflow catalog constructor, exposed so hosts do not import two modules. */
     static readonly Workflow: typeof AgentWorkflow;
+    /** Attempt budget, exposed for hosts that gate their own sub-steps. */
     static readonly AttemptBudget: typeof AttemptBudget;
+    /** Factory for a validated workflow definition. */
     static readonly createWorkflow: typeof defineWorkflow;
     private readonly maxRounds;
     private readonly exhausted;
@@ -67,27 +118,145 @@ export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
     private models?;
     private selectedModelId?;
     private maxModelCalls?;
+    /**
+     * Compile model options and reject engine-owned settings.
+     *
+     * @param options - Model binding supplied to the engine.
+     * @returns The compiled binding.
+     * @throws TypeError When the binding carries its own execution scope.
+     */
     private snapshotModel;
+    /**
+     * Bind the single model this engine will use.
+     *
+     * @param options - App model settings.
+     * @returns This engine, for chaining.
+     * @throws TypeError When a model is already bound or the settings are invalid.
+     */
     bindModel(options: AgentModelBinding): this;
-    /** Bind an existing request lifetime once, for App services sharing this Runner's budget. */
+    /**
+     * Bind an existing request lifetime once, for App services sharing this Runner's budget.
+     *
+     * Callbacks are bound to the source runtime and the counters stay live getters, so the
+     * engine and the App observe exactly the same budget and signal.
+     *
+     * @param source - Request model runtime owned by the App.
+     * @returns This engine, for chaining.
+     * @throws Error When another model is already bound or the runtime lacks a usable signal.
+     */
     bindModelRuntime(source: AgentModelRuntime): this;
+    /**
+     * Select a configured model, or replace the single bound model's configuration.
+     *
+     * @param options - A configured model id, or new settings for the single bound model.
+     * @returns This engine, for chaining.
+     * @throws WorkflowContractError When the id is not configured.
+     * @throws TypeError When no single model is bound to switch.
+     */
     switchModel(options: AgentModelBinding | string): this;
+    /**
+     * Look up a configured model by id.
+     *
+     * @param id - Configured model id.
+     * @param models - Configured model map, when the engine uses a catalog.
+     * @returns The compiled binding.
+     * @throws WorkflowContractError When the id is not configured.
+     */
     private requireModel;
+    /**
+     * Compile and store the single bound model.
+     *
+     * @param options - App model settings.
+     * @returns This engine, for chaining.
+     */
     private setModel;
     private invokeTool?;
+    /**
+     * Bind the tool runtime used by workflow context.
+     *
+     * @param tools - Registry exposing `invokeAsync`, or an object exposing `invoke`.
+     * @returns This engine, for chaining.
+     * @throws TypeError When tools are already bound or expose no invoke method.
+     */
     bindToolRuntime(tools: ToolBinding): this;
     private boundWorkflow?;
+    /**
+     * Bind a workflow, narrowing the engine's state and App types.
+     *
+     * Binding changes the engine's type parameters without changing its identity, so the
+     * same instance keeps its model, tools and branch.
+     *
+     * @param workflow - Workflow to execute.
+     * @returns The same engine typed for the workflow's state.
+     */
     bindWorkflow<NextState>(workflow: AgentWorkflow<NextState, Result, undefined>): AgentCoreEngine<Result, NextState, undefined>;
+    /**
+     * Bind a workflow together with its App dependencies.
+     *
+     * @param workflow - Workflow to execute.
+     * @param app - Dependencies passed to every node and route as `context.app`.
+     * @returns The same engine typed for the workflow's state and App.
+     */
     bindWorkflow<NextState, NextApp>(workflow: AgentWorkflow<NextState, Result, NextApp>, app: NextApp): AgentCoreEngine<Result, NextState, NextApp>;
+    /**
+     * Store the workflow and its dependencies.
+     *
+     * @param workflow - Workflow to execute.
+     * @param app - App dependencies handed to every node and route.
+     * @throws TypeError When a workflow is already bound.
+     */
     private bind;
+    /** The bound workflow. */
     get workflow(): AgentWorkflow<State, Result, App>;
     private branchIdentity;
     private readonly checkpoints;
+    /** Identity of this engine's branch. */
     get branch(): AgentBranch;
+    /**
+     * Take an in-memory checkpoint of host-owned data.
+     *
+     * The data is cloned on write and on every read, so neither side can mutate the other.
+     *
+     * @param data - Serializable data to capture.
+     * @returns A checkpoint bound to this branch.
+     */
     checkpoint<Data>(data: Data): AgentCheckpoint<Data>;
+    /**
+     * Export a checkpoint for host-owned persistence.
+     *
+     * @param checkpoint - Checkpoint taken by this engine.
+     * @returns A serializable record with a validated branch identity.
+     * @throws Error When the checkpoint belongs to another engine.
+     */
     exportCheckpoint<Data>(checkpoint: AgentCheckpoint<Data>): AgentCheckpointRecord<Data>;
+    /**
+     * Recreate a checkpoint from a persisted record.
+     *
+     * The record's branch must match this engine's branch exactly; otherwise persisted data
+     * from another branch would be adopted silently.
+     *
+     * @param record - Record produced by `exportCheckpoint`.
+     * @returns A checkpoint bound to this engine.
+     * @throws Error When the id is invalid or the branch identity differs.
+     */
     restoreCheckpoint<Data>(record: AgentCheckpointRecord<Data>): AgentCheckpoint<Data>;
-    fork<Data>({ at, workflow, routes, resume }: {
+    /**
+     * Create an engine on a new branch forked at a checkpoint.
+     *
+     * The forked engine keeps the round budget, observation and configuration, receives an
+     * optional workflow extension, and gets a new branch identity whose parent ids point at
+     * this engine. Live handles are not copied: an App dependency, request runtime or tool
+     * runtime must be restored by the `resume` callback, because they cannot be serialized.
+     *
+     * @param request.at - Checkpoint taken by this engine to fork from.
+     * @param request.workflow - Optional extension or replacement workflow.
+     * @param request.routes - Route overrides; only valid with a workflow instance.
+     * @param request.resume - Receives the checkpoint data and returns restored dependencies.
+     * @returns A new engine on the forked branch.
+     * @throws TypeError When the checkpoint is foreign or the App dependency is missing.
+     * @throws Error When a bound request runtime or tool runtime was not restored.
+     */
+    fork<Data>({ at, workflow, routes, resume, }: {
         at: AgentCheckpoint<Data>;
         workflow?: AgentWorkflow<State, Result, App> | WorkflowExtension<State, Result, App>;
         routes?: WorkflowExtension<State, Result, App>['routes'];
@@ -97,22 +266,139 @@ export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
             model?: AgentModelRuntime;
         };
     }): AgentCoreEngine<Result, State, App>;
+    /**
+     * Build an engine and validate its wiring.
+     *
+     * Legacy top-level names (`maxSteps`, `exhausted`, `signal`, `diagnostics`,
+     * `onWorkflowEvent`, `observe`) are rejected rather than ignored, because silently
+     * dropping them would change budgets or observation.
+     *
+     * @param settings - Round budget, errors, execution scope, model, tools, workflow and branch.
+     * @throws TypeError When settings are invalid, removed names are used, or model wiring is
+     * inconsistent.
+     */
     constructor(settings?: AgentCoreEngineSetup<State, Result, App>);
+    /**
+     * Run the loop with a step function when no workflow is bound.
+     *
+     * @param step - Receives the round index and context; returns continue or complete.
+     * @param options - Optional caller signal; a model id requires a bound workflow.
+     * @returns The value of the completing step.
+     */
     run(step: CoreStep<Result>, options?: {
         signal?: AbortSignal;
         modelId?: never;
     }): Promise<Result>;
+    /**
+     * Run a bound workflow from an initial state.
+     *
+     * @param state - Initial workflow state; node updates are committed into it.
+     * @param options - Optional caller signal and per-run model id.
+     * @returns The workflow result.
+     */
     run(state: State, options?: {
         signal?: AbortSignal;
         modelId?: string;
     }): Promise<Result>;
+    /**
+     * Resolve the lifetime of one run.
+     *
+     * All three sources are lifetime bounds only, so the strictest wins and no source can
+     * extend another.
+     *
+     * @param requestSignal - Caller-supplied signal for this run.
+     * @returns The combined signal.
+     */
     private executionSignal;
+    /**
+     * Resolve the observation scope for one run.
+     *
+     * A bound request runtime contributes its scope only when the engine has none, so one
+     * fact source serves both the App and the engine.
+     *
+     * @returns Execution options with the effective diagnostic scope.
+     */
     private executionOptions;
+    /**
+     * Drive a caller-supplied step function until it completes or the budget ends.
+     *
+     * Each iteration is a round: the step must return an explicit continue/complete outcome,
+     * the continue path owns the round limit, and a report scope always closes before the
+     * next round starts. Failures leave the loop and are rethrown after the scope closes.
+     *
+     * @param step - Step implementation receiving the round index and context.
+     * @param requestSignal - Caller signal for this run.
+     * @returns The value of the completing step.
+     * @throws WorkflowContractError When the step returns something other than continue/complete.
+     * @throws The configured exhausted error, the step's failure, or the signal reason.
+     */
     private runLoop;
+    /**
+     * Traverse a workflow node by node.
+     *
+     * Per visit the order is fixed: cancellation and round-budget checks, `requires`
+     * validation, the node handler, commit of `provides`, route selection, then either
+     * completion or transition. Failures are reported before any recovery decision, and only
+     * non-aborted, non-contract failures may follow `onErrorNodeId`; anything else propagates.
+     *
+     * @param workflow - Validated workflow catalog.
+     * @param state - Initial state; mutated in place by commits.
+     * @param app - Host dependencies exposed as `context.app`.
+     * @param requestSignal - Caller signal for this run.
+     * @param requestModelId - Per-run configured model override.
+     * @returns The workflow result.
+     * @throws WorkflowContractError for contract violations, or the node failure otherwise.
+     */
     private executeWorkflow;
+    /**
+     * Merge a node's state update and assert its declared outputs.
+     *
+     * The update is read once, checked against `provides` on the merged view, and only then
+     * written into the state, so a missing output never leaves a half-applied update.
+     * Cancellation is checked between the check and the write.
+     *
+     * @param state - State mutated in place.
+     * @param update - Object returned by the node handler, or undefined for no change.
+     * @param provides - Fields the node promises to leave defined.
+     * @param signal - Signal checked immediately before writing.
+     * @throws WorkflowContractError When the update is not an object or a provided field is
+     * undefined.
+     */
     private commit;
+    /**
+     * Publish one loop event.
+     *
+     * The report scope is closed before emission for every event type, including `enter`,
+     * so a step cannot report progress against a round that has already ended.
+     *
+     * @param event - Loop event without its id.
+     * @param diagnostics - Scope of the current round.
+     * @param reports - Report scope for the current round.
+     */
     private emitLoop;
+    /**
+     * Publish one workflow event and attach the node's report when content is enabled.
+     *
+     * The event is always emitted, even if the report throws or is malformed; a report is
+     * optional evidence, while the event is the authoritative transition record.
+     *
+     * @param input - Event fields without its id.
+     * @param diagnostics - Scope of the current node visit.
+     * @param report - Optional report builder evaluated only when content is enabled.
+     * @param reports - Report scope closed after emission.
+     * @returns The frozen event, so callers can reference its id.
+     */
     private emit;
+    /**
+     * Classify a failure for reporting.
+     *
+     * Cancellation takes precedence over the error itself: once the signal is aborted, the
+     * reason matters more than whatever the interrupted code threw.
+     *
+     * @param error - Failure to classify.
+     * @param signal - Execution signal at the time of failure.
+     * @returns `TIMEOUT`, `CANCELLED`, or the error's own code.
+     */
     private errorCode;
 }
-export type { CoreStep, StepOutcome, LoopEvent, AgentCoreEngineOptions } from '../structs/execution/engine.js';
+export type { CoreStep, StepOutcome, LoopEvent, AgentCoreEngineOptions, } from '../structs/execution/engine.js';