@statelyai/agent 2.0.0-alpha.30 → 2.0.0-alpha.32

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, a as AgentToolDescriptor, b as ToolCallPart, c as AllowedEvents, d as EventUnion, f as FilePart, h as InferOutput, i as AgentToolChoice, l as AssistantMessage, m as InferInput, n as AgentMessage, o as AgentToolExecute, p as ImagePart, r as AgentTool, s as AgentTools, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-Dp5_Ru4R.cjs";
-import { $ as AgentTruncatedError, A as AgentDecisionExhaustedError, B as createDecisionLogic, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as CreateDecisionRequestOptions, G as AgentInvalidEventPayloadError, H as renderDecisionAttempts, I as DecisionAttempt, J as AgentSchemas, K as AgentRequestOptions, L as DecisionLogic, M as AgentDecisionOption, N as AgentDecisionRequest, O as providerOutputSchema, P as AgentExecutorDecisionRequest, Q as AgentError, R as DecisionLogicConfig, S as createTextLogic, T as getCallUsage, U as resolveDecision, V as createDecisionRequest, W as AgentEventDescriptor, X as getAcceptedEvents, Y as EventFromSnapshot, Z as parseAgentEvent, _ as TextLogic, a as AgentModelRef, b as TextLogicExecutor, c as AgentRequestExecutorInfo, f as AgentTextRequest, g as ProviderStructuredOutput, j as AgentDecisionInput, k as AgentDecisionExecutor, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, o as AgentOutputMode, p as AgentTextResult, q as AgentRequestSource, r as AgentFinishReason, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as ResolveDecisionOptions } from "./text-logic-DmciuVUQ.cjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-Cm_ovz9V.cjs";
-import { C as AgentInteractionEventMeta, D as getInteraction, E as eventFromInteraction, O as interactionMetaSchema, S as AgentInteractionEvent, T as GetInteractionOptions, _ as FromConfigResult, a as WithAgentUsageEvent, b as AgentInteractionChoice, c as setupAgent, d as AgentWorkflowConfig, f as AgentWorkflowInvokeConfig, g as FromConfigOptions, h as AgentWorkflowTransitionConfig, i as WithAgentEvents, l as AgentWorkflowActionConfig, m as AgentWorkflowStateConfig, n as AgentSchemaPack, o as createAgentSchemas, p as AgentWorkflowRequestConfig, r as AgentUsageEventPayload, s as getAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActorConfig, v as SchemaCompiler, w as AgentInteractionMeta, x as AgentInteractionDescriptor, y as AgentInteraction } from "./setup-agent-CLPCkXsu.cjs";
-import { C as runAgent, D as AgentRequest, E as traceTransitions, O as AgentStepRequest, S as isAgentIdle, T as serializeTraceEvent, _ as AgentTransitionHandler, a as AgentRunErrorCause, b as createAgentRuntime, c as AgentRunOptions, d as AgentRuntime, f as AgentRuntimeOptions, g as AgentTraceEvent, h as AgentTimerScheduler, i as AgentMaxModelCallsExceededError, l as AgentRunResult, m as AgentTimerEvent, n as AgentEffects, o as AgentRunInit, p as AgentSnapshotDivergedError, r as AgentInputFrom, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunStart, v as InspectedActorRef, w as runToQuiescence, x as inspectTransitions, y as JsonSerializableTraceEvent } from "./run-agent-CTlMc3Jb.cjs";
-import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-CLAC9q2Y.cjs";
+import { $ as AgentTruncatedError, A as AgentDecisionExhaustedError, B as createDecisionLogic, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as CreateDecisionRequestOptions, G as AgentInvalidEventPayloadError, H as renderDecisionAttempts, I as DecisionAttempt, J as AgentSchemas, K as AgentRequestOptions, L as DecisionLogic, M as AgentDecisionOption, N as AgentDecisionRequest, O as providerOutputSchema, P as AgentExecutorDecisionRequest, Q as AgentError, R as DecisionLogicConfig, S as createTextLogic, T as getCallUsage, U as resolveDecision, V as createDecisionRequest, W as AgentEventDescriptor, X as getAcceptedEvents, Y as EventFromSnapshot, Z as parseAgentEvent, _ as TextLogic, a as AgentModelRef, b as TextLogicExecutor, c as AgentRequestExecutorInfo, f as AgentTextRequest, g as ProviderStructuredOutput, j as AgentDecisionInput, k as AgentDecisionExecutor, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, o as AgentOutputMode, p as AgentTextResult, q as AgentRequestSource, r as AgentFinishReason, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as ResolveDecisionOptions } from "./text-logic-CYP502VT.cjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-DVw-646x.cjs";
+import { C as AgentInteractionEventMeta, D as getInteraction, E as eventFromInteraction, O as interactionMetaSchema, S as AgentInteractionEvent, T as GetInteractionOptions, _ as FromConfigResult, a as WithAgentUsageEvent, b as AgentInteractionChoice, c as setupAgent, d as AgentWorkflowConfig, f as AgentWorkflowInvokeConfig, g as FromConfigOptions, h as AgentWorkflowTransitionConfig, i as WithAgentEvents, l as AgentWorkflowActionConfig, m as AgentWorkflowStateConfig, n as AgentSchemaPack, o as createAgentSchemas, p as AgentWorkflowRequestConfig, r as AgentUsageEventPayload, s as getAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActorConfig, v as SchemaCompiler, w as AgentInteractionMeta, x as AgentInteractionDescriptor, y as AgentInteraction } from "./setup-agent-BiF1N3td.cjs";
+import { C as runAgent, D as AgentRequest, E as traceTransitions, O as AgentStepRequest, S as isAgentIdle, T as serializeTraceEvent, _ as AgentTransitionHandler, a as AgentRunErrorCause, b as createAgentRuntime, c as AgentRunOptions, d as AgentRuntime, f as AgentRuntimeOptions, g as AgentTraceEvent, h as AgentTimerScheduler, i as AgentMaxModelCallsExceededError, l as AgentRunResult, m as AgentTimerEvent, n as AgentEffects, o as AgentRunInit, p as AgentSnapshotDivergedError, r as AgentInputFrom, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunStart, v as InspectedActorRef, w as runToQuiescence, x as inspectTransitions, y as JsonSerializableTraceEvent } from "./run-agent-B5QhabdY.cjs";
+import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-s73r1Hxf.cjs";
 import { a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, u as systemMessage } from "./utils-ebVpCYoF.cjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
 //#region src/type-helpers.d.ts
@@ -84,9 +84,10 @@ interface DescribeMachineOptions {
  * label and description (`*` marks the active ones when `snapshot` is given),
  * and under it every transition leaving it, one per line: `on EVENT`,
  * `always`, `after <delay>`, invoke `done`/`error`, and `choice` branches,
- * each with its guard (`if …`), where it goes (`→ review`), and what it sets
- * in context (`sets draft, attempts`). An `Events` section lists the
- * machine's event schemas with their descriptions and fields.
+ * each with `(human)` when its `meta.actor` is `"human"`, its guard (`if …`),
+ * where it goes (`→ review`), and what it sets in context (`sets draft,
+ * attempts`). An `Events` section lists the machine's event schemas with their
+ * descriptions and fields.
  *
  * A transition written as a function shows the targets its source names
  * (`→ review (conditional)` when it may decline or pick among several),
@@ -143,7 +144,9 @@ interface DecideNextResult<TEvent = ChosenEvent> {
   /**
    * The candidates the snapshot rejected: every `allowedEvents` type × payload,
    * built the same way as the offered options, where `snapshot.can(event)` was
-   * false. Never offered to the model. Filled when nothing is offered too.
+   * false or the state handles the type through a transition tagged
+   * `meta: { actor: "human" }`. Never offered to the model. Filled when
+   * nothing is offered too.
    */
   withheld: ChosenEvent[];
 }
@@ -151,7 +154,8 @@ interface DecideNextResult<TEvent = ChosenEvent> {
  * Asks a model to choose the next event for ANY XState snapshot, including a
  * machine built with plain `createMachine`/`setup` that knows nothing about AI.
  * The candidates are the `allowedEvents` an active state handles, one option per
- * payload, kept only where `snapshot.can(event)` is true; the rest come back as
+ * payload, kept only where `snapshot.can(event)` is true and no transition
+ * tagged `meta: { actor: "human" }` handles the type; the rest come back as
  * `withheld`. Each option is
  * described from the transition's `description`, else the event schema's,
  * plus (with `lookahead`) what it changes. The chosen event must equal one
@@ -185,6 +189,50 @@ interface DecideNextResult<TEvent = ChosenEvent> {
  */
 export declare function decideNext<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, options: DecideNextOptions<TSnapshot>): Promise<DecideNextResult<EventFromSnapshot<TSnapshot>>>;
 //#endregion
+//#region src/policy-decider.d.ts
+/** Options for {@link createPolicyDecider}: everything {@link runAgent} takes for the policy run, except how the run opens. */
+interface PolicyDeciderOptions<TPolicy extends AnyStateMachine> extends Omit<AgentRunOptions<TPolicy>, "input" | "event" | "attempts" | "snapshot" | "events" | "onIdle" | "signal" | "threadId"> {
+  /**
+   * The `store` thread for one decision's policy run. Every decision, and every
+   * retry of one, needs its own thread: a thread that already has entries is
+   * resumed, so a shared one would return an earlier decision's choice. Default
+   * with a `store`: `policy:${info.callKey}:${hash}`, where `hash` is the
+   * SHA-256 of the policy input's canonical JSON. The call key is unique per
+   * call and attempt and stays the same when a crashed run re-issues the call;
+   * the hash keeps a machine that asks something else at the same call site
+   * after a version bridge, which keeps the call key, off the earlier thread. Required
+   * with a `store` when the decider is called without a `callKey`.
+   */
+  threadId?: (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => string;
+  /**
+   * Builds the policy's input from the decision request. Default:
+   * `{ facts: request.metadata?.facts, options, system: request.system, prompt: request.prompt }`,
+   * where `options` are the offered events (`request.options[].event`). The
+   * policy's input schema validates it.
+   */
+  input?: (request: AgentExecutorDecisionRequest) => InputFrom<TPolicy>;
+}
+/**
+ * Runs a policy machine as a decide executor: each decision request starts one
+ * run of `policy`, and its output is the chosen event. The policy can answer
+ * with a rule (a `choice` over the facts, no model call) and invoke
+ * `agent.decide` for the rest, answered by `options.executors`.
+ *
+ * The environment still judges the event: one it does not accept is retried
+ * like any other decider's choice. The policy's input must be JSON (it opens
+ * the policy run's event log): the default drops keys whose value is
+ * `undefined`, and any other value that is not JSON throws before the run. The policy's token usage is reported on the
+ * result, and left out when the policy made no model call. A run that does not
+ * end `done` with an event throws `AgentError` with code `policy-not-done`.
+ *
+ * @example
+ * ```ts no-check
+ * const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
+ * await runAgent(deskMachine, { input, executors: { ...modelExecutors, decide } });
+ * ```
+ */
+export declare function createPolicyDecider<TPolicy extends AnyStateMachine>(policy: TPolicy, options?: PolicyDeciderOptions<TPolicy>): AgentDecisionExecutor;
+//#endregion
 //#region src/provide-executors.d.ts
 /** Options for {@link provideExecutors}. */
 interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
@@ -253,4 +301,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  */
 export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
 //#endregion
-export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type OutputOf, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
+export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 import { C as UserMessage, S as ToolResultPart, _ as StandardSchemaV1, a as AgentToolDescriptor, b as ToolCallPart, c as AllowedEvents, d as EventUnion, f as FilePart, h as InferOutput, i as AgentToolChoice, l as AssistantMessage, m as InferInput, n as AgentMessage, o as AgentToolExecute, p as ImagePart, r as AgentTool, s as AgentTools, u as ChosenEvent, v as SystemMessage, x as ToolMessage, y as TextPart } from "./types-Dp5_Ru4R.mjs";
-import { $ as AgentTruncatedError, A as AgentDecisionExhaustedError, B as createDecisionLogic, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as CreateDecisionRequestOptions, G as AgentInvalidEventPayloadError, H as renderDecisionAttempts, I as DecisionAttempt, J as AgentSchemas, K as AgentRequestOptions, L as DecisionLogic, M as AgentDecisionOption, N as AgentDecisionRequest, O as providerOutputSchema, P as AgentExecutorDecisionRequest, Q as AgentError, R as DecisionLogicConfig, S as createTextLogic, T as getCallUsage, U as resolveDecision, V as createDecisionRequest, W as AgentEventDescriptor, X as getAcceptedEvents, Y as EventFromSnapshot, Z as parseAgentEvent, _ as TextLogic, a as AgentModelRef, b as TextLogicExecutor, c as AgentRequestExecutorInfo, f as AgentTextRequest, g as ProviderStructuredOutput, j as AgentDecisionInput, k as AgentDecisionExecutor, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, o as AgentOutputMode, p as AgentTextResult, q as AgentRequestSource, r as AgentFinishReason, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as ResolveDecisionOptions } from "./text-logic-BRYOPWvY.mjs";
-import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-BkM3z02Y.mjs";
-import { C as AgentInteractionEventMeta, D as getInteraction, E as eventFromInteraction, O as interactionMetaSchema, S as AgentInteractionEvent, T as GetInteractionOptions, _ as FromConfigResult, a as WithAgentUsageEvent, b as AgentInteractionChoice, c as setupAgent, d as AgentWorkflowConfig, f as AgentWorkflowInvokeConfig, g as FromConfigOptions, h as AgentWorkflowTransitionConfig, i as WithAgentEvents, l as AgentWorkflowActionConfig, m as AgentWorkflowStateConfig, n as AgentSchemaPack, o as createAgentSchemas, p as AgentWorkflowRequestConfig, r as AgentUsageEventPayload, s as getAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActorConfig, v as SchemaCompiler, w as AgentInteractionMeta, x as AgentInteractionDescriptor, y as AgentInteraction } from "./setup-agent-CGELn1qZ.mjs";
-import { C as runAgent, D as AgentRequest, E as traceTransitions, O as AgentStepRequest, S as isAgentIdle, T as serializeTraceEvent, _ as AgentTransitionHandler, a as AgentRunErrorCause, b as createAgentRuntime, c as AgentRunOptions, d as AgentRuntime, f as AgentRuntimeOptions, g as AgentTraceEvent, h as AgentTimerScheduler, i as AgentMaxModelCallsExceededError, l as AgentRunResult, m as AgentTimerEvent, n as AgentEffects, o as AgentRunInit, p as AgentSnapshotDivergedError, r as AgentInputFrom, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunStart, v as InspectedActorRef, w as runToQuiescence, x as inspectTransitions, y as JsonSerializableTraceEvent } from "./run-agent-CAVt5R-r.mjs";
-import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-CIIJohjj.mjs";
+import { $ as AgentTruncatedError, A as AgentDecisionExhaustedError, B as createDecisionLogic, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as CreateDecisionRequestOptions, G as AgentInvalidEventPayloadError, H as renderDecisionAttempts, I as DecisionAttempt, J as AgentSchemas, K as AgentRequestOptions, L as DecisionLogic, M as AgentDecisionOption, N as AgentDecisionRequest, O as providerOutputSchema, P as AgentExecutorDecisionRequest, Q as AgentError, R as DecisionLogicConfig, S as createTextLogic, T as getCallUsage, U as resolveDecision, V as createDecisionRequest, W as AgentEventDescriptor, X as getAcceptedEvents, Y as EventFromSnapshot, Z as parseAgentEvent, _ as TextLogic, a as AgentModelRef, b as TextLogicExecutor, c as AgentRequestExecutorInfo, f as AgentTextRequest, g as ProviderStructuredOutput, j as AgentDecisionInput, k as AgentDecisionExecutor, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, o as AgentOutputMode, p as AgentTextResult, q as AgentRequestSource, r as AgentFinishReason, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as ResolveDecisionOptions } from "./text-logic-DuK9HIFM.mjs";
+import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-D7JKAxLc.mjs";
+import { C as AgentInteractionEventMeta, D as getInteraction, E as eventFromInteraction, O as interactionMetaSchema, S as AgentInteractionEvent, T as GetInteractionOptions, _ as FromConfigResult, a as WithAgentUsageEvent, b as AgentInteractionChoice, c as setupAgent, d as AgentWorkflowConfig, f as AgentWorkflowInvokeConfig, g as FromConfigOptions, h as AgentWorkflowTransitionConfig, i as WithAgentEvents, l as AgentWorkflowActionConfig, m as AgentWorkflowStateConfig, n as AgentSchemaPack, o as createAgentSchemas, p as AgentWorkflowRequestConfig, r as AgentUsageEventPayload, s as getAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActorConfig, v as SchemaCompiler, w as AgentInteractionMeta, x as AgentInteractionDescriptor, y as AgentInteraction } from "./setup-agent-J9f_Wu5T.mjs";
+import { C as runAgent, D as AgentRequest, E as traceTransitions, O as AgentStepRequest, S as isAgentIdle, T as serializeTraceEvent, _ as AgentTransitionHandler, a as AgentRunErrorCause, b as createAgentRuntime, c as AgentRunOptions, d as AgentRuntime, f as AgentRuntimeOptions, g as AgentTraceEvent, h as AgentTimerScheduler, i as AgentMaxModelCallsExceededError, l as AgentRunResult, m as AgentTimerEvent, n as AgentEffects, o as AgentRunInit, p as AgentSnapshotDivergedError, r as AgentInputFrom, s as AgentRunMeta, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunStart, v as InspectedActorRef, w as runToQuiescence, x as inspectTransitions, y as JsonSerializableTraceEvent } from "./run-agent-Atu-wEk7.mjs";
+import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-C2NjVlWU.mjs";
 import { a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, u as systemMessage } from "./utils-BnXdWih3.mjs";
 import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
 //#region src/type-helpers.d.ts
@@ -84,9 +84,10 @@ interface DescribeMachineOptions {
  * label and description (`*` marks the active ones when `snapshot` is given),
  * and under it every transition leaving it, one per line: `on EVENT`,
  * `always`, `after <delay>`, invoke `done`/`error`, and `choice` branches,
- * each with its guard (`if …`), where it goes (`→ review`), and what it sets
- * in context (`sets draft, attempts`). An `Events` section lists the
- * machine's event schemas with their descriptions and fields.
+ * each with `(human)` when its `meta.actor` is `"human"`, its guard (`if …`),
+ * where it goes (`→ review`), and what it sets in context (`sets draft,
+ * attempts`). An `Events` section lists the machine's event schemas with their
+ * descriptions and fields.
  *
  * A transition written as a function shows the targets its source names
  * (`→ review (conditional)` when it may decline or pick among several),
@@ -143,7 +144,9 @@ interface DecideNextResult<TEvent = ChosenEvent> {
   /**
    * The candidates the snapshot rejected: every `allowedEvents` type × payload,
    * built the same way as the offered options, where `snapshot.can(event)` was
-   * false. Never offered to the model. Filled when nothing is offered too.
+   * false or the state handles the type through a transition tagged
+   * `meta: { actor: "human" }`. Never offered to the model. Filled when
+   * nothing is offered too.
    */
   withheld: ChosenEvent[];
 }
@@ -151,7 +154,8 @@ interface DecideNextResult<TEvent = ChosenEvent> {
  * Asks a model to choose the next event for ANY XState snapshot, including a
  * machine built with plain `createMachine`/`setup` that knows nothing about AI.
  * The candidates are the `allowedEvents` an active state handles, one option per
- * payload, kept only where `snapshot.can(event)` is true; the rest come back as
+ * payload, kept only where `snapshot.can(event)` is true and no transition
+ * tagged `meta: { actor: "human" }` handles the type; the rest come back as
  * `withheld`. Each option is
  * described from the transition's `description`, else the event schema's,
  * plus (with `lookahead`) what it changes. The chosen event must equal one
@@ -185,6 +189,50 @@ interface DecideNextResult<TEvent = ChosenEvent> {
  */
 export declare function decideNext<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, options: DecideNextOptions<TSnapshot>): Promise<DecideNextResult<EventFromSnapshot<TSnapshot>>>;
 //#endregion
+//#region src/policy-decider.d.ts
+/** Options for {@link createPolicyDecider}: everything {@link runAgent} takes for the policy run, except how the run opens. */
+interface PolicyDeciderOptions<TPolicy extends AnyStateMachine> extends Omit<AgentRunOptions<TPolicy>, "input" | "event" | "attempts" | "snapshot" | "events" | "onIdle" | "signal" | "threadId"> {
+  /**
+   * The `store` thread for one decision's policy run. Every decision, and every
+   * retry of one, needs its own thread: a thread that already has entries is
+   * resumed, so a shared one would return an earlier decision's choice. Default
+   * with a `store`: `policy:${info.callKey}:${hash}`, where `hash` is the
+   * SHA-256 of the policy input's canonical JSON. The call key is unique per
+   * call and attempt and stays the same when a crashed run re-issues the call;
+   * the hash keeps a machine that asks something else at the same call site
+   * after a version bridge, which keeps the call key, off the earlier thread. Required
+   * with a `store` when the decider is called without a `callKey`.
+   */
+  threadId?: (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => string;
+  /**
+   * Builds the policy's input from the decision request. Default:
+   * `{ facts: request.metadata?.facts, options, system: request.system, prompt: request.prompt }`,
+   * where `options` are the offered events (`request.options[].event`). The
+   * policy's input schema validates it.
+   */
+  input?: (request: AgentExecutorDecisionRequest) => InputFrom<TPolicy>;
+}
+/**
+ * Runs a policy machine as a decide executor: each decision request starts one
+ * run of `policy`, and its output is the chosen event. The policy can answer
+ * with a rule (a `choice` over the facts, no model call) and invoke
+ * `agent.decide` for the rest, answered by `options.executors`.
+ *
+ * The environment still judges the event: one it does not accept is retried
+ * like any other decider's choice. The policy's input must be JSON (it opens
+ * the policy run's event log): the default drops keys whose value is
+ * `undefined`, and any other value that is not JSON throws before the run. The policy's token usage is reported on the
+ * result, and left out when the policy made no model call. A run that does not
+ * end `done` with an event throws `AgentError` with code `policy-not-done`.
+ *
+ * @example
+ * ```ts no-check
+ * const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
+ * await runAgent(deskMachine, { input, executors: { ...modelExecutors, decide } });
+ * ```
+ */
+export declare function createPolicyDecider<TPolicy extends AnyStateMachine>(policy: TPolicy, options?: PolicyDeciderOptions<TPolicy>): AgentDecisionExecutor;
+//#endregion
 //#region src/provide-executors.d.ts
 /** Options for {@link provideExecutors}. */
 interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
@@ -253,4 +301,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
  */
 export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
 //#endregion
-export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type OutputOf, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
+export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };

package/dist/index.mjs

@@ -1,8 +1,8 @@
-import { $ as getStateMeta, A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, H as getAgentExecutionOptions, I as parseOutput, L as parseProviderOutput, M as getCallFinishReason, N as getCallUsage, O as bindRequestExecutor, P as isTextLogic, Q as getMessageText, R as providerOutputSchema, V as executorBoundLogics, X as getJsonSchemaSync, Y as getJsonSchema, Z as getMachineStructuralHash, at as userMessage, ct as AgentTruncatedError, et as getStatePath, i as AgentMachineVersionMismatchError, it as toolMessage, j as getAgentOutputMode, q as assistantMessage, rt as systemMessage, st as AgentError, tt as isStandardSchema, u as canonicalEventJson } from "./event-log-DJCMHek_.mjs";
-import { a as createDecisionRequest, c as renderDecisionAttempts, d as getAcceptedEvents, f as isEventPattern, i as createDecisionLogic, l as resolveDecision, m as isRecord, p as parseAgentEvent, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as AgentInvalidEventPayloadError } from "./decision-BHkvuImD.mjs";
-import { n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-7rV_cujV.mjs";
-import { t as AgentEventLogConflictError } from "./event-log-store-DsP6GCRh.mjs";
-import { a as bindDecisionForProvide, c as getConfiguredInvokeSrcs, d as isStateMachineLogic, f as runAgent, h as traceTransitions, i as bindChildMachineForProvide, l as inspectTransitions, m as serializeTraceEvent, n as AgentMaxModelCallsExceededError, o as bindTextForProvide, p as runToQuiescence, r as AgentSnapshotDivergedError, s as createAgentRuntime, t as AGENT_TRACE_SCHEMA_VERSION, u as isAgentIdle } from "./run-agent-BpHqkaZw.mjs";
+import { $ as getStateMeta, A as createTextLogic, C as AGENT_USAGE_EVENT_TYPE, H as getAgentExecutionOptions, I as parseOutput, L as parseProviderOutput, M as getCallFinishReason, N as getCallUsage, O as bindRequestExecutor, P as isTextLogic, Q as getMessageText, R as providerOutputSchema, V as executorBoundLogics, X as getJsonSchemaSync, Y as getJsonSchema, Z as getMachineStructuralHash, at as userMessage, dt as AgentTruncatedError, et as getStatePath, i as AgentMachineVersionMismatchError, it as toolMessage, j as getAgentOutputMode, l as assertJsonSerializable, lt as isRecord, q as assistantMessage, rt as systemMessage, tt as isStandardSchema, u as canonicalEventJson, ut as AgentError } from "./event-log-DAqsalT1.mjs";
+import { a as createDecisionRequest, c as renderDecisionAttempts, d as getAcceptedEvents, f as getHumanEventTypes, i as createDecisionLogic, l as resolveDecision, m as parseAgentEvent, p as isEventPattern, s as isDecisionLogic, t as AgentDecisionExhaustedError, u as AgentInvalidEventPayloadError } from "./decision-CV7WiV5C.mjs";
+import { n as getAgentSchemas, r as setupAgent, t as createAgentSchemas } from "./setup-agent-CmhB-U5P.mjs";
+import { t as AgentEventLogConflictError } from "./event-log-store-BGehvVTb.mjs";
+import { a as bindDecisionForProvide, c as getConfiguredInvokeSrcs, d as isStateMachineLogic, f as runAgent, h as traceTransitions, i as bindChildMachineForProvide, l as inspectTransitions, m as serializeTraceEvent, n as AgentMaxModelCallsExceededError, o as bindTextForProvide, p as runToQuiescence, r as AgentSnapshotDivergedError, s as createAgentRuntime, t as AGENT_TRACE_SCHEMA_VERSION, u as isAgentIdle } from "./run-agent-2UnSUhDb.mjs";
 import { getNextTransitions, machineToJSON, transition } from "xstate";
 //#region src/messages.ts
 const KNOWN_PART_TYPES = /* @__PURE__ */ new Set([
@@ -167,7 +167,8 @@ function validateChoice(value, path) {
 * reads: an object whose optional `interaction` declares a `label` (a string
 * with `{context.path}` interpolation, or a function of the context), an
 * `events` map of choices, payload `choices` (an array, or a context path to
-* one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers. This is
+* one), and a `textEvent` (a type, or `{ type, field }`) for free-text answers; and
+* an optional `actor: "human"`, which tags a transition as sent by a person. This is
 * the default `meta` type `setupAgent` gives a machine; pass it to
 * `createAgentSchemas({ meta: interactionMetaSchema })` only when building a
 * schema pack by hand.
@@ -177,6 +178,8 @@ const interactionMetaSchema = { "~standard": {
 	vendor: "statelyai-agent",
 	validate(value) {
 		if (!value || typeof value !== "object" || Array.isArray(value)) return { issues: [{ message: "Expected a state meta object" }] };
+		const actor = value["actor"];
+		if (actor !== void 0 && actor !== "human") return { issues: [issue("Expected \"human\"", ["actor"])] };
 		const interaction = value["interaction"];
 		if (interaction === void 0) return { value };
 		if (!interaction || typeof interaction !== "object" || Array.isArray(interaction)) return { issues: [issue("Expected an interaction descriptor object", ["interaction"])] };
@@ -459,10 +462,36 @@ function guardText(guard) {
 */
 const mayDecline = (code) => /\bundefined\b|\bnull\b|\bvoid 0\b|\breturn\s*;|\bif\s*\(|(?<!\?)\?(?![.?])|&&/.test(code.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, "\"\""));
 /**
+* True when the function returns a call's result (`=> next(ctx)`, `return
+* pick(x)`), so its target is not in its own source. Reads only the
+* function's own returned expressions, not those of callbacks nested in it.
+*/
+function returnsCall(code) {
+	const text = code.replace(/(["'`])(?:\\.|(?!\1)[^\\])*\1/g, "\"\"");
+	const startsWithCall = (at) => /^[\s(]*[A-Za-z_$][\w$.]*\s*\(/.test(text.slice(at));
+	let parens = 0;
+	let body = -1;
+	for (let i = 0; i < text.length && body < 0; i++) {
+		const char = text[i];
+		if (char === "(") parens++;
+		else if (char === ")") parens--;
+		else if (parens === 0 && char === "=" && text[i + 1] === ">") body = i + 2;
+		else if (parens === 0 && char === "{") body = i;
+	}
+	if (body < 0) return false;
+	while (/\s/.test(text[body] ?? "")) body++;
+	if (text[body] !== "{") return startsWithCall(body);
+	let depth = 0;
+	for (let i = body; i < text.length; i++) if (text[i] === "{") depth++;
+	else if (text[i] === "}" && --depth === 0) return false;
+	else if (depth === 1 && text.startsWith("return", i) && !/[\w$]/.test(text[i - 1] ?? "") && !/[\w$]/.test(text[i + 6] ?? "") && startsWithCall(i + 6)) return true;
+	return false;
+}
+/**
 * Where a transition written as a function goes: every string literal after a
 * `target:` that names a real state node, `(conditional)` when it may decline
 * or pick among several, `(stays)` when its source has no `target`, `?` when
-* it names none that resolves.
+* it names none that resolves or returns a helper call's result.
 */
 function targetsInSource(source, code, choice) {
 	const found = /* @__PURE__ */ new Set();
@@ -475,14 +504,15 @@ function targetsInSource(source, code, choice) {
 		const conditional = names.length > 1 || !choice && mayDecline(code);
 		return `${names.join(", ")}${conditional ? " (conditional)" : ""}`;
 	}
-	return /\btarget\s*:/.test(code) ? "?" : "(stays)";
+	return /\btarget\s*:/.test(code) || returnsCall(code) ? "?" : "(stays)";
 }
-/** One transition, as a line: `on GO if context.ready → review; sets draft — description`. */
+/** One transition, as a line: `on GO (human) if context.ready → review; sets draft — description`. */
 function transitionLine(source, head, transition, options = {}) {
 	const code = codeOf(transition);
 	let to;
 	let guard;
 	let description;
+	let human = false;
 	let sets;
 	if (typeof transition === "string") {
 		const node = resolveTarget(source, transition);
@@ -499,12 +529,13 @@ function transitionLine(source, head, transition, options = {}) {
 		}).join(", ") : "(stays)";
 		guard = guardText(transition[options.guardKey ?? "guard"]);
 		description = typeof transition.description === "string" ? transition.description : void 0;
+		human = isObject(transition.meta) && transition.meta.actor === "human";
 		sets = contextKeys(transition, void 0);
 	} else {
 		to = "?";
 		sets = [];
 	}
-	return `${head}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` — ${oneLine(description)}` : ""}`;
+	return `${head}${human ? " (human)" : ""}${guard ? ` if ${guard}` : ""} → ${to}${sets.length ? `; sets ${sets.join(", ")}` : ""}${description ? ` — ${oneLine(description)}` : ""}`;
 }
 function formatMs(ms) {
 	if (ms < 1e3) return `${ms}ms`;
@@ -551,7 +582,7 @@ function stateLine(node, json) {
 	else if (node.type === "compound" && typeof json.initial === "string") marker = ` (initial: ${json.initial})`;
 	const tags = node.tags.length ? ` [tags: ${node.tags.join(", ")}]` : "";
 	const interaction = node.meta?.interaction;
-	const label = typeof interaction?.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : "";
+	const label = !interaction ? "" : typeof interaction.label === "string" ? ` [interaction: "${oneLine(interaction.label)}"]` : typeof interaction.label === "function" ? " [interaction: computed label]" : " [interaction]";
 	const description = node.description ? ` — ${oneLine(node.description)}` : "";
 	return `${node.key}${marker}${tags}${label}${description}`;
 }
@@ -588,9 +619,10 @@ function eventLines(machine) {
 * label and description (`*` marks the active ones when `snapshot` is given),
 * and under it every transition leaving it, one per line: `on EVENT`,
 * `always`, `after <delay>`, invoke `done`/`error`, and `choice` branches,
-* each with its guard (`if …`), where it goes (`→ review`), and what it sets
-* in context (`sets draft, attempts`). An `Events` section lists the
-* machine's event schemas with their descriptions and fields.
+* each with `(human)` when its `meta.actor` is `"human"`, its guard (`if …`),
+* where it goes (`→ review`), and what it sets in context (`sets draft,
+* attempts`). An `Events` section lists the machine's event schemas with their
+* descriptions and fields.
 *
 * A transition written as a function shows the targets its source names
 * (`→ review (conditional)` when it may decline or pick among several),
@@ -634,7 +666,8 @@ function describeMachine(machine, options = {}) {
 * Asks a model to choose the next event for ANY XState snapshot, including a
 * machine built with plain `createMachine`/`setup` that knows nothing about AI.
 * The candidates are the `allowedEvents` an active state handles, one option per
-* payload, kept only where `snapshot.can(event)` is true; the rest come back as
+* payload, kept only where `snapshot.can(event)` is true and no transition
+* tagged `meta: { actor: "human" }` handles the type; the rest come back as
 * `withheld`. Each option is
 * described from the transition's `description`, else the event schema's,
 * plus (with `lookahead`) what it changes. The chosen event must equal one
@@ -669,19 +702,21 @@ function describeMachine(machine, options = {}) {
 async function decideNext(snapshot, options) {
 	const patterns = typeof options.allowedEvents === "string" ? [options.allowedEvents] : options.allowedEvents;
 	const schemas = snapshot.machine.schemas?.events;
-	const events = getAcceptedEvents(snapshot, {
+	const candidates = getAcceptedEvents(snapshot, {
 		events: schemas,
 		eventTypes: patterns
 	}).filter((event) => !isEventPattern(event.type));
+	const humanEventTypes = getHumanEventTypes(snapshot);
+	const events = candidates.filter((event) => !humanEventTypes.has(event.type));
 	const payloads = options.payloads?.(snapshot) ?? {};
 	const accepted = [];
 	const withheld = [];
-	for (const { type } of events) for (const payload of payloads[type] ?? [{}]) {
+	for (const { type } of candidates) for (const payload of payloads[type] ?? [{}]) {
 		const event = {
 			...payload,
 			type
 		};
-		(safeCan(snapshot, event) ? accepted : withheld).push(event);
+		(!humanEventTypes.has(type) && safeCan(snapshot, event) ? accepted : withheld).push(event);
 	}
 	const offered = accepted.map((event) => ({
 		event,
@@ -771,6 +806,78 @@ function short(value, max = 60) {
 	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 //#endregion
+//#region src/policy-decider.ts
+/**
+* Runs a policy machine as a decide executor: each decision request starts one
+* run of `policy`, and its output is the chosen event. The policy can answer
+* with a rule (a `choice` over the facts, no model call) and invoke
+* `agent.decide` for the rest, answered by `options.executors`.
+*
+* The environment still judges the event: one it does not accept is retried
+* like any other decider's choice. The policy's input must be JSON (it opens
+* the policy run's event log): the default drops keys whose value is
+* `undefined`, and any other value that is not JSON throws before the run. The policy's token usage is reported on the
+* result, and left out when the policy made no model call. A run that does not
+* end `done` with an event throws `AgentError` with code `policy-not-done`.
+*
+* @example
+* ```ts no-check
+* const decide = createPolicyDecider(policyMachine, { executors: modelExecutors });
+* await runAgent(deskMachine, { input, executors: { ...modelExecutors, decide } });
+* ```
+*/
+function createPolicyDecider(policy, options = {}) {
+	const { input = defaultInput, threadId, ...runOptions } = options;
+	const id = policy.config.id ?? policy.id;
+	return async (request, info) => {
+		const policyInput = input(request);
+		assertJsonSerializable(policyInput, "policy input");
+		const thread = runOptions.store === void 0 ? void 0 : await policyThread(request, policyInput, info);
+		const result = await runAgent(policy, {
+			...runOptions,
+			input: policyInput,
+			...thread === void 0 ? {} : { threadId: thread },
+			...info?.signal ? { signal: info.signal } : {}
+		});
+		if (result.status !== "done") {
+			const why = result.status === "error" ? `: ${String(result.error)}` : "";
+			throw new AgentError("policy-not-done", `policy '${id}' settled '${result.status}'${why}`, { cause: result.status === "error" ? result.error : void 0 });
+		}
+		const event = result.output;
+		if (!isRecord(event) || typeof event.type !== "string") throw new AgentError("policy-not-done", `policy '${id}' output is not an event: ${JSON.stringify(event)}`);
+		const { modelCalls, ...usage } = result.usage;
+		return {
+			event,
+			...modelCalls > 0 ? { usage } : {}
+		};
+	};
+	async function policyThread(request, policyInput, info) {
+		if (threadId) return threadId(request, info);
+		if (info?.callKey) return `policy:${info.callKey}:${await sha256(canonicalEventJson(policyInput))}`;
+		throw new AgentError("missing-thread-id", `policy '${id}' has a store but no threadId, and the decision came with no callKey to derive one from`);
+	}
+}
+function defaultInput(request) {
+	const facts = request.metadata?.facts;
+	return withoutUndefinedKeys({
+		facts,
+		options: (request.options ?? []).map((option) => option.event),
+		system: request.system,
+		prompt: request.prompt
+	});
+}
+/** A copy of `value` with every object key whose value is `undefined` removed, at any depth. */
+function withoutUndefinedKeys(value) {
+	if (Array.isArray(value)) return value.map(withoutUndefinedKeys);
+	if (!isRecord(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return value;
+	return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, withoutUndefinedKeys(child)]));
+}
+/** Hex SHA-256 of `text`, with Web Crypto (Node, browsers, workers). */
+async function sha256(text) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
 //#region src/provide-executors.ts
 /**
 * Binds a machine's agent actor sources to a set of host `executors` in one
@@ -884,4 +991,4 @@ function missingExecutorError(src, kind, executor) {
 	return /* @__PURE__ */ new Error(`provideExecutors: actor source '${src}' is a ${kind} source but no '${executor}' executor was provided. Add it to the executors object, or bind the source with its own executor (logic.withExecutor(...)) before calling provideExecutors.`);
 }
 //#endregion
-export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentInvalidEventPayloadError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentSnapshotDivergedError, AgentTruncatedError, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, decideNext, describeMachine, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, messagesSchema, parseAgentEvent, parseOutput, parseProviderOutput, provideExecutors, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
+export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, AgentDecisionExhaustedError, AgentError, AgentEventLogConflictError, AgentInvalidEventPayloadError, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, AgentSnapshotDivergedError, AgentTruncatedError, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createPolicyDecider, createTextLogic, decideNext, describeMachine, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isAgentMessages, isStandardSchema, messagesSchema, parseAgentEvent, parseOutput, parseProviderOutput, provideExecutors, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };

package/dist/log.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_log = require("./event-log-BZRfBRd7.cjs");
-const require_event_log_store = require("./event-log-store-DZR4IIWe.cjs");
+const require_event_log = require("./event-log-CKWeC7H-.cjs");
+const require_event_log_store = require("./event-log-store-DKyE7JKr.cjs");
 //#region src/event-log-store-conformance.ts
 /**
 * The runner-agnostic conformance suite for {@link AgentEventLogStore}
@@ -30,8 +30,11 @@ function entry(index, type, metadata) {
 		...metadata !== void 0 ? { metadata } : {}
 	};
 }
+function initFixture(executionId = "exec-src") {
+	return entry(0, require_event_log.AGENT_INIT_EVENT_TYPE, { executionId });
+}
 function entriesFrom(start, count) {
-	return Array.from({ length: count }, (_unused, i) => entry(start + i, `e${start + i}`));
+	return Array.from({ length: count }, (_unused, i) => start + i === 0 ? initFixture() : entry(start + i, `e${start + i}`));
 }
 function assertJsonEqual(actual, expected, message) {
 	const a = JSON.stringify(actual);
@@ -281,10 +284,42 @@ const cases = [
 				expectedIndex: 1,
 				entries: [entry(1, "branch")]
 			});
-			assertJsonEqual((await store.read("fork-1")).map((e) => e.event.type), ["e0", "branch"], "a forked thread must append independently from its copied length");
+			assertJsonEqual((await store.read("fork-1")).map((e) => e.event.type), [require_event_log.AGENT_INIT_EVENT_TYPE, "branch"], "a forked thread must append independently from its copied length");
 			if (await store.length("src") !== 3) fail("appending to a fork must not touch the source thread");
 		}
 	},
+	{
+		name: "a fork is its own lineage: a fresh executionId, and forkedFrom naming the parent",
+		async run(create) {
+			const store = await create();
+			const source = entriesFrom(0, 3);
+			await store.append({
+				threadId: "src",
+				expectedIndex: 0,
+				entries: source
+			});
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-a",
+				upToIndex: 2
+			});
+			await store.fork({
+				threadId: "src",
+				newThreadId: "fork-b",
+				upToIndex: 2
+			});
+			const [a, b] = [await store.read("fork-a"), await store.read("fork-b")];
+			const ids = [require_event_log.getLogExecutionId(a), require_event_log.getLogExecutionId(b)];
+			if (typeof ids[0] !== "string" || typeof ids[1] !== "string") fail("a fork's init entry must carry a string metadata.executionId");
+			if (ids.includes("exec-src") || ids[0] === ids[1]) fail("every fork must mint its own executionId, not reuse the parent's or a sibling's");
+			assertJsonEqual(a[0].metadata?.forkedFrom, {
+				executionId: "exec-src",
+				logIndex: 2
+			}, "a fork's init entry must record forkedFrom: { executionId, logIndex }");
+			assertJsonEqual(a.slice(1), source.slice(1, 2), "a fork must copy every entry after the init entry unchanged");
+			assertJsonEqual(await store.read("src"), source, "forking must not touch the source thread");
+		}
+	},
 	{
 		name: "fork rejects a non-empty target, an unknown source, and an out-of-range cutoff (0 included)",
 		async run(create) {
@@ -357,7 +392,7 @@ const cases = [
 			]) await store.append({
 				threadId,
 				expectedIndex: 0,
-				entries: [entry(0, "start")]
+				entries: [initFixture()]
 			});
 			await store.fork({
 				threadId: "user:a",

package/dist/log.d.cts

@@ -1,4 +1,4 @@
-import { A as rebindActorSession, C as createReplayEntry, D as getSnapshotStateHash, E as getLogExecutionId, M as replay, N as validateReplayEntries, O as getUsageFromEvents, S as assertJsonSerializable, T as getDecisionAttempts, _ as NonSerializableAgentEventError, a as AGENT_INIT_EVENT_TYPE, b as agentCallOccurrence, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as LogRecorder, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, j as recordLog, k as initEntry, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayOptions, w as forkEventLog, x as assertAgentLogEntry, y as ReplayResult } from "./event-log-store-CLAC9q2Y.cjs";
+import { A as rebindActorSession, C as createReplayEntry, D as getSnapshotStateHash, E as getLogExecutionId, M as replay, N as validateReplayEntries, O as getUsageFromEvents, S as assertJsonSerializable, T as getDecisionAttempts, _ as NonSerializableAgentEventError, a as AGENT_INIT_EVENT_TYPE, b as agentCallOccurrence, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as LogRecorder, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, j as recordLog, k as initEntry, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayOptions, w as forkEventLog, x as assertAgentLogEntry, y as ReplayResult } from "./event-log-store-s73r1Hxf.cjs";
 //#region src/event-log-store-conformance.d.ts
 /** Produces a fresh, empty store for one case. */
 type CreateStore = () => Promise<AgentEventLogStore> | AgentEventLogStore;

package/dist/log.d.mts

@@ -1,4 +1,4 @@
-import { A as rebindActorSession, C as createReplayEntry, D as getSnapshotStateHash, E as getLogExecutionId, M as replay, N as validateReplayEntries, O as getUsageFromEvents, S as assertJsonSerializable, T as getDecisionAttempts, _ as NonSerializableAgentEventError, a as AGENT_INIT_EVENT_TYPE, b as agentCallOccurrence, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as LogRecorder, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, j as recordLog, k as initEntry, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayOptions, w as forkEventLog, x as assertAgentLogEntry, y as ReplayResult } from "./event-log-store-CIIJohjj.mjs";
+import { A as rebindActorSession, C as createReplayEntry, D as getSnapshotStateHash, E as getLogExecutionId, M as replay, N as validateReplayEntries, O as getUsageFromEvents, S as assertJsonSerializable, T as getDecisionAttempts, _ as NonSerializableAgentEventError, a as AGENT_INIT_EVENT_TYPE, b as agentCallOccurrence, c as AgentLogEntry, d as AgentMachineVersionMismatchError, f as AgentPersistedSnapshot, g as LogRecorder, h as JsonValue, i as AGENT_EVENT_SCHEMA_VERSION, j as recordLog, k as initEntry, l as AgentLogInit, m as CreateReplayEntryOptions, n as AgentEventLogStore, o as AgentEventLogError, p as AgentReplayDivergenceError, r as createInMemoryEventLogStore, s as AgentInitEvent, t as AgentEventLogConflictError, u as AgentLogVerification, v as ReplayOptions, w as forkEventLog, x as assertAgentLogEntry, y as ReplayResult } from "./event-log-store-C2NjVlWU.mjs";
 //#region src/event-log-store-conformance.d.ts
 /** Produces a fresh, empty store for one case. */
 type CreateStore = () => Promise<AgentEventLogStore> | AgentEventLogStore;