@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/execution/state.js

@@ -1,25 +1,65 @@
 import { WorkflowContractError } from '../structs/errors.js';
+/**
+ * Read a state field that must already be present.
+ *
+ * Used by `requires` declarations and terminal deliveries, so a node cannot observe a
+ * field as undefined and silently produce a wrong result.
+ *
+ * @param state - Current workflow state.
+ * @param key - Field to read.
+ * @returns The field value, narrowed to exclude undefined.
+ * @throws WorkflowContractError When the field is undefined.
+ */
 export function requireWorkflowValue(state, key) {
     const value = state[key];
     if (value === undefined)
         throw new WorkflowContractError(`Missing workflow state: ${String(key)}`);
     return value;
 }
+/**
+ * Build a reader for one state path.
+ *
+ * Dotted string paths traverse nested objects and stop safely at undefined; any other key
+ * is read directly from the state. Both forms share the returned reader so route
+ * conditions stay uniform.
+ *
+ * @param path - Dotted path or direct key.
+ * @returns A function reading the value from a state object.
+ */
 function readPath(path) {
     const keys = typeof path === 'string' ? path.split('.') : [path];
     return (state) => keys.reduce((value, key) => value?.[key], state);
 }
-/** Unconditional jump with a stable, target-derived route ID. */
+/**
+ * Unconditional jump with a stable, target-derived route ID.
+ *
+ * @param target - Destination node id.
+ * @param id - Optional explicit route id.
+ * @returns A terminal-free route that always matches.
+ */
 const routeTo = function route(target, id) {
     return { id: id ?? `to-${target}`, targetNodeId: target };
 };
-/** One conditional jump, using the same strict equality as a handwritten route. */
+/**
+ * One conditional jump, using the same strict equality as a handwritten route.
+ *
+ * A derived route id is only produced for symbol-free paths and primitive values,
+ * because those are the cases where `String(value)` is stable and unique enough to name
+ * the condition.
+ *
+ * @param target - Destination node id.
+ * @param path - State path to compare.
+ * @param value - Expected value, compared with `===`.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when the path equals `value`.
+ */
 function toIfEqual(target, path, value, options) {
     const stableValue = value === null || ['undefined', 'string', 'boolean', 'number', 'bigint'].includes(typeof value);
     const condition = typeof path !== 'symbol' && stableValue
         ? JSON.stringify([String(path), typeof value, String(value)])
         : undefined;
-    const id = options?.id ?? (condition === undefined ? undefined : `route:${JSON.stringify([condition, target])}`);
+    const id = options?.id ??
+        (condition === undefined ? undefined : `route:${JSON.stringify([condition, target])}`);
     const conditionId = options?.conditionId ?? (id === undefined ? undefined : '{nid}.{rid}');
     const read = readPath(path);
     return {
@@ -30,52 +70,138 @@ function toIfEqual(target, path, value, options) {
         targetNodeId: target,
     };
 }
-/** Jump when two state paths resolve to strictly equal values. */
+/**
+ * Jump when two state paths resolve to strictly equal values.
+ *
+ * No derived route id is produced for symbol paths, because a symbol cannot be embedded
+ * in a stable name.
+ *
+ * @param target - Destination node id.
+ * @param leftPath - First state path.
+ * @param rightPath - Second state path.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when both paths are strictly equal.
+ */
 function toIfEqualWith(target, leftPath, rightPath, options) {
     const left = readPath(leftPath);
     const right = readPath(rightPath);
-    const id = options?.id ?? (typeof leftPath === 'symbol' || typeof rightPath === 'symbol' ? undefined
-        : `route:with:${JSON.stringify([String(leftPath), String(rightPath), target])}`);
+    const id = options?.id ??
+        (typeof leftPath === 'symbol' || typeof rightPath === 'symbol'
+            ? undefined
+            : `route:with:${JSON.stringify([String(leftPath), String(rightPath), target])}`);
     return {
-        ...options, id,
+        ...options,
+        id,
         conditionId: options?.conditionId ?? (id === undefined ? undefined : '{nid}.{rid}'),
         when: (state) => left(state) === right(state),
         targetNodeId: target,
     };
 }
-/** Jump when a state array contains at least one entry. */
+/**
+ * Jump when a state array contains at least one entry.
+ *
+ * A non-array value never matches, so a mistyped field cannot be treated as populated.
+ *
+ * @param target - Destination node id.
+ * @param key - State path expected to hold an array.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches for a non-empty array.
+ */
 function toIfNotEmpty(target, key, options) {
     const read = readPath(key);
-    return { ...options, ...routeTo(target, options?.id), conditionId: options?.conditionId ?? '{nid}.{rid}', when: (state) => {
+    return {
+        ...options,
+        ...routeTo(target, options?.id),
+        conditionId: options?.conditionId ?? '{nid}.{rid}',
+        when: (state) => {
             const value = read(state);
             return Array.isArray(value) && value.length > 0;
-        } };
+        },
+    };
 }
-/** Jump once a state field has a value. */
+/**
+ * Jump once a state field has a value.
+ *
+ * `null` counts as present: only `undefined` means the field is still unset.
+ *
+ * @param target - Destination node id.
+ * @param field - State path to inspect.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when the field is not undefined.
+ */
 function toIfDefined(target, field, options) {
     const read = readPath(field);
-    return { ...options, ...routeTo(target, options?.id), conditionId: options?.conditionId ?? '{nid}.{rid}', when: (state) => read(state) !== undefined };
+    return {
+        ...options,
+        ...routeTo(target, options?.id),
+        conditionId: options?.conditionId ?? '{nid}.{rid}',
+        when: (state) => read(state) !== undefined,
+    };
 }
-/** Jump to the node named by a truthy state field. */
+/**
+ * Jump to the node named by a truthy state field.
+ *
+ * The same field is used as the condition and as the destination, which is the usual
+ * shape of a dispatcher that stored its own next node.
+ *
+ * @param target - Field holding the destination node id.
+ * @param options - Optional id, condition id and description.
+ * @returns A route that matches when the field is truthy.
+ */
 function toIf(target, options) {
-    return { ...toIfDefined(target, target, options), when: (state) => Boolean(state[target]) };
+    return {
+        ...toIfDefined(target, target, options),
+        when: (state) => Boolean(state[target]),
+    };
 }
 function toIfError(target, { errorKey = 'error', ...options } = {}) {
     return toIfDefined(target, errorKey, options);
 }
-/** At a terminal node, the result must already exist. */
+/**
+ * At a terminal node, the result must already exist.
+ *
+ * Completing reads the field with `requireWorkflowValue`, so a node that forgot to
+ * produce its result fails instead of returning undefined.
+ *
+ * @param field - State field holding the final result.
+ * @param options - Optional id and description; a condition id is meaningless here.
+ * @returns A completion route with the default id `complete`.
+ */
 function deliver(field, options) {
     const id = options?.id ?? 'complete';
     return {
-        ...options, id,
+        ...options,
+        id,
         complete: (state) => requireWorkflowValue(state, field),
     };
 }
-/** Deliver an available result, or let the next route decide. */
+/**
+ * Deliver an available result, or let the next route decide.
+ *
+ * Unlike `deliver`, this route carries a condition so a following route still has a
+ * chance to match when the field is still unset.
+ *
+ * @param field - State field holding the result.
+ * @param options - Optional route metadata.
+ * @returns A conditional completion route.
+ */
 function deliverIfReady(field, options) {
-    return { ...deliver(field, options), conditionId: options?.conditionId ?? '{nid}.{rid}', when: (state) => state[field] !== undefined };
+    return {
+        ...deliver(field, options),
+        conditionId: options?.conditionId ?? '{nid}.{rid}',
+        when: (state) => state[field] !== undefined,
+    };
 }
-/** Apply the shared continue/complete outcome contract. */
+/**
+ * Apply the shared continue/complete outcome contract.
+ *
+ * The field holds a `StepOutcome`; only the `complete` variant ends the workflow, and the
+ * completion asserts the variant instead of trusting the condition.
+ *
+ * @param field - State field holding the outcome.
+ * @param options - Optional route metadata.
+ * @returns A conditional completion route that unwraps the outcome value.
+ */
 function deliverWhenComplete(field, options) {
     return {
         ...options,
@@ -90,8 +216,21 @@ function deliverWhenComplete(field, options) {
         },
     };
 }
-/** Callable route catalog; aliases share the same function without namespace initialization. */
+/**
+ * Callable route catalog; aliases share the same function without namespace initialization.
+ *
+ * `route(...)` and `route.to(...)` are the same function, so both call styles stay
+ * interchangeable and no module-level setup is required to use either.
+ */
 export const route = Object.assign(routeTo, {
-    to: routeTo, toIfEqual, toIfEqualWith, toIfNotEmpty, toIfDefined, toIf, toIfError,
-    deliver, deliverIfReady, deliverWhenComplete,
+    to: routeTo,
+    toIfEqual,
+    toIfEqualWith,
+    toIfNotEmpty,
+    toIfDefined,
+    toIf,
+    toIfError,
+    deliver,
+    deliverIfReady,
+    deliverWhenComplete,
 });

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

@@ -1,20 +1,77 @@
 import type { AgentWorkflowDefinition, WorkflowExtension, WorkflowNode } from '../structs/execution/workflow.js';
-/** Executable catalog: validate references and bounded cycles before any handler runs. */
+/**
+ * Executable catalog: validate references and bounded cycles before any handler runs.
+ *
+ * Validation happens once, at construction, so traversal can assume every target exists
+ * and every cycle is budget-bounded.
+ */
 export declare class AgentWorkflow<State, Result, Runtime = undefined> {
+    /** Workflow id, also used in diagnostics and error messages. */
     readonly id: string;
+    /** First node visited; always starts a round. */
     readonly entryNodeId: string;
+    /** Optional revision passed through to diagnostics. */
     readonly revision?: string;
+    /** Optional result guard; when present it must return exactly true. */
     readonly isResult?: (result: Result) => boolean;
     private readonly nodes;
+    /**
+     * Build and validate a workflow.
+     *
+     * The entry node must start a round, because otherwise a workflow could loop forever
+     * without consuming the round budget. Renamed top-level fields are rejected as well.
+     *
+     * @param definition - Nodes, entry, id, optional revision and result guard.
+     * @throws TypeError When the definition, a node, a route or a graph invariant is invalid.
+     */
     constructor(definition: AgentWorkflowDefinition<State, Result, Runtime>);
+    /**
+     * Derive an extended workflow without mutating this catalog.
+     *
+     * Every node is copied with its callbacks rebound, so the new catalog keeps the same
+     * entry and result guard and can be composed repeatedly. Route overrides are keyed by
+     * node id and must name a node that exists after the merge.
+     *
+     * @param extension - Extension patch, or another workflow whose definitions are merged.
+     * @param routes - Route overrides keyed by node id.
+     * @returns A new, fully re-validated workflow.
+     * @throws TypeError When an override names an unknown node or a node is invalid.
+     */
     add(extension: WorkflowExtension<State, Result, Runtime> | AgentWorkflow<State, Result, Runtime>, routes?: WorkflowExtension<State, Result, Runtime>['routes']): AgentWorkflow<State, Result, Runtime>;
+    /**
+     * Look up a node that must exist.
+     *
+     * @param id - Node id.
+     * @returns The registered node.
+     * @throws TypeError When the node is unknown.
+     */
     require(id: string): WorkflowNode<State, Result, Runtime>;
+    /** Frozen snapshot of all nodes, in registration order. */
     get definitions(): readonly Readonly<WorkflowNode<State, Result, Runtime>>[];
+    /** @returns A frozen array of node ids in registration order. */
     ids(): readonly string[];
+    /** @returns An iterator over the registered nodes. */
     values(): MapIterator<WorkflowNode<State, Result, Runtime>>;
+    /** @returns An iterator over id/node pairs. */
     entries(): MapIterator<[string, WorkflowNode<State, Result, Runtime>]>;
+    /**
+     * @param id - Node id.
+     * @returns Whether the node is registered.
+     */
     has(id: string): boolean;
+    /**
+     * @param id - Node id.
+     * @returns The node, or undefined when it is not registered.
+     */
     get(id: string): WorkflowNode<State, Result, Runtime> | undefined;
+    /**
+     * Produce a serializable description of every node and route.
+     *
+     * Used by documentation and registration listings; it reports resolved ids and which
+     * routes are terminal or conditional, never the handler implementations.
+     *
+     * @returns An array of plain description objects in registration order.
+     */
     describe(): {
         startsRound: boolean;
         onErrorNodeId: string | undefined;
@@ -32,22 +89,83 @@ export declare class AgentWorkflow<State, Result, Runtime = undefined> {
         id: string;
         description: string;
     }[];
+    /**
+     * Validate and freeze one node, then add it to the catalog.
+     *
+     * A route must be either a jump with a target or a completion, never both; an
+     * unconditional route must be last, because it would shadow every later route. Route
+     * ids and condition ids are resolved here so the engine never interpolates templates at
+     * run time.
+     *
+     * @param node - Node supplied by the workflow definition.
+     * @throws TypeError When the node, a route or a state contract is invalid.
+     */
     private register;
+    /**
+     * Collect every node a visit can hand control to.
+     *
+     * Error targets are included so a recovery node is treated as reachable and is subject
+     * to the same cycle rule as a normal transition.
+     *
+     * @param node - Node whose outgoing edges are collected.
+     * @returns Target node ids, including the error node.
+     */
     private targets;
+    /**
+     * Require every route target to name a registered node.
+     *
+     * @throws TypeError When any target is unknown.
+     */
     private checkReferences;
+    /**
+     * Require every node to be reachable from the entry.
+     *
+     * An unreachable node is a declaration mistake: it would never run, yet it still
+     * appears in listings and documentation.
+     *
+     * @throws TypeError When any node cannot be reached.
+     */
     private checkReachability;
+    /**
+     * Require every cycle to cross a round boundary.
+     *
+     * @throws TypeError When a cycle can be traversed without ever starting a new round.
+     */
     private checkBoundedCycles;
 }
+/**
+ * Build a validated workflow from a definition.
+ *
+ * @param definition - Workflow definition; validated like the constructor argument.
+ * @returns A validated, immutable workflow catalog.
+ * @throws TypeError When the definition is invalid.
+ */
 export declare function defineWorkflow<State, Result, Runtime = undefined>(definition: AgentWorkflowDefinition<State, Result, Runtime>): AgentWorkflow<State, Result, Runtime>;
-/** Successful acquisitions consume attempts; a refused acquisition never grants another. */
+/**
+ * Successful acquisitions consume attempts; a refused acquisition never grants another.
+ *
+ * `available` is a snapshot of the counter, not a reservation: a caller must still call
+ * `take` and honor its boolean result before acting.
+ */
 export declare class AttemptBudget {
     readonly limit: number;
     private consumed;
+    /**
+     * @param limit - Total attempts allowed; must be a nonnegative integer.
+     * @throws TypeError When `limit` is not a nonnegative integer.
+     */
     constructor(limit: number);
+    /** Attempts consumed so far. */
     get used(): number;
+    /** Whether at least one attempt remains unspent. */
     get available(): boolean;
+    /**
+     * Consume one attempt if one remains.
+     *
+     * @returns True when the attempt was granted, false when the budget is exhausted.
+     */
     take(): boolean;
 }
 export { requireWorkflowValue, route } from './state.js';
-export type { WorkflowContext, WorkflowModel, WorkflowRoute, WorkflowNode, WorkflowNodeReport, WorkflowExtension, AgentWorkflowDefinition, WorkflowEvent } from '../structs/execution/workflow.js';
+export type { WorkflowContext, WorkflowModel, WorkflowRoute, WorkflowNode, WorkflowNodeReport, WorkflowExtension, AgentWorkflowDefinition, WorkflowEvent, } from '../structs/execution/workflow.js';
 export { WorkflowContractError } from '../structs/errors.js';