@eduardorenani/atlasjs 0.1.0-alpha.0

package/dist/defineAgent.js

@@ -0,0 +1,79 @@
+// `defineAgent` — constructs the root XState machine.
+//
+// Spec: docs/specs/004-xstate-agent-wrapper.md §`defineAgent`
+//        + docs/specs/005-agent-deps-and-stringifiable-context.md §`defineAgent`
+//
+// `defineAgent` is the only constructor that touches `xstate`: it returns an
+// `AnyStateMachine` so the rest of the project (`createActor`, the inspector,
+// existing tests) keeps working unchanged. The lowering itself lives in
+// `compile.ts`.
+//
+// Deps lifecycle (spec 005 §Imutabilidade):
+//   - `Object.freeze` is applied once, here, before the closure is captured.
+//   - The frozen reference is threaded to `compile.ts`, which captures it in
+//     every generated callback's closure. There is no runtime path to swap
+//     deps after this call returns.
+import { compile } from "./compile.js";
+/**
+ * Construct the **root agent** — compiles the declarative `AgentConfig` into
+ * a runnable XState machine. This is the single boundary where the wrapper
+ * touches `xstate`: the return type is `AnyStateMachine`, so callers feed it
+ * straight into `createActor`, the inspector, and existing tests.
+ *
+ * The agent's `modes` map can mix `Mode`s (leaves) and nested `CompoundMode`s
+ * freely. The compile step lowers them, validates sibling-target references,
+ * injects the `END` synthetic state per-compound when referenced, and wires
+ * the payload-driven `routes` into XState transitions.
+ *
+ * @template TContext  The agent's root context shape. Constrained to
+ *                     `JsonCompatible<TContext>` so the snapshot round-trips
+ *                     through arbitrary storage without custom encoding.
+ * @template TEvents   The agent's full event union. Each variant must have a
+ *                     `type: string` discriminant. Pass `{} as Ev` to the
+ *                     `events` field — only its type matters; it's a phantom.
+ * @template TModes    The root `modes` map. `initial` is keyed against this
+ *                     type so a typo is a compile error.
+ * @template TDeps     Frozen container of external resources. Defaults to
+ *                     `Record<string, never>` when `deps` is omitted —
+ *                     callbacks still receive `deps`, typed as the empty
+ *                     object, so the envelope shape stays uniform.
+ *
+ * @param config  `{ id, initial, context, events, deps?, actions?, modes }`.
+ *                `actions` registers reusable, deps-aware callbacks (each
+ *                returning `Partial<TContext>`) referenced by name from
+ *                passive `on[event].actions`. The wrapper wraps them in
+ *                `assign(...)` at compile time, so user code never imports
+ *                from `xstate`.
+ *
+ * @returns An `AnyStateMachine` ready to pass to `createActor`.
+ *
+ * @example
+ * ```ts
+ * const agent = defineAgent<Ctx, Ev, Modes, { db: Driver; logger: Logger }>({
+ *     id: "zoe",
+ *     initial: "listening",
+ *     context: { messages: [], attempts: 0 },
+ *     events: {} as Ev,
+ *     deps: { db: realDb, logger: pino() },
+ *     actions: {
+ *         appendUserMsg: ({ context, event, deps }) =>
+ *             event.type === "USER_MSG"
+ *                 ? { messages: [...context.messages, { role: "user", content: event.text }] }
+ *                 : {},
+ *     },
+ *     modes: { listening, classifying, greetings, socratic },
+ * });
+ *
+ * const actor = createActor(agent).start();
+ * actor.send({ type: "USER_MSG", text: "hi" });
+ * ```
+ */
+export function defineAgent(config) {
+    // Spec 005 §Imutabilidade: shallow freeze the deps container once, here,
+    // before passing the reference to `compile`. The default-empty branch
+    // produces a frozen `{}` so callbacks observe `Object.isFrozen(deps) === true`
+    // even when the consumer omits `deps`.
+    const frozenDeps = Object.freeze(config.deps ?? {});
+    return compile(config, frozenDeps);
+}
+//# sourceMappingURL=defineAgent.js.map

package/dist/defineAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineAgent.js","sourceRoot":"","sources":["../src/defineAgent.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,8DAA8D;AAC9D,iFAAiF;AACjF,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,wEAAwE;AACxE,gBAAgB;AAChB,EAAE;AACF,4CAA4C;AAC5C,6EAA6E;AAC7E,6EAA6E;AAC7E,2EAA2E;AAC3E,oCAAoC;AAIpC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,WAAW,CAKzB,MAAqD;IACnD,yEAAyE;IACzE,sEAAsE;IACtE,+EAA+E;IAC/E,uCAAuC;IACvC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,IAAK,EAAY,CAAC,CAAC;IAC/D,OAAO,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC"}

package/dist/defineCompoundMode.d.ts

@@ -0,0 +1,77 @@
+import type { CompoundContext, CompoundMode, CompoundModeConfig, LocalContextOf, ModesMap } from "./types.js";
+/**
+ * Runtime carrier behind the opaque `CompoundMode` brand. Internal —
+ * accessed only by `compile.ts` via the `__kind` discriminant.
+ *
+ * `config` is stored as `unknown` on purpose: the original generic narrowing
+ * has already done its job at the call site, and `compile.ts` walks the tree
+ * structurally rather than relying on the generic parameters.
+ *
+ * @template TParentContext  Context shape the parent scope provides.
+ * @template TEvents         The agent's full event union.
+ * @template TDeps           Frozen deps container this compound demands.
+ */
+export type CompoundModeCarrier<TParentContext, TEvents extends {
+    type: string;
+}, TDeps extends Record<string, unknown> = Record<string, never>> = {
+    readonly __kind: "compound";
+    readonly config: unknown;
+};
+/**
+ * Construct a **CompoundMode** — a Mode that contains sub-Modes. Use this to
+ * group related leaves under a shared lifecycle, optionally narrowing the
+ * context children see via `context: { inherit, local }`.
+ *
+ * Children's effective context is `LocalContextOf<TParentContext, TCtx>`:
+ * - With `context` supplied: `Pick<TParentContext, inherit[number]> & typeof local`.
+ *   Inherited keys are live-mirrored; locals are reset on every entry.
+ * - Without `context`: children see the full `TParentContext`.
+ *
+ * Children route out of the compound via `END` (defined in `./types.ts`); the
+ * compound's `onDone` then fires the parent-level transition.
+ *
+ * @template TParentContext  The context the enclosing scope provides to this
+ *                           compound. Constrained to
+ *                           `JsonCompatible<TParentContext>`.
+ * @template TEvents         The agent's full event union (each variant has a
+ *                           `type` discriminant).
+ * @template TCtx            Either `undefined` (no narrowing — children see
+ *                           `TParentContext`) or a `CompoundContext` literal
+ *                           declaring which keys to `inherit` and which `local`
+ *                           variables to declare. The `local` shape must
+ *                           satisfy `JsonCompatible<TLocal>` (enforced at the
+ *                           `CompoundContext` alias level).
+ * @template TModes          The compound's `modes` map. Each slot is a
+ *                           `Mode` (leaf) or nested `CompoundMode` typed
+ *                           against the compound-local context view.
+ * @template TDeps           Frozen deps this compound passes to its children.
+ *                           Must match the agent's `TDeps` at the slot site
+ *                           (spec 005 §`defineCompoundMode` "Manual threading").
+ *
+ * @param config  `{ context?, initial, modes, onDone }`. `initial` is keyed
+ *                against `TModes` so a typo is a compile error. `onDone`
+ *                accepts a sibling name or `END` (when nested further).
+ *
+ * @returns An opaque `CompoundMode` brand. Only `defineCompoundMode` /
+ *          `defineAgent` accept it as a `modes` slot.
+ *
+ * @example CompoundMode with context narrowing — children see only `messages`.
+ * ```ts
+ * const socratic = defineCompoundMode<AgentCtx, Ev, {
+ *     inherit: ["messages"];
+ *     local: { attempts: number };
+ * }, {
+ *     thinking: Mode<{ messages: Msg[]; attempts: number }, Ev>;
+ *     evaluating: Mode<{ messages: Msg[]; attempts: number }, Ev, EvalPayload>;
+ * }, AgentDeps>({
+ *     context: { inherit: ["messages"] as const, local: { attempts: 0 } },
+ *     initial: "thinking",
+ *     modes: { thinking, evaluating },
+ *     onDone: "listening",
+ * });
+ * ```
+ */
+export declare function defineCompoundMode<TParentContext, TEvents extends {
+    type: string;
+}, TCtx extends CompoundContext<TParentContext, ReadonlyArray<keyof TParentContext & string>, object> | undefined, TModes extends ModesMap<LocalContextOf<TParentContext, TCtx>, TEvents, TDeps>, TDeps extends Record<string, unknown> = Record<string, never>>(config: CompoundModeConfig<TParentContext, TEvents, TCtx, TModes, TDeps>): CompoundMode<TParentContext, TEvents, TDeps>;
+//# sourceMappingURL=defineCompoundMode.d.ts.map

package/dist/defineCompoundMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCompoundMode.d.ts","sourceRoot":"","sources":["../src/defineCompoundMode.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACR,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACX,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,CAC3B,cAAc,EACd,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAC7D;IACA,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,kBAAkB,CAC9B,cAAc,EACd,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChC,IAAI,SACE,eAAe,CACb,cAAc,EACd,aAAa,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,EAO5C,MAAM,CACT,GACC,SAAS,EACf,MAAM,SAAS,QAAQ,CAAC,cAAc,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,EAC7E,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAE7D,MAAM,EAAE,kBAAkB,CAAC,cAAc,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,GACzE,YAAY,CAAC,cAAc,EAAE,OAAO,EAAE,KAAK,CAAC,CAM9C"}

package/dist/defineCompoundMode.js

@@ -0,0 +1,79 @@
+// `defineCompoundMode` — constructs a CompoundMode (a Mode with sub-Modes).
+//
+// Spec: docs/specs/004-xstate-agent-wrapper.md §`defineCompoundMode`
+//        + docs/specs/005-agent-deps-and-stringifiable-context.md §`defineCompoundMode`
+//        + docs/specs/006-modes-not-states.md §"Refined vocabulary"
+//
+// Like `defineMode`, this is a thin Phase 3 shell. The generics enforce
+// the compound-local context narrowing at the call site: children's
+// `TContext` is `LocalContextOf<TParentContext, TCtx>`. The compile step in
+// `compile.ts` lowers the carrier to XState states later.
+//
+// `TDeps` is threaded through to the returned `CompoundMode` brand via its
+// contravariant `__phantomDeps` field. See spec 005 §`defineCompoundMode` for
+// the manual-threading rationale: TypeScript cannot infer the agent's `TDeps`
+// from a sub-Mode definition site (Modes are typically declared in separate
+// files and only referenced from `defineAgent.modes`), so each
+// `defineCompoundMode` invocation declares its own `TDeps` generic explicitly.
+/**
+ * Construct a **CompoundMode** — a Mode that contains sub-Modes. Use this to
+ * group related leaves under a shared lifecycle, optionally narrowing the
+ * context children see via `context: { inherit, local }`.
+ *
+ * Children's effective context is `LocalContextOf<TParentContext, TCtx>`:
+ * - With `context` supplied: `Pick<TParentContext, inherit[number]> & typeof local`.
+ *   Inherited keys are live-mirrored; locals are reset on every entry.
+ * - Without `context`: children see the full `TParentContext`.
+ *
+ * Children route out of the compound via `END` (defined in `./types.ts`); the
+ * compound's `onDone` then fires the parent-level transition.
+ *
+ * @template TParentContext  The context the enclosing scope provides to this
+ *                           compound. Constrained to
+ *                           `JsonCompatible<TParentContext>`.
+ * @template TEvents         The agent's full event union (each variant has a
+ *                           `type` discriminant).
+ * @template TCtx            Either `undefined` (no narrowing — children see
+ *                           `TParentContext`) or a `CompoundContext` literal
+ *                           declaring which keys to `inherit` and which `local`
+ *                           variables to declare. The `local` shape must
+ *                           satisfy `JsonCompatible<TLocal>` (enforced at the
+ *                           `CompoundContext` alias level).
+ * @template TModes          The compound's `modes` map. Each slot is a
+ *                           `Mode` (leaf) or nested `CompoundMode` typed
+ *                           against the compound-local context view.
+ * @template TDeps           Frozen deps this compound passes to its children.
+ *                           Must match the agent's `TDeps` at the slot site
+ *                           (spec 005 §`defineCompoundMode` "Manual threading").
+ *
+ * @param config  `{ context?, initial, modes, onDone }`. `initial` is keyed
+ *                against `TModes` so a typo is a compile error. `onDone`
+ *                accepts a sibling name or `END` (when nested further).
+ *
+ * @returns An opaque `CompoundMode` brand. Only `defineCompoundMode` /
+ *          `defineAgent` accept it as a `modes` slot.
+ *
+ * @example CompoundMode with context narrowing — children see only `messages`.
+ * ```ts
+ * const socratic = defineCompoundMode<AgentCtx, Ev, {
+ *     inherit: ["messages"];
+ *     local: { attempts: number };
+ * }, {
+ *     thinking: Mode<{ messages: Msg[]; attempts: number }, Ev>;
+ *     evaluating: Mode<{ messages: Msg[]; attempts: number }, Ev, EvalPayload>;
+ * }, AgentDeps>({
+ *     context: { inherit: ["messages"] as const, local: { attempts: 0 } },
+ *     initial: "thinking",
+ *     modes: { thinking, evaluating },
+ *     onDone: "listening",
+ * });
+ * ```
+ */
+export function defineCompoundMode(config) {
+    const carrier = {
+        __kind: "compound",
+        config,
+    };
+    return carrier;
+}
+//# sourceMappingURL=defineCompoundMode.js.map

package/dist/defineCompoundMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCompoundMode.js","sourceRoot":"","sources":["../src/defineCompoundMode.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,qEAAqE;AACrE,wFAAwF;AACxF,oEAAoE;AACpE,EAAE;AACF,wEAAwE;AACxE,oEAAoE;AACpE,4EAA4E;AAC5E,0DAA0D;AAC1D,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,+DAA+D;AAC/D,+EAA+E;AA+B/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,kBAAkB,CAmB9B,MAAwE;IAExE,MAAM,OAAO,GAAwD;QACjE,MAAM,EAAE,UAAU;QAClB,MAAM;KACT,CAAC;IACF,OAAO,OAAkE,CAAC;AAC9E,CAAC"}

package/dist/defineMode.d.ts

@@ -0,0 +1,89 @@
+import type { Mode, ModeConfig } from "./types.js";
+/**
+ * Runtime carrier behind the opaque `Mode` brand. Internal — accessed
+ * only by `compile.ts` via the `__kind` discriminant. User code never sees
+ * this shape because `defineMode` returns the branded type.
+ *
+ * @template TContext  Context shape this Mode reads/writes.
+ * @template TEvents   The agent's full event union (each variant has a `type`).
+ * @template TPayload  Payload shape carried by `ModeOutput<TPayload>`.
+ * @template TDeps     Frozen deps container this Mode demands.
+ */
+export type ModeCarrier<TContext, TEvents extends {
+    type: string;
+}, TPayload, TDeps extends Record<string, unknown> = Record<string, never>> = {
+    readonly __kind: "leaf";
+    readonly config: ModeConfig<TContext, TEvents, TPayload, TDeps>;
+};
+/**
+ * Construct a **leaf Mode** — one node in the agent's state tree with no
+ * sub-Modes. Modes come in two structural flavors:
+ *
+ * - **Active** (`{ input, behavior, routes }`) — runs an async `behavior` and
+ *   dispatches on its `ModeOutput`. Use for LLM calls, tool execution,
+ *   classifiers — anything that does work and then decides where to go next.
+ *
+ * - **Passive** (`{ on }`) — waits for an external event. Use for listening
+ *   states or user-input gates.
+ *
+ * The two variants are mutually exclusive at the type level: mixing `behavior`
+ * and `on` is a compile error.
+ *
+ * @template TContext  Shape of the context this Mode observes. Constrained to
+ *                     `JsonCompatible<TContext>`. At the agent's top level,
+ *                     this is the agent's full context. Inside a
+ *                     `defineCompoundMode` with a narrowing `context`, this is
+ *                     the compound-local view: inherited keys + declared locals.
+ * @template TEvents   The agent's full event union. Each variant must have a
+ *                     `type: string` discriminant. Passive `on` handlers are
+ *                     typed against this union via `Extract<TEvents, { type: K }>`.
+ * @template TPayload  Payload type carried on a successful `behavior` return
+ *                     (`ModeOutput<TPayload>`). Flows into `routes.*.when` and
+ *                     `routes.*.assign` for payload-driven dispatch. Defaults
+ *                     to `unknown` (relevant only for passive Modes, which
+ *                     never produce a payload).
+ * @template TDeps     Frozen deps this Mode wants to see. Defaults to
+ *                     `Record<string, never>` — a Mode with the default
+ *                     slots into any agent. A Mode that declares
+ *                     `<…, { db: Driver }>` can only slot into agents whose
+ *                     `defineAgent.deps` provides at least `db`.
+ *
+ * @param config  An `ActiveModeConfig` or a `PassiveModeConfig`. The
+ *                discriminator is structural — TypeScript picks the variant
+ *                from which keys are present.
+ *
+ * @returns An opaque `Mode` brand. User code cannot inspect it; only
+ *          `defineCompoundMode` and `defineAgent` accept it as a `modes` slot.
+ *
+ * @example Active Mode — classify an intent and route on the payload.
+ * ```ts
+ * const classifying = defineMode<Ctx, Ev, { intent: "greet" | "learn" }>({
+ *     input: ({ context, deps }) => ({ messages: context.messages }),
+ *     behavior: async ({ input, deps }) => {
+ *         const intent = await deps.llm.classify(input);
+ *         return { outcome: "achieved", payload: { intent } };
+ *     },
+ *     routes: {
+ *         achieved: [
+ *             { when: (p) => p.intent === "greet", target: "greetings" },
+ *             { target: "socratic" },
+ *         ],
+ *         retry: [],
+ *         abandoned: { target: END },
+ *     },
+ * });
+ * ```
+ *
+ * @example Passive Mode — park here until a `USER_MSG` event arrives.
+ * ```ts
+ * const listening = defineMode<Ctx, Ev>({
+ *     on: {
+ *         USER_MSG: { target: "classifying", actions: "appendUserMsg" },
+ *     },
+ * });
+ * ```
+ */
+export declare function defineMode<TContext, TEvents extends {
+    type: string;
+}, TPayload = unknown, TDeps extends Record<string, unknown> = Record<string, never>>(config: ModeConfig<TContext, TEvents, TPayload, TDeps>): Mode<TContext, TEvents, TPayload, TDeps>;
+//# sourceMappingURL=defineMode.d.ts.map

package/dist/defineMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMode.d.ts","sourceRoot":"","sources":["../src/defineMode.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,CACnB,QAAQ,EACR,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChC,QAAQ,EACR,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAC7D;IACA,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;CACnE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,UAAU,CACtB,QAAQ,EACR,OAAO,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAChC,QAAQ,GAAG,OAAO,EAClB,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAE7D,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,GACvD,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAS1C"}

package/dist/defineMode.js

@@ -0,0 +1,95 @@
+// `defineMode` — constructs a leaf agent Mode (active or passive variant).
+//
+// Spec: docs/specs/004-xstate-agent-wrapper.md §`defineMode`
+//        + docs/specs/005-agent-deps-and-stringifiable-context.md §`defineMode`
+//        + docs/specs/006-modes-not-states.md §"Refined vocabulary"
+//
+// Phase 3 (these constructors) is a thin shell: it stores the user's config
+// plus a runtime `__kind` tag behind the opaque `Mode` brand. The actual
+// XState lowering happens in `compile.ts` (Phase 5) and is reached only via
+// `defineAgent`. Users never inspect the returned object.
+//
+// The `TDeps` generic flows through to the brand via `__phantomDeps`, which
+// puts it in function-argument position — making `Mode` contravariant in
+// `TDeps`. That gives the slot-time variance check in `defineAgent.modes`
+// the right direction structurally: a `Mode` demanding `{ db }` slots into
+// agents whose deps include at least `db`.
+/**
+ * Construct a **leaf Mode** — one node in the agent's state tree with no
+ * sub-Modes. Modes come in two structural flavors:
+ *
+ * - **Active** (`{ input, behavior, routes }`) — runs an async `behavior` and
+ *   dispatches on its `ModeOutput`. Use for LLM calls, tool execution,
+ *   classifiers — anything that does work and then decides where to go next.
+ *
+ * - **Passive** (`{ on }`) — waits for an external event. Use for listening
+ *   states or user-input gates.
+ *
+ * The two variants are mutually exclusive at the type level: mixing `behavior`
+ * and `on` is a compile error.
+ *
+ * @template TContext  Shape of the context this Mode observes. Constrained to
+ *                     `JsonCompatible<TContext>`. At the agent's top level,
+ *                     this is the agent's full context. Inside a
+ *                     `defineCompoundMode` with a narrowing `context`, this is
+ *                     the compound-local view: inherited keys + declared locals.
+ * @template TEvents   The agent's full event union. Each variant must have a
+ *                     `type: string` discriminant. Passive `on` handlers are
+ *                     typed against this union via `Extract<TEvents, { type: K }>`.
+ * @template TPayload  Payload type carried on a successful `behavior` return
+ *                     (`ModeOutput<TPayload>`). Flows into `routes.*.when` and
+ *                     `routes.*.assign` for payload-driven dispatch. Defaults
+ *                     to `unknown` (relevant only for passive Modes, which
+ *                     never produce a payload).
+ * @template TDeps     Frozen deps this Mode wants to see. Defaults to
+ *                     `Record<string, never>` — a Mode with the default
+ *                     slots into any agent. A Mode that declares
+ *                     `<…, { db: Driver }>` can only slot into agents whose
+ *                     `defineAgent.deps` provides at least `db`.
+ *
+ * @param config  An `ActiveModeConfig` or a `PassiveModeConfig`. The
+ *                discriminator is structural — TypeScript picks the variant
+ *                from which keys are present.
+ *
+ * @returns An opaque `Mode` brand. User code cannot inspect it; only
+ *          `defineCompoundMode` and `defineAgent` accept it as a `modes` slot.
+ *
+ * @example Active Mode — classify an intent and route on the payload.
+ * ```ts
+ * const classifying = defineMode<Ctx, Ev, { intent: "greet" | "learn" }>({
+ *     input: ({ context, deps }) => ({ messages: context.messages }),
+ *     behavior: async ({ input, deps }) => {
+ *         const intent = await deps.llm.classify(input);
+ *         return { outcome: "achieved", payload: { intent } };
+ *     },
+ *     routes: {
+ *         achieved: [
+ *             { when: (p) => p.intent === "greet", target: "greetings" },
+ *             { target: "socratic" },
+ *         ],
+ *         retry: [],
+ *         abandoned: { target: END },
+ *     },
+ * });
+ * ```
+ *
+ * @example Passive Mode — park here until a `USER_MSG` event arrives.
+ * ```ts
+ * const listening = defineMode<Ctx, Ev>({
+ *     on: {
+ *         USER_MSG: { target: "classifying", actions: "appendUserMsg" },
+ *     },
+ * });
+ * ```
+ */
+export function defineMode(config) {
+    const carrier = {
+        __kind: "leaf",
+        config,
+    };
+    // The brand is a phantom — at runtime the object is just the carrier.
+    // The cast is the single boundary where the opaque type is minted; user
+    // code can only obtain `Mode` values through this function.
+    return carrier;
+}
+//# sourceMappingURL=defineMode.js.map

package/dist/defineMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineMode.js","sourceRoot":"","sources":["../src/defineMode.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,6DAA6D;AAC7D,gFAAgF;AAChF,oEAAoE;AACpE,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,4EAA4E;AAC5E,0DAA0D;AAC1D,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,2EAA2E;AAC3E,2CAA2C;AAwB3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,MAAM,UAAU,UAAU,CAMtB,MAAsD;IAEtD,MAAM,OAAO,GAAoD;QAC7D,MAAM,EAAE,MAAM;QACd,MAAM;KACT,CAAC;IACF,sEAAsE;IACtE,wEAAwE;IACxE,4DAA4D;IAC5D,OAAO,OAA8D,CAAC;AAC1E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { defineMode } from "./defineMode.js";
+export { defineCompoundMode } from "./defineCompoundMode.js";
+export { defineAgent } from "./defineAgent.js";
+export { END, RE_THROW } from "./types.js";
+export type { ModeOutput, Outcome, Mode, CompoundMode, ModeConfig, ActiveModeConfig, PassiveModeConfig, CompoundModeConfig, AgentConfig, ModesMap, CompoundContext, Routes, RouteList, RouteTarget, ErrorRouteTarget, EventHandlers, JsonPrimitive, JsonValue, JsonObject, JsonArray, JsonCompatible, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EACR,UAAU,EACV,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,eAAe,EACf,MAAM,EACN,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,SAAS,EACT,UAAU,EACV,SAAS,EACT,cAAc,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// Atlas — XState wrapper for AI agent orchestration.
+//
+// Spec: docs/specs/004-xstate-agent-wrapper.md
+//       docs/specs/005-agent-deps-and-stringifiable-context.md
+// Tasks: docs/specs/004-tasks.md
+export { defineMode } from "./defineMode.js";
+export { defineCompoundMode } from "./defineCompoundMode.js";
+export { defineAgent } from "./defineAgent.js";
+export { END, RE_THROW } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,EAAE;AACF,+CAA+C;AAC/C,+DAA+D;AAC/D,iCAAiC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/injectEnd.d.ts

@@ -0,0 +1,10 @@
+import type { LoweredAtomicState } from "./buildPassiveState.js";
+import type { LoweredInvokeState } from "./buildActiveState.js";
+export type LoweredLeafState = LoweredAtomicState | LoweredInvokeState;
+export declare const END_SUBSTATE: {
+    type: "final";
+};
+export declare function pickEndName(siblings: readonly string[]): string;
+export declare function hasEndReference(state: LoweredLeafState): boolean;
+export declare function rewriteEndTargets(state: LoweredLeafState, endName: string): LoweredLeafState;
+//# sourceMappingURL=injectEnd.d.ts.map

package/dist/injectEnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectEnd.d.ts","sourceRoot":"","sources":["../src/injectEnd.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,kBAAkB,EAAqB,MAAM,wBAAwB,CAAC;AACpF,OAAO,KAAK,EACR,kBAAkB,EAGrB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAGvE,eAAO,MAAM,YAAY;;CAA6B,CAAC;AAgBvD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM/D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAmBhE;AA6BD,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,MAAM,GAChB,gBAAgB,CAwBlB"}

package/dist/injectEnd.js

@@ -0,0 +1,106 @@
+// Phase 5.11 helpers: `$end` substate injection + END-target rewrite.
+//
+// Spec: docs/specs/004-tasks.md Phase 5.11 + 5.12,
+// docs/specs/004-xstate-agent-wrapper.md §"END and the injected final substate"
+// (lines 631-635).
+//
+// A compound mode whose subtree references `target: END` anywhere needs an
+// injected final substate to exit through — XState requires a concrete state
+// name as a transition target, the spec keeps `END` as a symbol so it cannot
+// collide with user-declared names. This module provides the building blocks:
+//   - `pickEndName(siblings)`: collision-safe name (`$end`, `$end1`, ...)
+//   - `hasEndReference(state)`: does a lowered leaf state mention END anywhere?
+//   - `rewriteEndTargets(state, name)`: same shape with every END target swapped
+//   - `END_SUBSTATE`: the XState final-substate config to inject
+//
+// The compound-lowering slice (5.16) composes these:
+//   if any direct child references END → pickEndName(Object.keys(states)),
+//     rewriteEndTargets on each child, set states[endName] = END_SUBSTATE.
+//   Otherwise leave the compound open (5.12 — no final substate emitted).
+import { END } from "./types.js";
+// XState final-substate config — what gets dropped into `states[endName]`.
+export const END_SUBSTATE = { type: "final" };
+// `Array.isArray` widens `readonly T[]` to `any[]` and fails to subtract it
+// from a `T | readonly T[]` union. Typed predicate keeps narrowing precise
+// without leaking `any`. (Same pattern as buildPassiveState / buildActiveState.)
+function isReadonlyArray(value) {
+    return Array.isArray(value);
+}
+function isInvoke(state) {
+    return "invoke" in state;
+}
+// `$end` if available, then `$end1`, `$end2`, ... — the `$` prefix is unusual
+// enough that collisions with user keys are vanishingly rare, but we still
+// probe and bump for safety.
+export function pickEndName(siblings) {
+    const set = new Set(siblings);
+    if (!set.has("$end"))
+        return "$end";
+    let i = 1;
+    while (set.has(`$end${i}`))
+        i += 1;
+    return `$end${i}`;
+}
+export function hasEndReference(state) {
+    if (isInvoke(state)) {
+        for (const t of state.invoke.onDone) {
+            if (t.target === END)
+                return true;
+        }
+        if (state.invoke.onError !== undefined) {
+            for (const t of state.invoke.onError) {
+                if (t.target === END)
+                    return true;
+            }
+        }
+        return false;
+    }
+    for (const transitions of Object.values(state.on)) {
+        const list = isReadonlyArray(transitions) ? transitions : [transitions];
+        for (const t of list) {
+            if (t.target === END)
+                return true;
+        }
+    }
+    return false;
+}
+function rewritePassiveTransition(t, endName) {
+    if (t.target !== END)
+        return t;
+    return { ...t, target: endName };
+}
+function rewriteOnDoneTransition(t, endName) {
+    if (t.target !== END)
+        return t;
+    return { ...t, target: endName };
+}
+function rewriteOnErrorTransition(t, endName) {
+    if (t.target !== END)
+        return t;
+    return { ...t, target: endName };
+}
+// Returns a new lowered state with every `target === END` rewritten to
+// `endName`. Non-END targets, `actions`, `guard`, and `reenter` flags are
+// preserved by reference. The input is not mutated.
+export function rewriteEndTargets(state, endName) {
+    if (isInvoke(state)) {
+        const onDone = state.invoke.onDone.map((t) => rewriteOnDoneTransition(t, endName));
+        const invoke = {
+            src: state.invoke.src,
+            input: state.invoke.input,
+            onDone,
+        };
+        if (state.invoke.onError !== undefined) {
+            invoke.onError = state.invoke.onError.map((t) => rewriteOnErrorTransition(t, endName));
+        }
+        return { invoke };
+    }
+    const on = {};
+    for (const [event, transitions] of Object.entries(state.on)) {
+        on[event] = isReadonlyArray(transitions)
+            ? transitions.map((t) => rewritePassiveTransition(t, endName))
+            : rewritePassiveTransition(transitions, endName);
+    }
+    return { on };
+}
+//# sourceMappingURL=injectEnd.js.map

package/dist/injectEnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectEnd.js","sourceRoot":"","sources":["../src/injectEnd.ts"],"names":[],"mappings":"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"}