@statelyai/agent 2.0.0-alpha.5 → 2.0.0-alpha.7

package/dist/{text-logic-2EMJIS-n.d.mts → text-logic-2wFNEznm.d.mts}

@@ -383,6 +383,21 @@ type AgentModelMap = Record<string, unknown>;
  * adapter's models map / `resolveModel`) resolves them to a real model.
  */
 type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : (keyof TModels & string) | (string & {});
+/**
+ * Splits a portable `"provider/model-id"` model ref (the convention JSON
+ * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
+ * its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
+ * The standard building block for a host's `resolveModel`:
+ *
+ * @example
+ * ```ts
+ * const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
+ * ```
+ */
+declare function parseModelRef(modelRef: string): {
+  provider: string | undefined;
+  modelId: string;
+};
 /**
  * Portable, provider-agnostic input a text request passes to a host
  * executor (`generateText`/`streamText` on {@link AgentRequestExecutors}).
@@ -437,17 +452,22 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    */
   metadata?: TMetadata;
 }
-/** Inline input for the `agent.userInput` builtin actor — a human-input request (CLI prompt, form, chat reply, …). See {@link RunAgentOptions.userInput}. */
+/**
+ * Inline input for the `agent.userInput` builtin actor — a human-input request
+ * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
+ * See {@link RunAgentOptions.userInput}. For structured input, parse/classify
+ * the string in a follow-up state, or register a custom actor source; host
+ * rendering hints (a form spec, say) belong in `metadata`.
+ */
 interface AgentUserInput<TMetadata = Record<string, unknown>> {
   prompt?: string;
-  schema?: StandardSchemaV1;
   metadata?: TMetadata;
 }
 /** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
 type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
   [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
-  [USER_INPUT_ACTOR]: AsyncActorLogic<unknown, AgentUserInput>;
+  [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
   [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
   [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
 };
@@ -564,7 +584,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
  * });
  * ```
  */
-declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor, info?: Pick<AgentRequestExecutorInfo, "onChunk">): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 /**
  * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
  * `output` is the request's value (a text string or a structured object).
@@ -678,5 +698,13 @@ interface StructuredOutputEnvelope {
 declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
   reasoning?: boolean;
 }): StandardSchemaV1<StructuredOutputEnvelope>;
+/**
+ * Validates a raw provider value against the structured-output envelope for
+ * `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+ * replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
+ * Pair with {@link buildEnvelopeSchema} (which produced the schema the
+ * provider was asked to satisfy).
+ */
+declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentPlanInput as A, AgentEventDescriptor as B, createTextLogic as C, AgentDecisionExecutor as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentRequestOptions as H, PLAN_DONE_EVENT_TYPE as I, matchesEventPattern as K, ResolveDecisionOptions as L, DecisionAttempt as M, DecisionExhaustedError as N, AgentDecisionInput as O, DecisionLogic as P, renderDecisionAttempts as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentRequestSource as U, AgentEventToolNameResolver as V, EVENT_TOOL_PREFIX as W, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentPlanOutput as j, AgentDecisionRequest as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, parseAgentEvent as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, resolveDecision as z };
+export { AgentDecisionInput as A, renderDecisionAttempts as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogic as I, matchesEventPattern as J, EVENT_TOOL_PREFIX as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, ResolveDecisionOptions as z };

package/dist/{text-logic-1ZQkO3zr.d.cts → text-logic-4Q2F9kyr.d.cts}

@@ -383,6 +383,21 @@ type AgentModelMap = Record<string, unknown>;
  * adapter's models map / `resolveModel`) resolves them to a real model.
  */
 type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : (keyof TModels & string) | (string & {});
+/**
+ * Splits a portable `"provider/model-id"` model ref (the convention JSON
+ * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
+ * its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
+ * The standard building block for a host's `resolveModel`:
+ *
+ * @example
+ * ```ts
+ * const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
+ * ```
+ */
+declare function parseModelRef(modelRef: string): {
+  provider: string | undefined;
+  modelId: string;
+};
 /**
  * Portable, provider-agnostic input a text request passes to a host
  * executor (`generateText`/`streamText` on {@link AgentRequestExecutors}).
@@ -437,17 +452,22 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    */
   metadata?: TMetadata;
 }
-/** Inline input for the `agent.userInput` builtin actor — a human-input request (CLI prompt, form, chat reply, …). See {@link RunAgentOptions.userInput}. */
+/**
+ * Inline input for the `agent.userInput` builtin actor — a human-input request
+ * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
+ * See {@link RunAgentOptions.userInput}. For structured input, parse/classify
+ * the string in a follow-up state, or register a custom actor source; host
+ * rendering hints (a form spec, say) belong in `metadata`.
+ */
 interface AgentUserInput<TMetadata = Record<string, unknown>> {
   prompt?: string;
-  schema?: StandardSchemaV1;
   metadata?: TMetadata;
 }
 /** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
 type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
   [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
-  [USER_INPUT_ACTOR]: AsyncActorLogic<unknown, AgentUserInput>;
+  [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
   [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
   [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
 };
@@ -564,7 +584,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
  * });
  * ```
  */
-declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor, info?: Pick<AgentRequestExecutorInfo, "onChunk">): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 /**
  * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
  * `output` is the request's value (a text string or a structured object).
@@ -678,5 +698,13 @@ interface StructuredOutputEnvelope {
 declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
   reasoning?: boolean;
 }): StandardSchemaV1<StructuredOutputEnvelope>;
+/**
+ * Validates a raw provider value against the structured-output envelope for
+ * `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+ * replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
+ * Pair with {@link buildEnvelopeSchema} (which produced the schema the
+ * provider was asked to satisfy).
+ */
+declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentPlanInput as A, AgentEventDescriptor as B, createTextLogic as C, AgentDecisionExecutor as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentRequestOptions as H, PLAN_DONE_EVENT_TYPE as I, matchesEventPattern as K, ResolveDecisionOptions as L, DecisionAttempt as M, DecisionExhaustedError as N, AgentDecisionInput as O, DecisionLogic as P, renderDecisionAttempts as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentRequestSource as U, AgentEventToolNameResolver as V, EVENT_TOOL_PREFIX as W, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentPlanOutput as j, AgentDecisionRequest as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, parseAgentEvent as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, resolveDecision as z };
+export { AgentDecisionInput as A, renderDecisionAttempts as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogic as I, matchesEventPattern as J, EVENT_TOOL_PREFIX as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, ResolveDecisionOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.5",
+  "version": "2.0.0-alpha.7",
   "description": "State-machine authoring layer for AI agents",
   "type": "module",
   "main": "dist/index.cjs",
@@ -96,7 +96,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.6.2",
     "vitest": "^2.1.2",
-    "xstate": "6.0.0-alpha.17",
+    "xstate": "6.0.0-alpha.21",
     "zod": "^4.3.6"
   },
   "publishConfig": {

package/readme.md

@@ -132,6 +132,7 @@ The example has one model decision and two final outcomes. Real machines can add
 <!-- starter examples derived from examples/*/metadata.json and examples/index.ts -->
 
 - [Twenty Questions](examples/twenty-questions) shows a model choosing legal events in a loop.
+- [Go Fish](examples/go-fish) pits a model against a human while the machine enforces hidden-information game rules.
 - [Human in the loop](examples/human-in-the-loop) pauses, stores a snapshot, and resumes after review.
 - [Ticket triage](examples/triage) returns structured data from a model request.
 - [JSON agent](examples/json-agent) runs a machine defined as data.