@statelyai/agent 1.1.5 → 2.0.0-alpha.10

package/dist/index.d.mts

@@ -1,428 +1,212 @@
-import { EventObject, AnyStateMachine, AnyEventObject, AnyActorRef, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, ActorRefFrom, Subscription, StateValue, ObservableActorLogic } from 'xstate';
-import { SomeZodObject, ZodType, TypeOf } from 'zod';
-import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, StreamTextResult, CoreTool } from 'ai';
+import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as EventUnion, a as AgentTool, b as InferOutput, c as AgentToolExecute, d as AllowedEventPattern, f as AllowedEvents, g as EventPayload, h as DataContent, i as AgentSnapshotStore, k as ToolResultPart, l as AgentToolSchema, m as ChosenEvent, n as AgentEventSchemaInputMap, o as AgentToolChoice, p as AssistantMessage, r as AgentMessage, s as AgentToolDescriptor, t as AgentEventSchemaInput, u as AgentTools, v as FilePart, w as SystemMessage, x as NormalizedEventSchemas, y as ImagePart } from "./types-qm00QF91.mjs";
+import { A as AgentDecisionInput, B as renderDecisionAttempts, C as createTextLogic, D as parseOutput, E as parseModelRef, F as DecisionExhaustedError, G as AgentRequestSource, H as AgentEventDescriptor, I as DecisionLogic, J as matchesEventPattern, K as EVENT_TOOL_PREFIX, L as DecisionLogicConfig, M as AgentPlanInput, N as AgentPlanOutput, O as parseStructuredEnvelope, P as DecisionAttempt, R as PLAN_DONE_EVENT_TYPE, S as buildEnvelopeSchema, T as isStructuredOutputSchema, U as AgentEventToolNameResolver, V as resolveDecision, W as AgentRequestOptions, Y as parseAgentEvent, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, m as StructuredOutputEnvelope, n as AgentModelRef, o as AgentRequestExecutorResult, q as getAcceptedEvents, r as AgentOutputMode, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, w as getAgentOutputMode, x as bindRequestExecutor, y as TextLogicInput, z as ResolveDecisionOptions } from "./text-logic-C7WJpCIc.mjs";
+import { A as AgentSchemaPack, B as AgentWorkflowStateConfig, C as initialAgentStep, D as AgentMachine, E as transitionAgentStep, F as AgentWorkflowActionConfig, G as messagesSchema, H as FromConfigOptions, I as AgentWorkflowActorConfig, L as AgentWorkflowConfig, M as AgentStateNarrowing, N as createAgentSchemas, O as AgentMachineConfig, P as setupAgent, R as AgentWorkflowInvokeConfig, S as getAgentRequests, T as resolveAgentStep, U as SchemaCompiler, V as AgentWorkflowTransitionConfig, W as appendMessages, _ as AgentRequest, a as AgentUserInputExecutor, b as ResolveAgentRequestsOptions, c as PendingUserInput, d as SnapshotVersionMismatchError, f as inspectTransitions, g as AgentPlanRequest, h as AgentStateRequest, i as AgentTraceEvent, j as AgentSetupStateSchema, k as AgentRequestConfig, l as RunAgentOptions, m as runAgentToCompletion, n as AgentMessageInfo, o as IllegalResumeEventError, p as runAgent, r as AgentRunMeta, s as InspectedActorRef, t as AgentIdleError, u as RunAgentResult, v as AgentStep, w as resolveAgentRequests, x as executeAgentRequest, y as AgentStepRequest, z as AgentWorkflowRequestConfig } from "./run-agent-DzYJb3CK.mjs";
+import { a as getMachineStructuralHash, c as persistSnapshot, d as userMessage, f as validateSchemaSync, i as getJsonSchemaSync, l as systemMessage, n as getAgentMessages, o as getStateMeta, r as getJsonSchema, s as isStandardSchema, t as assistantMessage, u as toolMessage } from "./utils-Y6GDRGGE.mjs";
+import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
 
-type ZodEventMapping = {
-    [eventType: string]: SomeZodObject;
-};
-type ZodContextMapping = {
-    [contextKey: string]: ZodType;
-};
-
-type GenerateTextOptions = Parameters<typeof generateText>[0];
-type StreamTextOptions = Parameters<typeof streamText>[0];
-type AgentPlanInput<TEvent extends EventObject> = Omit<GenerateTextOptions, 'prompt' | 'messages' | 'tools'> & {
-    /**
-     * The currently observed state.
-     */
-    state: ObservedState;
-    /**
-     * The goal for the agent to accomplish.
-     * The agent will create a plan based on this goal.
-     */
-    goal: string;
-    /**
-     * The events that the agent can trigger. This is a mapping of
-     * event types to Zod event schemas.
-     */
-    events: ZodEventMapping;
-    /**
-     * The state machine that represents the environment the agent
-     * is interacting with.
-     */
-    machine?: AnyStateMachine;
-    /**
-     * The previous plan.
-     */
-    previousPlan?: AgentPlan<TEvent>;
-};
-type AgentPlan<TEvent extends EventObject> = {
-    goal: string;
-    state: ObservedState;
-    content?: string;
-    /**
-     * Executes the plan based on the given `state` and resolves with
-     * a potential next `event` to trigger to achieve the `goal`.
-     */
-    execute: (state: ObservedState) => Promise<TEvent | undefined>;
-    nextEvent: TEvent | undefined;
-    sessionId: string;
-    timestamp: number;
-};
-interface TransitionData {
-    eventType: string;
-    description?: string;
-    guard?: {
-        type: string;
-    };
-    target?: any;
+//#region src/verify.d.ts
+/** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
+type AgentLintSeverity = "error" | "warning";
+/**
+ * One static-analysis finding from {@link lintAgentMachine}. `code` names the
+ * check (stable, machine-readable), `path` points at the offending state path
+ * or config location, and `message` explains the problem and its remedy.
+ */
+interface AgentLintDiagnostic {
+  code: "unreachable-state" | "decide-without-events" | "unserializable-context" | "direct-object-src" | "final-without-output" | "final-output-reads-event" | "missing-final";
+  severity: AgentLintSeverity;
+  /** State path (`parent.child`) or config pointer (e.g. `(root)`, `context`) the finding is about. */
+  path: string;
+  message: string;
 }
-type PromptTemplate<TEvents extends EventObject> = (data: {
-    goal: string;
-    /**
-     * The observed state
-     */
-    state?: ObservedState;
-    /**
-     * The context to provide.
-     * This overrides the observed state.context, if provided.
-     */
-    context?: any;
-    /**
-     * The state machine model of the observed environment
-     */
-    machine?: unknown;
-    /**
-     * The potential next transitions that can be taken
-     * in the state machine
-     */
-    transitions?: TransitionData[];
-    /**
-     * Past observations
-     */
-    observations?: AgentObservation<any>[];
-    feedback?: AgentFeedback[];
-    messages?: AgentMessage[];
-    plans?: AgentPlan<TEvents>[];
-}) => string;
-type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
-type AgentDecideOptions = {
-    goal: string;
-    model?: LanguageModel;
-    context?: any;
-    state: ObservedState;
-    machine: AnyStateMachine;
-    execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<any>;
-    events?: ZodEventMapping;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt' | 'messages'>;
-interface AgentFeedback {
-    goal?: string;
-    observationId?: string;
-    /**
-     * The message correlation that the feedback is relevant for
-     */
-    correlationId?: string;
-    attributes: Record<string, any>;
-    reward: number;
-    timestamp: number;
-    sessionId: string;
+/** Options for {@link lintAgentMachine}. Reserved for future check selection. */
+interface LintAgentMachineOptions {
+  /** Skip these check codes entirely. */
+  disable?: AgentLintDiagnostic["code"][];
 }
-interface AgentFeedbackInput {
-    goal?: string;
-    observationId?: string;
-    correlationId?: string;
-    attributes?: Record<string, any>;
-    timestamp?: number;
-    reward?: number;
+/**
+ * Runs static structural checks over a built agent machine and returns the
+ * findings ({@link AgentLintDiagnostic}[], empty when clean). Works for
+ * TS-authored (`setupAgent(...).createMachine(...)`) and
+ * `setupAgent.fromConfig(...)`-compiled machines alike, reading `machine.config`
+ * plus the schemas/actor sources the library already retains per machine.
+ *
+ * No model calls, no API keys — a coding agent that emits an agent machine can
+ * call this to catch dead states, undeliverable decisions, un-rebindable
+ * invoke srcs, and output-contract gaps before ever running it.
+ *
+ * @example
+ * ```ts
+ * const errors = lintAgentMachine(machine).filter((d) => d.severity === 'error');
+ * if (errors.length) throw new Error(errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
+ * ```
+ */
+declare function lintAgentMachine(machine: AnyStateMachine, options?: LintAgentMachineOptions): AgentLintDiagnostic[];
+/** Options for {@link assertAgentMachine}. */
+interface AssertAgentMachineOptions extends LintAgentMachineOptions {
+  /** Also fail on warning-severity findings. Default: errors only. */
+  warnings?: boolean;
 }
-type AgentMessage = CoreMessage & {
-    timestamp: number;
-    id: string;
-    /**
-     * The response ID of the message, which references
-     * which message this message is responding to, if any.
-     */
-    responseId?: string;
-    result?: GenerateTextResult<any>;
-    sessionId: string;
-    correlationId: string;
-    parentCorrelationId?: string;
-};
-type AgentMessageInput = CoreMessage & {
-    timestamp?: number;
-    id?: string;
-    /**
-     * The response ID of the message, which references
-     * which message this message is responding to, if any.
-     */
-    responseId?: string;
-    correlationId?: string;
-    parentCorrelationId?: string;
-    result?: GenerateTextResult<any>;
-};
-interface AgentObservation<TActor extends AnyActorRef> {
+/**
+ * Thrown by {@link assertAgentMachine} when lint finds failing diagnostics.
+ * `diagnostics` holds the findings; the message lists them one per finding,
+ * so a test runner's failure output reads like the CLI's lint report.
+ */
+declare class AgentLintError extends Error {
+  diagnostics: AgentLintDiagnostic[];
+  constructor(machineId: string, diagnostics: AgentLintDiagnostic[]);
+}
+/**
+ * Asserts a machine passes {@link lintAgentMachine}: returns silently when
+ * clean, throws {@link AgentLintError} (with the findings on `.diagnostics`)
+ * otherwise. Fails on error-severity findings; set `warnings: true` to fail on
+ * warnings too. The one-liner for tests and generation loops:
+ *
+ * @example
+ * ```ts
+ * test('agent machine is structurally sound', () => {
+ *   assertAgentMachine(machine);
+ * });
+ * ```
+ */
+declare function assertAgentMachine(machine: AnyStateMachine, options?: AssertAgentMachineOptions): void;
+/**
+ * Scripted responses for a {@link simulateAgent} playthrough. Each channel is a
+ * by-`src` map of FIFO queues, consumed in the order the machine reaches the
+ * requests:
+ * - `text` — output values for text requests, keyed by request src (the
+ *   `setupAgent({ requests })` key, or `agent.generateText`/`agent.streamText`).
+ * - `decisions` — the {@link ChosenEvent} to apply for a decision request,
+ *   keyed by decision src (usually `agent.decide`).
+ * - `userInput` — output values for `agent.userInput` invokes, keyed by src
+ *   (usually `agent.userInput`).
+ */
+interface SimulationScript {
+  text?: Record<string, unknown[]>;
+  decisions?: Record<string, ChosenEvent[]>;
+  userInput?: Record<string, unknown[]>;
+}
+/** One entry in a {@link SimulateAgentResult.trail}: the state after this step, plus what drove the step. */
+interface SimulationTrailEntry {
+  /** The machine state value after applying this step. */
+  state: unknown;
+  /** The chosen event applied (for a decision request). */
+  appliedEvent?: ChosenEvent;
+  /** The resolved request (for a text/userInput invoke): its kind and src. */
+  resolvedRequest?: {
+    kind: "text" | "userInput";
+    src: string;
     id: string;
-    prevState: SnapshotFrom<TActor> | undefined;
-    event: EventFrom<TActor>;
-    state: SnapshotFrom<TActor>;
-    machineHash: string | undefined;
-    sessionId: string;
-    timestamp: number;
+  };
 }
-interface AgentObservationInput {
-    id?: string;
-    prevState: ObservedState | undefined;
-    event: AnyEventObject;
-    state: ObservedState;
-    machine?: AnyStateMachine;
-    timestamp?: number;
+/** Options for {@link simulateAgent}. */
+interface SimulateAgentOptions {
+  input?: unknown;
+  script: SimulationScript;
+  /** Max steps before returning `'exhausted'`. Default 100. */
+  maxSteps?: number;
 }
-type AgentDecisionInput = {
-    goal: string;
-    model?: LanguageModel;
-    context?: any;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
-type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<AgentPlan<TEvents> | undefined, AgentDecisionInput | string>;
-type AgentEmitted<TEvents extends EventObject> = {
-    type: 'feedback';
-    feedback: AgentFeedback;
-} | {
-    type: 'observation';
-    observation: AgentObservation<any>;
-} | {
-    type: 'message';
-    message: AgentMessage;
-} | {
-    type: 'plan';
-    plan: AgentPlan<TEvents>;
-};
-type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<AgentMemoryContext>, {
-    type: 'agent.feedback';
-    feedback: AgentFeedback;
-} | {
-    type: 'agent.observe';
-    observation: AgentObservation<any>;
-} | {
-    type: 'agent.message';
-    message: AgentMessage;
-} | {
-    type: 'agent.plan';
-    plan: AgentPlan<TEvents>;
-}, any, // TODO: input
-any, AgentEmitted<TEvents>>;
-type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
-    [K in keyof TEventSchemas & string]: {
-        type: K;
-    } & TypeOf<TEventSchemas[K]>;
-}>;
-type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
-    [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
-};
-type Agent<TContext, TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
-    /**
-     * The name of the agent. All agents with the same name are related and
-     * able to share experiences (observations, feedback) with each other.
-     */
-    name?: string;
-    /**
-     * The unique identifier for the agent.
-     */
-    id?: string;
-    description?: string;
-    events: ZodEventMapping;
-    types: {
-        events: TEvents;
-        context: Compute<TContext>;
-    };
-    model: LanguageModel;
-    defaultOptions: GenerateTextOptions;
-    memory: AgentLongTermMemory | undefined;
-    /**
-     * The adapter used to perform LLM actions such as
-     * `.generateText(…)` and `.streamText(…)`.
-     *
-     * Defaults to the Vercel AI SDK.
-     */
-    adapter: AIAdapter;
-    /**
-     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
-     *
-     * - The `goal` for the agent to achieve
-     * - The observed current `state`
-     * - The `machine` (e.g. a state machine) that specifies what can happen next
-     * - Additional `context`
-     */
-    decide: (options: AgentDecideOptions) => Promise<AgentPlan<TEvents> | undefined>;
-    generateText: (options: AgentGenerateTextOptions) => Promise<AgentGenerateTextResult>;
-    streamText: (options: AgentStreamTextOptions) => Promise<AgentStreamTextResult>;
-    addObservation: (observationInput: AgentObservationInput) => AgentObservation<any>;
-    addMessage: (messageInput: AgentMessageInput) => AgentMessage;
-    addFeedback: (feedbackInput: AgentFeedbackInput) => AgentFeedback;
-    addPlan: (plan: AgentPlan<TEvents>) => void;
-    /**
-     * Called whenever the agent (LLM assistant) receives or sends a message.
-     */
-    onMessage: (callback: (message: AgentMessage) => void) => void;
-    /**
-     * Selects agent data from its context.
-     *
-     * @deprecated Select from `agent.getSnapshot().context` directly or:
-     * - `agent.getMessages()`
-     * - `agent.getObservations()`
-     * - `agent.getFeedback()`
-     * - `agent.getPlans()`
-     */
-    select: <T>(selector: (context: AgentMemoryContext) => T) => T;
-    /**
-     * Retrieves messages from the agent's short-term (local) memory.
-     */
-    getMessages: () => AgentMessage[];
-    /**
-     * Retrieves observations from the agent's short-term (local) memory.
-     */
-    getObservations: () => AgentObservation<Agent<TContext, TEvents>>[];
-    /**
-     * Retrieves feedback from the agent's short-term (local) memory.
-     */
-    getFeedback: () => AgentFeedback[];
-    /**
-     * Retrieves strategies from the agent's short-term (local) memory.
-     */
-    getPlans: () => AgentPlan<TEvents>[];
-    /**
-     * Interacts with this state machine actor by inspecting state transitions and storing them as observations.
-     *
-     * Observations contain the `prevState`, `event`, and current `state` of this
-     * actor, as well as other properties that are useful when recalled.
-     * These observations are stored in the `agent`'s short-term (local) memory
-     * and can be retrieved via `agent.getObservations()`.
-     *
-     * @example
-     * ```ts
-     * // Only observes the actor's state transitions
-     * agent.interact(actor);
-     *
-     * actor.start();
-     * ```
-     */
-    interact<TActor extends AnyActorRef>(actorRef: TActor): Subscription;
-    /**
-     * Interacts with this state machine actor by:
-     * 1. Inspecting state transitions and storing them as observations
-     * 2. Deciding what to do next (which event to send the actor) based on
-     * the agent input returned from `getInput(observation)`, if `getInput(…)` is provided as the 2nd argument.
-     *
-     * Observations contain the `prevState`, `event`, and current `state` of this
-     * actor, as well as other properties that are useful when recalled.
-     * These observations are stored in the `agent`'s short-term (local) memory
-     * and can be retrieved via `agent.getObservations()`.
-     *
-     * @example
-     * ```ts
-     * // Observes the actor's state transitions and
-     * // makes a decision if on the "summarize" state
-     * agent.interact(actor, observed => {
-     *   if (observed.state.matches('summarize')) {
-     *     return {
-     *       context: observed.state.context,
-     *       goal: 'Summarize the message'
-     *     }
-     *   }
-     * });
-     *
-     * actor.start();
-     * ```
-     */
-    interact<TActor extends AnyActorRef>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
-};
-type AnyAgent = Agent<any, any>;
-type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
-type CommonTextOptions = {
-    prompt: FromAgent<string>;
-    model?: LanguageModel;
-    context?: Record<string, any>;
-    messages?: FromAgent<CoreMessage[]>;
-    template?: PromptTemplate<any>;
-    correlationId?: string;
-    parentCorrelationId?: string;
-};
-type TextResultMeta = {
-    correlationId: string;
-    parentCorrelationId?: string;
-};
-type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentGenerateTextResult = GenerateTextResult<any> & TextResultMeta;
-type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentStreamTextResult = StreamTextResult<any> & TextResultMeta;
-interface ObservedState {
-    /**
-     * The current state value of the state machine, e.g.
-     * `"loading"` or `"processing"` or `"ready"`
-     */
-    value: StateValue;
-    /**
-     * Additional contextual data related to the current state
-     */
-    context: Record<string, unknown>;
+/** The outcome of a {@link simulateAgent} playthrough. */
+interface SimulateAgentResult {
+  /** `'done'` = reached a final state; `'idle'` = paused with no pending work; `'exhausted'` = hit `maxSteps`. */
+  status: "done" | "idle" | "exhausted";
+  snapshot: AnyMachineSnapshot;
+  trail: SimulationTrailEntry[];
 }
-type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
-type AgentMemoryContext = {
-    observations: AgentObservation<any>[];
-    messages: AgentMessage[];
-    plans: AgentPlan<any>[];
-    feedback: AgentFeedback[];
-};
-type AgentMemory = AppendOnlyStorage<AgentMemoryContext>;
-interface AppendOnlyStorage<T extends Record<string, any[]>> {
-    append<K extends keyof T>(sessionId: string, key: K, item: T[K][0]): Promise<void>;
-    getAll<K extends keyof T>(sessionId: string, key: K): Promise<T[K] | undefined>;
+/**
+ * Deterministically plays a machine through, resolving each request from a
+ * {@link SimulationScript} instead of a model — no API keys, no model calls.
+ * Runs on the pure step path ({@link initialAgentStep} etc.), so it exercises
+ * the real transition logic. Returns the terminal `status`, final `snapshot`,
+ * and a `trail` of every step taken.
+ *
+ * Throws a descriptive error when the script runs dry mid-request, naming the
+ * pending request's kind, src, and id so the missing scripted response is
+ * obvious.
+ *
+ * @example
+ * ```ts
+ * const { status, snapshot } = simulateAgent(machine, {
+ *   input: { topic: 'state machines' },
+ *   script: { decisions: { 'agent.decide': [{ type: 'END' }] } },
+ * });
+ * ```
+ */
+declare function simulateAgent(machine: AnyStateMachine, options: SimulateAgentOptions): Promise<SimulateAgentResult>;
+/** Options for {@link explorePaths}. */
+interface ExplorePathsOptions {
+  input?: unknown;
+  /** Max branch points (decisions + external-event forks) along any path. Default 8. */
+  maxDepth?: number;
+  /** Total path cap before exploration stops (reported via `hitPathCap`). Default 200. */
+  maxPaths?: number;
+  /** Canned outputs for text/userInput invokes, keyed by src. A missing src halts that branch with a `needs-output` note. */
+  textOutputs?: Record<string, unknown>;
 }
-interface AgentLongTermMemory {
-    get<K extends keyof AgentMemoryContext>(key: K): Promise<AgentMemoryContext[K]>;
-    append<K extends keyof AgentMemoryContext>(key: K, item: AgentMemoryContext[K][0]): Promise<void>;
-    set<K extends keyof AgentMemoryContext>(key: K, items: AgentMemoryContext[K]): Promise<void>;
+/** A single explored path's terminal outcome. */
+interface AgentPathTerminal {
+  status: "done" | "idle" | "needs-output" | "max-depth";
+  /** The chosen/applied events, in order, that produced this terminal. */
+  path: ChosenEvent[];
+  /** The final state value on this path. */
+  state: unknown;
+  /** For `needs-output`: the src whose canned output was missing. */
+  missingSrc?: string;
 }
-interface AIAdapter {
-    generateText: typeof generateText;
-    streamText: typeof streamText;
+/** The report returned by {@link explorePaths}. */
+interface AgentPathReport {
+  /** Every distinct state value (JSON) encountered across all explored paths. */
+  reachedStates: unknown[];
+  /** One entry per explored path. */
+  terminals: AgentPathTerminal[];
+  /** How many candidate events were pruned because a guard rejected them. */
+  prunedByGuard: number;
+  /** Notes about coverage the exploration could not complete (missing outputs, depth/path caps). */
+  unexplored: string[];
+  /** Total paths explored. */
+  pathsExplored: number;
+  /** True when the total-paths cap was hit (report is partial). */
+  hitPathCap: boolean;
 }
-type Compute<A extends any> = {
-    [K in keyof A]: A[K];
-} & unknown;
-
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ name, description, model, events, context, planner, stringify, getMemory, logic, adapter, ...generateTextOptions }: {
-    /**
-     * The unique identifier for the agent.
-     *
-     * This should be the same across all sessions of a specific agent, as it can be
-     * used to retrieve memory for this agent.
-     *
-     * @example
-     * ```ts
-     * const agent = createAgent({
-     *  id: 'recipe-assistant',
-     *  // ...
-     * });
-     * ```
-     */
-    id?: string;
-    /**
-     * The name of the agent
-     */
-    name?: string;
-    /**
-     * A description of the role of the agent
-     */
-    description?: string;
-    /**
-     * Events that the agent can cause (send) in an environment
-     * that the agent knows about.
-     */
-    events: TEventSchemas;
-    context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContext, TEvents>>;
-    stringify?: typeof JSON.stringify;
-    /**
-     * A function that retrieves the agent's long term memory
-     */
-    getMemory?: (agent: Agent<TContext, TEvents>) => AgentLongTermMemory;
-    /**
-     * Agent logic
-     */
-    logic?: AgentLogic<TEvents>;
-    adapter?: AIAdapter;
-} & GenerateTextOptions): Agent<TContext, TEvents>;
-
-declare function fromTextStream<T extends AnyAgent>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
-    textDelta: string;
-}, Omit<AgentStreamTextOptions, 'context'> & {
-    context?: AgentStreamTextOptions['context'];
-}>;
-declare function fromText<T extends AnyAgent>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
-    context?: AgentGenerateTextOptions['context'];
-}>;
-
-declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
-
-export { type AIAdapter, type Agent, type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentGenerateTextResult, type AgentLogic, type AgentLongTermMemory, type AgentMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, type AgentStreamTextResult, type AnyAgent, type AppendOnlyStorage, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TextResultMeta, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };
+/**
+ * Enumerates a machine's decision and external-event branches to a bounded
+ * depth, model-free, and reports which states are reached and how each path
+ * terminates. At each decision request it forks one branch per candidate event
+ * (guard-rejected candidates are counted in `prunedByGuard`, not explored); at
+ * an idle wait it forks per externally-accepted event. A `agent.plan` request
+ * forks the same way — one branch per candidate, including the reserved
+ * `agent.plan.done` move — advancing each branch through the real plan protocol
+ * (`resolveAgentRequests`), so a plan can consume several depth units. Text/`userInput` invokes
+ * are resolved from `textOutputs` (a by-src canned-output map) — a missing src
+ * halts that branch with a `needs-output` terminal rather than throwing.
+ *
+ * Combinatorics are bounded by `maxDepth` (default 8) and `maxPaths` (default
+ * 200, reported via `hitPathCap`).
+ *
+ * @example
+ * ```ts
+ * const report = await explorePaths(refundMachine, { input: { request: 'x', amount: 5000 } });
+ * // report.terminals → both 'refunded' and 'denied'; report.prunedByGuard → 1
+ * ```
+ */
+declare function explorePaths(machine: AnyStateMachine, options?: ExplorePathsOptions): Promise<AgentPathReport>;
+/** The result of a {@link canReach} query. */
+interface CanReachResult {
+  canReach: boolean;
+  /** When reachable, the sequence of chosen/applied events that gets there. */
+  witness?: ChosenEvent[];
+}
+/**
+ * Answers "can the machine reach `statePath`?" by exploring its branches (a
+ * thin wrapper over {@link explorePaths}). Returns `{ canReach: true, witness }`
+ * with the event sequence that reaches it, or `{ canReach: false }`.
+ *
+ * @example
+ * ```ts
+ * const { canReach, witness } = await canReach(refundMachine, 'denied', { input: { request: 'x', amount: 5000 } });
+ * // canReach → true; witness → [{ type: 'NEEDS_REVIEW' }, { type: 'DENY' }]
+ * ```
+ */
+declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
+//#endregion
+export { type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentMachine, type AgentMachineConfig, type AgentMessage, type AgentMessageInfo, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, type AgentRequest, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunMeta, type AgentSchemaPack, type AgentSetupStateSchema, type AgentSnapshotStore, type AgentStateNarrowing, type AgentStateRequest, type AgentStep, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssertAgentMachineOptions, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type DecisionLogicConfig, EVENT_TOOL_PREFIX, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, type NormalizedEventSchemas, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type ProviderOptions, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assertAgentMachine, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };