@statelyai/agent 2.0.0-alpha.16 → 2.0.0-alpha.17

package/dist/ai-sdk.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_decision = require("./decision-Ba8qrT8r.cjs");
+const require_decision = require("./decision-DnQCQPew.cjs");
 let ai = require("ai");
 //#region src/ai-sdk/mappers.ts
 /**

package/dist/ai-sdk.mjs

@@ -1,4 +1,4 @@
-import { H as isStandardSchema, _ as getAgentOutputMode, i as renderDecisionAttempts, p as buildEnvelopeSchema } from "./decision-Bt2HYYRo.mjs";
+import { H as isStandardSchema, _ as getAgentOutputMode, i as renderDecisionAttempts, p as buildEnvelopeSchema } from "./decision-C11xuud2.mjs";
 import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText, tool } from "ai";
 //#region src/ai-sdk/mappers.ts
 /**

package/dist/{decision-Bt2HYYRo.mjs → decision-C11xuud2.mjs}

@@ -232,9 +232,10 @@ const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
 * object. `config` is shared by reference across `machine.provide(...)` (unlike
 * the machine object itself), so a predicate registered here travels with the
 * machine through `.provide` — which is why it is keyed on `config`, not the
-* machine. Set by `setupAgent({ isSuspended })` in `createMachine`, read by
-* `runAgent` (below the host `options.isSuspended` override, above the timing
-* heuristic).
+* machine. Set by `setupAgent({ isSuspended })` in `createMachine` and by
+* `setupAgent.fromConfig` (its `isSuspended` option or the config's
+* `suspendedTags`), read by `runAgent` (below the host `options.isSuspended`
+* override, above the timing heuristic).
 */
 const machineSuspensionPredicates = /* @__PURE__ */ new WeakMap();
 /** Reads the {@link machineSuspensionPredicates} predicate carried by `machine` (via its root `config`), if any. */

package/dist/{decision-Ba8qrT8r.cjs → decision-DnQCQPew.cjs}

@@ -232,9 +232,10 @@ const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
 * object. `config` is shared by reference across `machine.provide(...)` (unlike
 * the machine object itself), so a predicate registered here travels with the
 * machine through `.provide` — which is why it is keyed on `config`, not the
-* machine. Set by `setupAgent({ isSuspended })` in `createMachine`, read by
-* `runAgent` (below the host `options.isSuspended` override, above the timing
-* heuristic).
+* machine. Set by `setupAgent({ isSuspended })` in `createMachine` and by
+* `setupAgent.fromConfig` (its `isSuspended` option or the config's
+* `suspendedTags`), read by `runAgent` (below the host `options.isSuspended`
+* override, above the timing heuristic).
 */
 const machineSuspensionPredicates = /* @__PURE__ */ new WeakMap();
 /** Reads the {@link machineSuspensionPredicates} predicate carried by `machine` (via its root `config`), if any. */

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_errors = require("./errors-DUBBzRLP.cjs");
-const require_setup_agent = require("./setup-agent-BLU77gqr.cjs");
-const require_decision = require("./decision-Ba8qrT8r.cjs");
+const require_setup_agent = require("./setup-agent-D_EyJ0Ik.cjs");
+const require_decision = require("./decision-DnQCQPew.cjs");
 const require_event_log_store = require("./event-log-store-yquOV1TX.cjs");
 let xstate = require("xstate");
 //#region src/internal/state-request-pass.ts

package/dist/index.d.cts

@@ -96,6 +96,17 @@ interface AgentWorkflowConfig {
   actors?: Record<string, AgentWorkflowActorConfig>;
   initial: string;
   states: Record<string, AgentWorkflowStateConfig>;
+  /**
+   * State tags that mark an INTENTIONAL wait for an external event (a human
+   * approval, an inbound webhook, …) — the declarative form of `setupAgent({
+   * isSuspended })`, since a config cannot carry a function. Lowered to a
+   * `snapshot.hasTag(...)`-any-of predicate so `runAgent` settles those
+   * snapshots idle deterministically instead of using its timing heuristic.
+   * Every listed tag must appear in some state's `tags` — an unused tag is a
+   * build-time error. A `fromConfig(config, { isSuspended })` option takes
+   * precedence; a `runAgent({ isSuspended })` host override beats both.
+   */
+  suspendedTags?: string[];
   meta?: Record<string, unknown>;
 }
 /** A `requests` entry in {@link AgentWorkflowConfig} — the JSON equivalent of a `setupAgent({ requests })` `TextLogicConfig`. Fields beyond `input`/`output`/`tools`/`mode`/`description` are `unknown` because they accept template-expression strings (see {@link AgentWorkflowConfig}). */
@@ -228,6 +239,16 @@ interface FromConfigOptions {
    * implementation here is a build-time error.
    */
   actions?: Record<string, (params: any) => unknown>;
+  /**
+   * Detects a snapshot that is an INTENTIONAL wait for an external event —
+   * the same machine-carried predicate `setupAgent({ isSuspended })` declares
+   * for TS-authored machines, registered here because a function cannot live
+   * in the workflow config itself. Takes precedence over the config's
+   * declarative {@link AgentWorkflowConfig.suspendedTags}; a
+   * `runAgent({ isSuspended })` host override beats both. Travels with the
+   * machine through `machine.provide(...)`.
+   */
+  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
 }
 //#endregion
 //#region src/setup-agent.d.ts

package/dist/index.d.mts

@@ -96,6 +96,17 @@ interface AgentWorkflowConfig {
   actors?: Record<string, AgentWorkflowActorConfig>;
   initial: string;
   states: Record<string, AgentWorkflowStateConfig>;
+  /**
+   * State tags that mark an INTENTIONAL wait for an external event (a human
+   * approval, an inbound webhook, …) — the declarative form of `setupAgent({
+   * isSuspended })`, since a config cannot carry a function. Lowered to a
+   * `snapshot.hasTag(...)`-any-of predicate so `runAgent` settles those
+   * snapshots idle deterministically instead of using its timing heuristic.
+   * Every listed tag must appear in some state's `tags` — an unused tag is a
+   * build-time error. A `fromConfig(config, { isSuspended })` option takes
+   * precedence; a `runAgent({ isSuspended })` host override beats both.
+   */
+  suspendedTags?: string[];
   meta?: Record<string, unknown>;
 }
 /** A `requests` entry in {@link AgentWorkflowConfig} — the JSON equivalent of a `setupAgent({ requests })` `TextLogicConfig`. Fields beyond `input`/`output`/`tools`/`mode`/`description` are `unknown` because they accept template-expression strings (see {@link AgentWorkflowConfig}). */
@@ -228,6 +239,16 @@ interface FromConfigOptions {
    * implementation here is a build-time error.
    */
   actions?: Record<string, (params: any) => unknown>;
+  /**
+   * Detects a snapshot that is an INTENTIONAL wait for an external event —
+   * the same machine-carried predicate `setupAgent({ isSuspended })` declares
+   * for TS-authored machines, registered here because a function cannot live
+   * in the workflow config itself. Takes precedence over the config's
+   * declarative {@link AgentWorkflowConfig.suspendedTags}; a
+   * `runAgent({ isSuspended })` host override beats both. Travels with the
+   * machine through `machine.provide(...)`.
+   */
+  isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
 }
 //#endregion
 //#region src/setup-agent.d.ts

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { _ as resolveAgentStep, a as AgentReplayDivergenceError, b as messagesSchema, c as diffEventLogs, d as replay, f as validateReplayEntries, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_USAGE_EVENT_TYPE, l as getAgentEffects, m as executeAgentRequest, n as setupAgent, o as AgentReplayMachineMismatchError, p as verifyReplay, r as AGENT_INIT_EVENT_TYPE, s as createReplayEntry, t as createAgentSchemas, u as initEntry, v as transitionAgentStep, y as appendMessages } from "./setup-agent-SbiiSbAU.mjs";
-import { A as isUnboundPlaceholder, B as getMachineStructuralHash, C as parseStructuredEnvelope, D as getMachineStaticTransitionTargets, E as executorBoundLogics, G as toolMessage, H as isStandardSchema, I as findNonSerializableContextPaths, K as userMessage, L as getAgentMessages, O as getMachineSuspensionPredicate, P as assistantMessage, R as getJsonSchema, S as parseOutput, U as persistSnapshot, V as getStateMeta, W as systemMessage, _ as getAgentOutputMode, a as resolveDecision, b as normalizeGeneratorResult, c as AGENT_USAGE_TOKEN_FIELDS, f as bindRequestExecutor, h as createTextLogic, i as renderDecisionAttempts, k as getRegisteredAgentExecutionOptions, o as getAcceptedEvents, p as buildEnvelopeSchema, q as validateSchemaSync, r as isDecisionLogic, s as parseAgentEvent, t as AgentDecisionExhaustedError, u as INTERPRET_SOURCE, v as getCallUsage, x as parseModelRef, y as isTextLogic, z as getJsonSchemaSync } from "./decision-Bt2HYYRo.mjs";
+import { _ as resolveAgentStep, a as AgentReplayDivergenceError, b as messagesSchema, c as diffEventLogs, d as replay, f as validateReplayEntries, g as initialAgentStep, h as getInvokeEffectMetadata, i as AGENT_USAGE_EVENT_TYPE, l as getAgentEffects, m as executeAgentRequest, n as setupAgent, o as AgentReplayMachineMismatchError, p as verifyReplay, r as AGENT_INIT_EVENT_TYPE, s as createReplayEntry, t as createAgentSchemas, u as initEntry, v as transitionAgentStep, y as appendMessages } from "./setup-agent-CTg57Pa4.mjs";
+import { A as isUnboundPlaceholder, B as getMachineStructuralHash, C as parseStructuredEnvelope, D as getMachineStaticTransitionTargets, E as executorBoundLogics, G as toolMessage, H as isStandardSchema, I as findNonSerializableContextPaths, K as userMessage, L as getAgentMessages, O as getMachineSuspensionPredicate, P as assistantMessage, R as getJsonSchema, S as parseOutput, U as persistSnapshot, V as getStateMeta, W as systemMessage, _ as getAgentOutputMode, a as resolveDecision, b as normalizeGeneratorResult, c as AGENT_USAGE_TOKEN_FIELDS, f as bindRequestExecutor, h as createTextLogic, i as renderDecisionAttempts, k as getRegisteredAgentExecutionOptions, o as getAcceptedEvents, p as buildEnvelopeSchema, q as validateSchemaSync, r as isDecisionLogic, s as parseAgentEvent, t as AgentDecisionExhaustedError, u as INTERPRET_SOURCE, v as getCallUsage, x as parseModelRef, y as isTextLogic, z as getJsonSchemaSync } from "./decision-C11xuud2.mjs";
 import { a as assertJsonSerializable, i as assertAgentLogEntry, n as AgentEventLogConflictError, o as createInMemoryEventLogStore, r as NonSerializableAgentEventError, s as assertEventLogStoreConformance, t as AGENT_EVENT_SCHEMA_VERSION } from "./event-log-store-B-1fcfkT.mjs";
 import { createActor, createAsyncLogic, getNextTransitions, isMachineSnapshot } from "xstate";
 //#region src/internal/state-request-pass.ts

package/dist/machines.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_setup_agent = require("./setup-agent-BLU77gqr.cjs");
+const require_setup_agent = require("./setup-agent-D_EyJ0Ik.cjs");
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";

package/dist/machines.mjs

@@ -1,4 +1,4 @@
-import { n as setupAgent } from "./setup-agent-SbiiSbAU.mjs";
+import { n as setupAgent } from "./setup-agent-CTg57Pa4.mjs";
 //#region src/machines/internal.ts
 /** The builtin inline text request every preset lowers a request entry to. */
 const GENERATE_TEXT_SRC = "agent.generateText";

package/dist/{setup-agent-SbiiSbAU.mjs → setup-agent-CTg57Pa4.mjs}

@@ -1,5 +1,5 @@
 import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { B as getMachineStructuralHash, F as djb2Hex, M as machineSuspensionPredicates, N as missingActor, T as agentExecutionOptions, d as USER_INPUT_ACTOR, g as executeAgentTextRequest, h as createTextLogic, j as machineStaticTransitionTargets, k as getRegisteredAgentExecutionOptions, l as DECIDE_ACTOR, m as builtinTextActors, n as createDecideActor, o as getAcceptedEvents, q as validateSchemaSync, r as isDecisionLogic, w as userInputActor, y as isTextLogic } from "./decision-Bt2HYYRo.mjs";
+import { B as getMachineStructuralHash, F as djb2Hex, M as machineSuspensionPredicates, N as missingActor, T as agentExecutionOptions, d as USER_INPUT_ACTOR, g as executeAgentTextRequest, h as createTextLogic, j as machineStaticTransitionTargets, k as getRegisteredAgentExecutionOptions, l as DECIDE_ACTOR, m as builtinTextActors, n as createDecideActor, o as getAcceptedEvents, q as validateSchemaSync, r as isDecisionLogic, w as userInputActor, y as isTextLogic } from "./decision-C11xuud2.mjs";
 import { a as assertJsonSerializable, i as assertAgentLogEntry } from "./event-log-store-B-1fcfkT.mjs";
 import { createMachineFromConfig, initialTransition, setup, transition } from "xstate";
 //#region src/messages.ts
@@ -1128,6 +1128,22 @@ function translateWorkflowConfig(config, translation) {
 	if (json.output === void 0 && finalOutputs.length === 1) json.output = finalOutputs[0];
 	return json;
 }
+function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
+	for (const state of Object.values(states ?? {})) {
+		for (const tag of state.tags ?? []) tags.add(tag);
+		collectDeclaredStateTags(state.states, tags);
+	}
+	return tags;
+}
+function resolveSuspensionPredicate(config, options) {
+	if (options.isSuspended) return options.isSuspended;
+	const suspendedTags = config.suspendedTags ?? [];
+	if (!suspendedTags.length) return;
+	const declaredTags = collectDeclaredStateTags(config.states);
+	const unknown = suspendedTags.filter((tag) => !declaredTags.has(tag));
+	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'suspendedTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
+	return (snapshot) => suspendedTags.some((tag) => snapshot.hasTag(tag));
+}
 function setupAgentFromConfig(config, options) {
 	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
 	const { compileSchema } = options;
@@ -1158,6 +1174,8 @@ function setupAgentFromConfig(config, options) {
 		models: {}
 	});
 	if (machine.config) machineStaticTransitionTargets.set(machine.config, translation.transitionTargets);
+	const isSuspended = resolveSuspensionPredicate(config, options);
+	if (isSuspended && machine.config) machineSuspensionPredicates.set(machine.config, isSuspended);
 	return {
 		machine,
 		schemas

package/dist/{setup-agent-BLU77gqr.cjs → setup-agent-D_EyJ0Ik.cjs}

@@ -1,5 +1,5 @@
 const require_errors = require("./errors-DUBBzRLP.cjs");
-const require_decision = require("./decision-Ba8qrT8r.cjs");
+const require_decision = require("./decision-DnQCQPew.cjs");
 const require_event_log_store = require("./event-log-store-yquOV1TX.cjs");
 let xstate = require("xstate");
 //#region src/messages.ts
@@ -1128,6 +1128,22 @@ function translateWorkflowConfig(config, translation) {
 	if (json.output === void 0 && finalOutputs.length === 1) json.output = finalOutputs[0];
 	return json;
 }
+function collectDeclaredStateTags(states, tags = /* @__PURE__ */ new Set()) {
+	for (const state of Object.values(states ?? {})) {
+		for (const tag of state.tags ?? []) tags.add(tag);
+		collectDeclaredStateTags(state.states, tags);
+	}
+	return tags;
+}
+function resolveSuspensionPredicate(config, options) {
+	if (options.isSuspended) return options.isSuspended;
+	const suspendedTags = config.suspendedTags ?? [];
+	if (!suspendedTags.length) return;
+	const declaredTags = collectDeclaredStateTags(config.states);
+	const unknown = suspendedTags.filter((tag) => !declaredTags.has(tag));
+	if (unknown.length) throw new Error(`setupAgent.fromConfig: 'suspendedTags' lists ${unknown.map((tag) => `'${tag}'`).join(", ")}, which no state declares in its 'tags'. Tag the waiting state(s) — e.g. "tags": ["${unknown[0]}"] — or remove the entry.`);
+	return (snapshot) => suspendedTags.some((tag) => snapshot.hasTag(tag));
+}
 function setupAgentFromConfig(config, options) {
 	if (!options || typeof options.compileSchema !== "function") throw new Error("setupAgent.fromConfig(...) requires a 'compileSchema' option: { compileSchema: (jsonSchema, name) => StandardSchemaV1 }. Bring your own JSON Schema engine (Ajv, @cfworker/json-schema, a compiled-Zod-from-JSON-Schema pipeline, ...). Core intentionally ships no JSON Schema engine.");
 	const { compileSchema } = options;
@@ -1158,6 +1174,8 @@ function setupAgentFromConfig(config, options) {
 		models: {}
 	});
 	if (machine.config) require_decision.machineStaticTransitionTargets.set(machine.config, translation.transitionTargets);
+	const isSuspended = resolveSuspensionPredicate(config, options);
+	if (isSuspended && machine.config) require_decision.machineSuspensionPredicates.set(machine.config, isSuspended);
 	return {
 		machine,
 		schemas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.16",
+  "version": "2.0.0-alpha.17",
   "description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
   "keywords": [
     "agent",

package/schemas/agent-workflow.json

@@ -71,6 +71,14 @@
         "$ref": "#/$defs/State"
       }
     },
+    "suspendedTags": {
+      "description": "State tags that mark an intentional wait for an external event (a human approval, an inbound webhook, ...). Lowered by setupAgent.fromConfig(...) into a snapshot.hasTag(...) suspension predicate so runAgent settles those states idle deterministically. Every listed tag must appear in some state's 'tags'.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "meta": {
       "$ref": "#/$defs/JsonObject"
     }