@statelyai/agent 2.0.0-alpha.29 → 2.0.0-alpha.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/CHANGELOG.md +1733 -0
  2. package/dist/ai-sdk.cjs +9 -9
  3. package/dist/ai-sdk.d.cts +5 -5
  4. package/dist/ai-sdk.d.mts +5 -5
  5. package/dist/ai-sdk.mjs +4 -4
  6. package/dist/{decision-Bl_rKQnU.mjs → decision-DqO018Tp.mjs} +23 -10
  7. package/dist/{decision-oevZnkBe.cjs → decision-Iys2hzg3.cjs} +31 -18
  8. package/dist/{event-log-Dtb16p1p.cjs → event-log-Bdww2l1D.cjs} +104 -25
  9. package/dist/{event-log-GPZO9p7_.mjs → event-log-DE430ZCa.mjs} +87 -26
  10. package/dist/{event-log-store-bCdskPNS.cjs → event-log-store-BWMLi6oh.cjs} +1 -1
  11. package/dist/{event-log-store-yalq8C77.mjs → event-log-store-CCWdTPEP.mjs} +1 -1
  12. package/dist/{event-log-store-CN9ygggF.d.cts → event-log-store-DTf_OzB-.d.cts} +1 -1
  13. package/dist/{event-log-store-DS836wch.d.mts → event-log-store-RziIobdW.d.mts} +1 -1
  14. package/dist/index.cjs +136 -23
  15. package/dist/index.d.cts +58 -11
  16. package/dist/index.d.mts +58 -11
  17. package/dist/index.mjs +133 -21
  18. package/dist/log.cjs +2 -2
  19. package/dist/log.d.cts +1 -1
  20. package/dist/log.d.mts +1 -1
  21. package/dist/log.mjs +2 -2
  22. package/dist/machines.cjs +1 -1
  23. package/dist/machines.mjs +1 -1
  24. package/dist/{model-source-C7FFP2Sj.mjs → model-source-CXsSZPq0.mjs} +1 -2
  25. package/dist/{model-source-DjJPjGSP.cjs → model-source-DQ7KgJaT.cjs} +4 -5
  26. package/dist/openai.cjs +3 -3
  27. package/dist/openai.d.cts +2 -2
  28. package/dist/openai.d.mts +2 -2
  29. package/dist/openai.mjs +3 -3
  30. package/dist/otel.d.cts +1 -1
  31. package/dist/otel.d.mts +1 -1
  32. package/dist/{run-agent-C9ubX8Tx.d.cts → run-agent-B5opVUxx.d.cts} +25 -6
  33. package/dist/{run-agent-CxSyZmIE.d.mts → run-agent-D4MwS5GY.d.mts} +25 -6
  34. package/dist/{run-agent-CuQT1xSS.mjs → run-agent-DWZ1uyBJ.mjs} +100 -37
  35. package/dist/{run-agent-cToZ3K42.cjs → run-agent-tmk58M0x.cjs} +100 -37
  36. package/dist/{setup-agent-DniLvDu7.mjs → setup-agent-BaffhCcM.mjs} +38 -3
  37. package/dist/{setup-agent-tsc3vm5I.d.mts → setup-agent-CPyg2ic7.d.mts} +11 -3
  38. package/dist/{setup-agent-DTF3NQg3.cjs → setup-agent-D0L8Anl_.cjs} +38 -3
  39. package/dist/{setup-agent-DlbgwsIJ.d.cts → setup-agent-yFFVXf5s.d.cts} +11 -3
  40. package/dist/tanstack-ai.cjs +3 -3
  41. package/dist/tanstack-ai.d.cts +2 -2
  42. package/dist/tanstack-ai.d.mts +2 -2
  43. package/dist/tanstack-ai.mjs +3 -3
  44. package/dist/testing.cjs +176 -26
  45. package/dist/testing.d.cts +128 -10
  46. package/dist/testing.d.mts +128 -10
  47. package/dist/testing.mjs +168 -20
  48. package/dist/{text-logic-BDbGjYMh.d.mts → text-logic-BwdrDpO9.d.mts} +6 -2
  49. package/dist/{text-logic-9fv1i9aK.d.cts → text-logic-j9hShB7d.d.cts} +6 -2
  50. package/dist/{usage-D8UphgEA.d.mts → usage-BYqv7VBw.d.cts} +1 -1
  51. package/dist/{usage-R1NTmLxY.d.cts → usage-Bl4nK8D-.d.mts} +1 -1
  52. package/dist/validate.cjs +3 -3
  53. package/dist/validate.d.cts +2 -2
  54. package/dist/validate.d.mts +2 -2
  55. package/dist/validate.mjs +3 -3
  56. package/dist/{verify-B5qGC5WN.mjs → verify-BH5e0XLK.mjs} +55 -5
  57. package/dist/{verify-DYH_2VzU.d.cts → verify-CPKDPMwY.d.cts} +14 -6
  58. package/dist/{verify-Cqghu4gz.cjs → verify-CS_xxvVU.cjs} +57 -7
  59. package/dist/{verify-CBuYIpsa.d.mts → verify-tkymWz6X.d.mts} +14 -6
  60. package/package.json +34 -4
  61. package/readme.md +72 -42
  62. package/skills/add-evals/SKILL.md +144 -0
  63. package/skills/add-traces/SKILL.md +147 -0
  64. package/skills/generate-machine/SKILL.md +6 -6
  65. package/skills/graph-engineering/SKILL.md +33 -0
  66. package/skills/improve-machine/SKILL.md +73 -21
  67. package/skills/improve-machine/reference.md +12 -7
  68. package/skills/loop-to-machine/SKILL.md +210 -0
  69. package/skills/loop-to-machine/policy.md +154 -0
package/dist/openai.cjs CHANGED
@@ -1,6 +1,6 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_event_log = require("./event-log-Dtb16p1p.cjs");
3
- const require_decision = require("./decision-oevZnkBe.cjs");
2
+ const require_event_log = require("./event-log-Bdww2l1D.cjs");
3
+ const require_decision = require("./decision-Iys2hzg3.cjs");
4
4
  //#region src/openai/index.ts
5
5
  /** Thrown for a message part Chat Completions cannot carry — dropping it would
6
6
  * silently change what the model sees. */
@@ -284,7 +284,7 @@ function toToolContent(output) {
284
284
  * ```ts
285
285
  * const executors = createOpenAiExecutors({
286
286
  * client: new OpenAI(),
287
- * resolveModel: () => 'gpt-5.4-mini',
287
+ * resolveModel: () => 'gpt-6-luna',
288
288
  * });
289
289
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
290
290
  * ```
package/dist/openai.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
2
- import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-9fv1i9aK.cjs";
2
+ import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-j9hShB7d.cjs";
3
3
  import OpenAI from "openai";
4
4
  import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
5
5
  //#region src/openai/index.d.ts
@@ -170,7 +170,7 @@ export declare function addAgentCallUsage(total: AgentCallUsage | undefined, nex
170
170
  * ```ts
171
171
  * const executors = createOpenAiExecutors({
172
172
  * client: new OpenAI(),
173
- * resolveModel: () => 'gpt-5.4-mini',
173
+ * resolveModel: () => 'gpt-6-luna',
174
174
  * });
175
175
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
176
176
  * ```
package/dist/openai.d.mts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
2
- import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BDbGjYMh.mjs";
2
+ import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BwdrDpO9.mjs";
3
3
  import OpenAI from "openai";
4
4
  import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
5
5
  //#region src/openai/index.d.ts
@@ -170,7 +170,7 @@ export declare function addAgentCallUsage(total: AgentCallUsage | undefined, nex
170
170
  * ```ts
171
171
  * const executors = createOpenAiExecutors({
172
172
  * client: new OpenAI(),
173
- * resolveModel: () => 'gpt-5.4-mini',
173
+ * resolveModel: () => 'gpt-6-luna',
174
174
  * });
175
175
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
176
176
  * ```
package/dist/openai.mjs CHANGED
@@ -1,5 +1,5 @@
1
- import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, ct as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-GPZO9p7_.mjs";
2
- import { c as renderDecisionAttempts } from "./decision-Bl_rKQnU.mjs";
1
+ import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, dt as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-DE430ZCa.mjs";
2
+ import { c as renderDecisionAttempts } from "./decision-DqO018Tp.mjs";
3
3
  //#region src/openai/index.ts
4
4
  /** Thrown for a message part Chat Completions cannot carry — dropping it would
5
5
  * silently change what the model sees. */
@@ -283,7 +283,7 @@ function toToolContent(output) {
283
283
  * ```ts
284
284
  * const executors = createOpenAiExecutors({
285
285
  * client: new OpenAI(),
286
- * resolveModel: () => 'gpt-5.4-mini',
286
+ * resolveModel: () => 'gpt-6-luna',
287
287
  * });
288
288
  * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
289
289
  * ```
package/dist/otel.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { g as AgentTraceEvent } from "./run-agent-C9ubX8Tx.cjs";
1
+ import { g as AgentTraceEvent } from "./run-agent-B5opVUxx.cjs";
2
2
  import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
3
3
  //#region src/otel/index.d.ts
4
4
  /** Options for {@link createOtelTraceHandler}. */
package/dist/otel.d.mts CHANGED
@@ -1,4 +1,4 @@
1
- import { g as AgentTraceEvent } from "./run-agent-CxSyZmIE.mjs";
1
+ import { g as AgentTraceEvent } from "./run-agent-D4MwS5GY.mjs";
2
2
  import { Attributes, Tracer, TracerProvider } from "@opentelemetry/api";
3
3
  //#region src/otel/index.d.ts
4
4
  /** Options for {@link createOtelTraceHandler}. */
@@ -1,7 +1,7 @@
1
1
  import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.cjs";
2
- import { I as DecisionAttempt, N as AgentDecisionRequest, Q as AgentError, W as AgentEventDescriptor, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, q as AgentRequestSource, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-9fv1i9aK.cjs";
3
- import { n as AgentUsageEvent } from "./usage-R1NTmLxY.cjs";
4
- import { c as AgentLogEntry, n as AgentEventLogStore } from "./event-log-store-CN9ygggF.cjs";
2
+ import { I as DecisionAttempt, N as AgentDecisionRequest, Q as AgentError, W as AgentEventDescriptor, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, q as AgentRequestSource, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-j9hShB7d.cjs";
3
+ import { n as AgentUsageEvent } from "./usage-BYqv7VBw.cjs";
4
+ import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-DTf_OzB-.cjs";
5
5
  import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
6
6
  import { DurableExecution } from "xstate/durable";
7
7
  //#region src/steps.d.ts
@@ -121,6 +121,13 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
121
121
  };
122
122
  snapshot: SnapshotFrom<TMachine>;
123
123
  event: EventFromLogic<TMachine>;
124
+ /**
125
+ * `true` when the host's own event (the run's opening `event`, or one
126
+ * sent with `runtime.transition`) had no transition in this state, so
127
+ * nothing changed: the same event {@link AgentRunResult.ignored}
128
+ * reports. Absent otherwise.
129
+ */
130
+ ignored?: true;
124
131
  } | {
125
132
  type: "emit";
126
133
  event: EmittedFrom<TMachine>;
@@ -246,11 +253,23 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
246
253
  onEvent?: (entry: AgentLogEntry) => void;
247
254
  /**
248
255
  * Record a `verification.stateHash` on every appended entry (default `true`).
249
- * The hash is taken O(1) from the live actor's persisted snapshot right after
250
- * that entry's transition, so `replay(machine, events)` can prove it lands on
251
- * the same state. Set `false` for a smaller, unverifiable log.
256
+ * The hash is of the state the log folds to after that entry, the same fold
257
+ * `replay` runs, so `replay(machine, events)` can check each entry against
258
+ * the fold before it. It does not show the log is complete (a dropped last
259
+ * entry leaves the rest intact), nor compare against the live snapshot: a
260
+ * machine that reads something the log does not keep (an error's class, a
261
+ * non-JSON field) can replay to a different state. Set `false` for a
262
+ * smaller, unverifiable log.
252
263
  */
253
264
  verification?: boolean;
265
+ /**
266
+ * Host-owned JSON stored on the log's `@agent.init` entry when this run
267
+ * starts a log: what produced the run, such as a policy version, the model
268
+ * ids, or the scenario. A resume keeps the stamp of the run that started
269
+ * the log; a version bridge, which opens a new log segment, takes this
270
+ * run's. `executionId` and `migratedFrom` are reserved and cannot be set here.
271
+ */
272
+ metadata?: Record<string, JsonValue$1>;
254
273
  /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
255
274
  actors?: Record<string, AnyActorLogic>;
256
275
  /**
@@ -1,7 +1,7 @@
1
1
  import { _ as StandardSchemaV1, m as InferInput, s as AgentTools, w as WithAgentInputSchema } from "./types-Dp5_Ru4R.mjs";
2
- import { I as DecisionAttempt, N as AgentDecisionRequest, Q as AgentError, W as AgentEventDescriptor, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, q as AgentRequestSource, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BDbGjYMh.mjs";
3
- import { n as AgentUsageEvent } from "./usage-D8UphgEA.mjs";
4
- import { c as AgentLogEntry, n as AgentEventLogStore } from "./event-log-store-DS836wch.mjs";
2
+ import { I as DecisionAttempt, N as AgentDecisionRequest, Q as AgentError, W as AgentEventDescriptor, d as AgentRequestMode, f as AgentTextRequest, m as AgentUsage, q as AgentRequestSource, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BwdrDpO9.mjs";
3
+ import { n as AgentUsageEvent } from "./usage-Bl4nK8D-.mjs";
4
+ import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-RziIobdW.mjs";
5
5
  import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
6
6
  import { DurableExecution } from "xstate/durable";
7
7
  //#region src/steps.d.ts
@@ -121,6 +121,13 @@ type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
121
121
  };
122
122
  snapshot: SnapshotFrom<TMachine>;
123
123
  event: EventFromLogic<TMachine>;
124
+ /**
125
+ * `true` when the host's own event (the run's opening `event`, or one
126
+ * sent with `runtime.transition`) had no transition in this state, so
127
+ * nothing changed: the same event {@link AgentRunResult.ignored}
128
+ * reports. Absent otherwise.
129
+ */
130
+ ignored?: true;
124
131
  } | {
125
132
  type: "emit";
126
133
  event: EmittedFrom<TMachine>;
@@ -246,11 +253,23 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
246
253
  onEvent?: (entry: AgentLogEntry) => void;
247
254
  /**
248
255
  * Record a `verification.stateHash` on every appended entry (default `true`).
249
- * The hash is taken O(1) from the live actor's persisted snapshot right after
250
- * that entry's transition, so `replay(machine, events)` can prove it lands on
251
- * the same state. Set `false` for a smaller, unverifiable log.
256
+ * The hash is of the state the log folds to after that entry, the same fold
257
+ * `replay` runs, so `replay(machine, events)` can check each entry against
258
+ * the fold before it. It does not show the log is complete (a dropped last
259
+ * entry leaves the rest intact), nor compare against the live snapshot: a
260
+ * machine that reads something the log does not keep (an error's class, a
261
+ * non-JSON field) can replay to a different state. Set `false` for a
262
+ * smaller, unverifiable log.
252
263
  */
253
264
  verification?: boolean;
265
+ /**
266
+ * Host-owned JSON stored on the log's `@agent.init` entry when this run
267
+ * starts a log: what produced the run, such as a policy version, the model
268
+ * ids, or the scenario. A resume keeps the stamp of the run that started
269
+ * the log; a version bridge, which opens a new log segment, takes this
270
+ * run's. `executionId` and `migratedFrom` are reserved and cannot be set here.
271
+ */
272
+ metadata?: Record<string, JsonValue$1>;
254
273
  /** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
255
274
  actors?: Record<string, AnyActorLogic>;
256
275
  /**
@@ -1,6 +1,6 @@
1
- import { B as responseMessagesOf, C as AGENT_USAGE_EVENT_TYPE, F as normalizeGeneratorResult, J as findNonSerializableContextPaths, M as getCallFinishReason, N as getCallUsage, P as isTextLogic, S as validateReplayEntries, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, W as isUnboundPlaceholder, _ as getUsageFromEvents, d as createReplayEntry, f as foldLog, g as getSnapshotStateHash, h as getLogExecutionId, i as AgentMachineVersionMismatchError, l as assertJsonSerializable, nt as resolveMachineVersion, ot as validateSchemaSync, s as agentCallOccurrence, st as AgentError, tt as isStandardSchema, u as canonicalEventJson, v as initEntry, x as replay } from "./event-log-GPZO9p7_.mjs";
2
- import { d as getAcceptedEvents, l as resolveDecision, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-Bl_rKQnU.mjs";
3
- import { t as AgentEventLogConflictError } from "./event-log-store-yalq8C77.mjs";
1
+ import { B as responseMessagesOf, C as AGENT_USAGE_EVENT_TYPE, F as normalizeGeneratorResult, J as findNonSerializableContextPaths, M as getCallFinishReason, N as getCallUsage, P as isTextLogic, S as validateReplayEntries, U as getRegisteredAgentExecutionOptions, V as executorBoundLogics, W as isUnboundPlaceholder, _ as getUsageFromEvents, d as createReplayEntry, f as foldLog, g as getSnapshotStateHash, h as getLogExecutionId, i as AgentMachineVersionMismatchError, l as assertJsonSerializable, nt as resolveMachineVersion, ot as validateSchemaSync, s as agentCallOccurrence, st as canonicalJson, tt as isStandardSchema, u as canonicalEventJson, ut as AgentError, v as initEntry, x as replay } from "./event-log-DE430ZCa.mjs";
2
+ import { d as getAcceptedEvents, f as getHumanEventTypes, l as resolveDecision, n as acceptedDecisionOptions, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-DqO018Tp.mjs";
3
+ import { t as AgentEventLogConflictError } from "./event-log-store-CCWdTPEP.mjs";
4
4
  import { createAsyncLogic, getNextTransitions, isMachineSnapshot, stopActor } from "xstate";
5
5
  import { createDurable } from "xstate/durable";
6
6
  //#region src/run-agent.ts
@@ -290,6 +290,13 @@ function unrebindableChildRequestError(childPath, stateName, requestSrc, kind) {
290
290
  function declaresUsageTransition(snapshot) {
291
291
  return getNextTransitions(snapshot).some((transition) => transition.eventType === "@agent.usage" || transition.eventType === "*");
292
292
  }
293
+ function observe(name, call) {
294
+ try {
295
+ call();
296
+ } catch (error) {
297
+ console.error(`@statelyai/agent: ${name} threw; the run continues.`, error);
298
+ }
299
+ }
293
300
  /**
294
301
  * Builds the ONE place a trace payload is emitted: it hands the payload to the
295
302
  * envelope-stamping trace sink and, from that same payload, invokes the sugar
@@ -306,21 +313,21 @@ function createTraceDispatch(sinks) {
306
313
  return (payload, self) => {
307
314
  switch (payload.type) {
308
315
  case "stream.chunk":
309
- sinks.onTrace?.(payload, self);
310
- sinks.onChunk?.(payload.chunk, { request: payload.request });
316
+ observe("onTrace", () => sinks.onTrace?.(payload, self));
317
+ observe("onChunk", () => sinks.onChunk?.(payload.chunk, { request: payload.request }));
311
318
  return;
312
319
  case "request.end":
313
- sinks.onResult?.(payload.request, {
320
+ observe("onResult", () => sinks.onResult?.(payload.request, {
314
321
  result: payload.output,
315
322
  raw: payload.raw
316
- });
317
- sinks.onTrace?.(payload, self);
323
+ }));
324
+ observe("onTrace", () => sinks.onTrace?.(payload, self));
318
325
  return;
319
326
  case "machine.transition":
320
- sinks.onTrace?.(payload, self);
321
- sinks.onTransition?.(payload.snapshot, payload.event);
327
+ observe("onTrace", () => sinks.onTrace?.(payload, self));
328
+ observe("onTransition", () => sinks.onTransition?.(payload.snapshot, payload.event));
322
329
  return;
323
- default: sinks.onTrace?.(payload, self);
330
+ default: observe("onTrace", () => sinks.onTrace?.(payload, self));
324
331
  }
325
332
  };
326
333
  }
@@ -509,6 +516,11 @@ function bindDecisionLogic(logic, runCtx) {
509
516
  schemas: runCtx.schemas,
510
517
  eventTypes: declaredEventTypes
511
518
  }) : [];
519
+ const agentCan = (event) => {
520
+ if (!actorRef) return true;
521
+ const snapshot = actorRef.getSnapshot();
522
+ return !getHumanEventTypes(snapshot).has(event.type) && snapshot.can(event);
523
+ };
512
524
  const lowered = logic.request(input);
513
525
  const request = {
514
526
  ...lowered,
@@ -521,7 +533,7 @@ function bindDecisionLogic(logic, runCtx) {
521
533
  const options = acceptedDecisionOptions(request, (event) => {
522
534
  let accepted;
523
535
  try {
524
- accepted = actorRef ? actorRef.getSnapshot().can(event) : true;
536
+ accepted = agentCan(event);
525
537
  } catch {
526
538
  accepted = false;
527
539
  }
@@ -532,6 +544,10 @@ function bindDecisionLogic(logic, runCtx) {
532
544
  request.options = options;
533
545
  request.withheld = withheld;
534
546
  }
547
+ if (actorRef) {
548
+ const humanEventTypes = getHumanEventTypes(actorRef.getSnapshot());
549
+ request.events = events.filter((event) => !humanEventTypes.has(event.type));
550
+ }
535
551
  if (options?.length === 0) {
536
552
  const error = new AgentDecisionExhaustedError([]);
537
553
  error.message = `Decision '${request.name}' has no offered option the current snapshot accepts; no model call was made.`;
@@ -554,7 +570,7 @@ function bindDecisionLogic(logic, runCtx) {
554
570
  } }, {
555
571
  maxRetries: lowered.maxRetries ?? logic.maxRetries,
556
572
  signal,
557
- canTake: (event) => actorRef ? actorRef.getSnapshot().can(event) : true
573
+ canTake: agentCan
558
574
  });
559
575
  if (priorAttempts.length > 0) runCtx.noteDecision?.(chosen, priorAttempts);
560
576
  actorRef?.send(chosen);
@@ -918,6 +934,8 @@ function createAgentRuntime(machine, options = {}) {
918
934
  let traceSeq = 0;
919
935
  const machineId = machine.config.id ?? machine.id ?? "(machine)";
920
936
  const machineVersion = resolveMachineVersion(machine);
937
+ if (options.metadata !== void 0) assertJsonSerializable(options.metadata, "metadata");
938
+ const initMetadata = options.metadata === void 0 ? void 0 : structuredClone(options.metadata);
921
939
  const onTrace = createTraceDispatch({
922
940
  onTrace: (payload) => {
923
941
  options.onTrace?.({
@@ -998,13 +1016,32 @@ function createAgentRuntime(machine, options = {}) {
998
1016
  let loggingEnabled = true;
999
1017
  const attemptsByEvent = /* @__PURE__ */ new WeakMap();
1000
1018
  let logFold;
1019
+ const stopLogging = (error) => {
1020
+ if (!loggingEnabled) return;
1021
+ loggingEnabled = false;
1022
+ if (store !== void 0) {
1023
+ journalError ??= error;
1024
+ stopRun({
1025
+ cause: "journal",
1026
+ error
1027
+ });
1028
+ return;
1029
+ }
1030
+ console.warn(`@statelyai/agent: this run's log stopped at entry ${logEntries.length}, so result.events is incomplete: ${error instanceof Error ? error.message : String(error)}. Pass input and events that JSON can hold.`);
1031
+ };
1001
1032
  const appendLogEntry = (event, attempts) => {
1002
1033
  if (!loggingEnabled) return;
1003
- const entry = createReplayEntry(logMachine, logEntries, event, {
1004
- machineVersion,
1005
- verification: false,
1006
- ...attempts !== void 0 ? { attempts } : {}
1007
- });
1034
+ let entry;
1035
+ try {
1036
+ entry = createReplayEntry(logMachine, logEntries, event, {
1037
+ machineVersion,
1038
+ verification: false,
1039
+ ...attempts !== void 0 ? { attempts } : {}
1040
+ });
1041
+ } catch (error) {
1042
+ stopLogging(error);
1043
+ return;
1044
+ }
1008
1045
  if (verificationEnabled && logFold !== null) try {
1009
1046
  logFold ??= foldLog(logMachine, logEntries, {
1010
1047
  machineVersion,
@@ -1016,7 +1053,7 @@ function createAgentRuntime(machine, options = {}) {
1016
1053
  }
1017
1054
  logEntries.push(entry);
1018
1055
  journalEntry(entry);
1019
- options.onEvent?.(entry);
1056
+ observe("onEvent", () => options.onEvent?.(entry));
1020
1057
  return entry;
1021
1058
  };
1022
1059
  const recordUsage = (usage, source = {}) => {
@@ -1191,8 +1228,8 @@ function createAgentRuntime(machine, options = {}) {
1191
1228
  event
1192
1229
  });
1193
1230
  const on = options.on ?? {};
1194
- on[event.type]?.(event);
1195
- if (event.type !== "*") on["*"]?.(event);
1231
+ observe(`on['${event.type}']`, () => on[event.type]?.(event));
1232
+ if (event.type !== "*") observe("on['*']", () => on["*"]?.(event));
1196
1233
  };
1197
1234
  const inspect = options.inspect === void 0 ? void 0 : (event) => {
1198
1235
  if (typeof options.inspect === "function") options.inspect(event);
@@ -1246,14 +1283,15 @@ function createAgentRuntime(machine, options = {}) {
1246
1283
  }
1247
1284
  }, inspect ? { inspect } : void 0);
1248
1285
  const runErrorCause = (error) => budgetExceeded ? "max-model-calls" : wrapsDecisionExhausted(error) ? "decision-exhausted" : "machine";
1249
- const commit = (snapshot, event) => {
1286
+ const commit = (snapshot, event, ignored = false) => {
1250
1287
  const from = { value: (current ?? snapshot).value };
1251
1288
  current = snapshot;
1252
1289
  onTrace({
1253
1290
  type: "machine.transition",
1254
1291
  from,
1255
1292
  snapshot,
1256
- event
1293
+ event,
1294
+ ...ignored ? { ignored: true } : {}
1257
1295
  });
1258
1296
  };
1259
1297
  /** True for a child completion/failure whose child is no longer running under the current state. */
@@ -1267,14 +1305,23 @@ function createAgentRuntime(machine, options = {}) {
1267
1305
  if (started) throw new AgentError("runtime-started", "createAgentRuntime: `start` was already called.");
1268
1306
  started = true;
1269
1307
  let resumeEvents = init.events;
1308
+ let resumedFromStore = false;
1270
1309
  if (store !== void 0) {
1271
1310
  const storedThread = await store.read(threadId);
1272
1311
  if (resumeEvents !== void 0) {
1273
1312
  if (storedThread.length !== resumeEvents.length) throw new AgentEventLogConflictError(threadId, resumeEvents.length, storedThread.length);
1274
1313
  assertThreadMatchesEvents(threadId, storedThread, resumeEvents);
1275
- } else if (storedThread.length > 0) resumeEvents = storedThread;
1314
+ resumedFromStore = storedThread.length > 0;
1315
+ } else if (storedThread.length > 0) {
1316
+ resumeEvents = storedThread;
1317
+ resumedFromStore = true;
1318
+ }
1276
1319
  }
1277
1320
  const resolvedInput = resolveMachineInput(machine, init.input);
1321
+ const threadInit = resumeEvents?.[0]?.event;
1322
+ if (resumedFromStore && init.input !== void 0 && threadInit !== void 0 && Object.hasOwn(threadInit, "input")) {
1323
+ if (canonicalJson(threadInit.input) !== canonicalJson(resolvedInput)) throw new AgentError("thread-input-mismatch", `createAgentRuntime: thread '${threadId}' was started with different input. A thread that already has entries is resumed, not restarted; give a new run a new threadId.`);
1324
+ }
1278
1325
  let effectiveSnapshot = init.snapshot;
1279
1326
  let seedInitEntry;
1280
1327
  const restoredPersistedSnapshot = () => {
@@ -1292,18 +1339,25 @@ function createAgentRuntime(machine, options = {}) {
1292
1339
  * run WITHOUT a log rather than failing it.
1293
1340
  */
1294
1341
  const appendInitEntry = (candidates, metadata) => {
1295
- for (const candidate of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) try {
1296
- const entry = initEntry(logMachine, candidate, {
1297
- machineVersion,
1298
- verification,
1299
- metadata
1300
- });
1342
+ let lastError;
1343
+ for (const candidate of candidates) for (const verification of verificationEnabled ? [true, false] : [false]) {
1344
+ let entry;
1345
+ try {
1346
+ entry = initEntry(logMachine, candidate, {
1347
+ machineVersion,
1348
+ verification,
1349
+ metadata
1350
+ });
1351
+ } catch (error) {
1352
+ lastError = error;
1353
+ continue;
1354
+ }
1301
1355
  logEntries.push(entry);
1302
1356
  journalEntry(entry);
1303
- options.onEvent?.(entry);
1357
+ observe("onEvent", () => options.onEvent?.(entry));
1304
1358
  return;
1305
- } catch {}
1306
- loggingEnabled = false;
1359
+ }
1360
+ stopLogging(lastError);
1307
1361
  };
1308
1362
  /** Init forms for a snapshot resume, most faithful first. */
1309
1363
  const snapshotInitCandidates = () => {
@@ -1370,16 +1424,23 @@ function createAgentRuntime(machine, options = {}) {
1370
1424
  logIndex: resumeEvents.length
1371
1425
  };
1372
1426
  seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
1427
+ ...initMetadata,
1373
1428
  ...logExecutionId !== void 0 ? { executionId: logExecutionId } : {},
1374
1429
  migratedFrom
1375
1430
  });
1376
1431
  }
1377
1432
  } else if (init.snapshot !== void 0) {
1378
1433
  logExecutionId = crypto.randomUUID();
1379
- seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), { executionId: logExecutionId });
1434
+ seedInitEntry = () => appendInitEntry(snapshotInitCandidates(), {
1435
+ ...initMetadata,
1436
+ executionId: logExecutionId
1437
+ });
1380
1438
  } else {
1381
1439
  logExecutionId = crypto.randomUUID();
1382
- seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], { executionId: logExecutionId });
1440
+ seedInitEntry = () => appendInitEntry([resolvedInput !== void 0 ? { input: resolvedInput } : {}], {
1441
+ ...initMetadata,
1442
+ executionId: logExecutionId
1443
+ });
1383
1444
  }
1384
1445
  const resumedHistory = [...logEntries];
1385
1446
  const siteCallCounts = /* @__PURE__ */ new Map();
@@ -1447,9 +1508,11 @@ function createAgentRuntime(machine, options = {}) {
1447
1508
  const attempts = transitionOptions?.attempts ?? attemptsByEvent.get(event);
1448
1509
  if (transitionOptions?.attempts !== void 0) assertJsonSerializable(transitionOptions.attempts, "attempts");
1449
1510
  const [next, effects] = execution.transition(state, event);
1450
- if (!fromMailbox.has(event) && next === state && effects.length === 0) ignoredEvent = event;
1511
+ const ignored = !fromMailbox.has(event) && next === state && effects.length === 0;
1512
+ if (ignored) ignoredEvent = event;
1451
1513
  appendLogEntry(event, attempts);
1452
- commit(next, event);
1514
+ if (stopReason !== void 0) return [state, []];
1515
+ commit(next, event, ignored);
1453
1516
  return [next, effects];
1454
1517
  },
1455
1518
  async execute(effects) {