@dna113p/machines 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,210 @@
+import { type AnyStateMachine, type SnapshotFrom, type StateValue } from "xstate";
+export interface Event {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+export type HumanOptions = {
+    readonly choices: readonly string[];
+    readonly suggestions?: never;
+} | {
+    readonly choices?: never;
+    readonly suggestions?: readonly string[];
+};
+export type HumanPrompt = string | (() => string);
+export interface HumanRequest {
+    readonly prompt: string;
+    readonly choices?: readonly string[];
+    readonly suggestions?: readonly string[];
+}
+export type HumanRunner = (request: HumanRequest) => string | Promise<string>;
+export interface AgentOptions {
+    readonly cwd?: string;
+    readonly using?: string;
+}
+export type AgentPrompt = string | (() => string);
+export interface AgentRequest {
+    readonly prompt: string;
+    readonly outcomes: readonly string[];
+    readonly cwd?: string;
+}
+interface AgentInvocation extends AgentRequest {
+    readonly using: string;
+}
+export type AgentUpdate = {
+    readonly type: "identity";
+    readonly harness: string;
+    readonly model?: string;
+    readonly thinking?: string;
+} | {
+    readonly type: "output";
+    readonly text: string;
+} | {
+    readonly type: "tool";
+    readonly id: string;
+    readonly title?: string;
+    readonly status?: "pending" | "in_progress" | "completed" | "failed";
+};
+export type AgentReporter = (update: AgentUpdate) => void;
+export type AgentRunner = (request: AgentRequest, report?: AgentReporter) => Event | Promise<Event>;
+export interface RunOptions {
+    readonly agents?: Readonly<Record<string, AgentRunner>>;
+    readonly human?: HumanRunner;
+    readonly onAgentUpdate?: AgentReporter;
+    readonly onHumanInput?: (active: boolean) => void;
+    readonly onState?: (state: StateValue) => void;
+}
+export declare const machine: <const TConfig extends import("xstate").MachineConfig<import("xstate").MachineContext, import("xstate").AnyEventObject, {
+    src: "agent";
+    logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "human";
+    logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "humanInputFinished";
+    params: unknown;
+} | {
+    type: "humanInputStarted";
+    params: unknown;
+}, never, never, string, import("xstate").NonReducibleUnknown, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject>, TResolvedChildren extends Record<string, string> = import("xstate").Cast<TConfig extends {
+    invoke: infer TInvoke;
+} ? TInvoke extends readonly (infer E)[] ? ((E extends {
+    id: infer TId extends string;
+    src: infer TSrc extends string;
+} ? { [K in TId]: TSrc; } : {}) extends infer T ? T extends (E extends {
+    id: infer TId extends string;
+    src: infer TSrc extends string;
+} ? { [K in TId]: TSrc; } : {}) ? T extends any ? (x: T) => void : never : never : never) extends (x: infer I) => void ? I : never : TInvoke extends {
+    id: infer TId extends string;
+    src: infer TSrc extends string;
+} ? { [K in TId]: TSrc; } : {} : {}, Record<string, string>>>(config: TConfig) => import("xstate").StateMachine<import("xstate").MachineContext, import("xstate").AnyEventObject | ([import("xstate").RoutableStateId<TConfig>] extends [never] ? never : {
+    type: 'xstate.route';
+    to: import("xstate").RoutableStateId<TConfig>;
+}), import("xstate").Cast<{ [A in {
+    src: "agent";
+    logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+    id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never;
+} | {
+    src: "human";
+    logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+    id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never;
+} as A["id"] extends infer T_4 ? T_4 extends A["id"] ? T_4 extends string ? string extends T_4 ? never : T_4 : never : never : never]?: import("xstate").ActorRefFromLogic<A["logic"]> | undefined; } & {
+    include: {
+        [id: string]: (((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never) extends infer T_4 ? T_4 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never) ? T_4 extends string ? string extends T_4 ? never : T_4 : never : never : never) extends never ? {
+            src: "agent";
+            logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+            id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never;
+        } : never) | (((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never) extends infer T_5 ? T_5 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never) ? T_5 extends string ? string extends T_5 ? never : T_5 : never : never : never) extends never ? {
+            src: "human";
+            logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+            id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never;
+        } : never) extends never ? import("xstate").AnyActorRef | undefined : (((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never) extends infer T_4 ? T_4 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never) ? T_4 extends string ? string extends T_4 ? never : T_4 : never : never : never) extends never ? {
+            src: "agent";
+            logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+            id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never;
+        } : never) | (((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never) extends infer T_5 ? T_5 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never) ? T_5 extends string ? string extends T_5 ? never : T_5 : never : never : never) extends never ? {
+            src: "human";
+            logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+            id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never;
+        } : never) extends any ? import("xstate").ActorRefFromLogic<((((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never) extends infer T_4 ? T_4 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never) ? T_4 extends string ? string extends T_4 ? never : T_4 : never : never : never) extends never ? {
+            src: "agent";
+            logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+            id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never;
+        } : never) | (((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never) extends infer T_5 ? T_5 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never) ? T_5 extends string ? string extends T_5 ? never : T_5 : never : never : never) extends never ? {
+            src: "human";
+            logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+            id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never;
+        } : never))["logic"]> | undefined : never;
+    };
+    exclude: unknown;
+}[(((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_6 ? T_6 extends "agent" ? T_6 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_6] & string : string | undefined : never : never) extends infer T_7 ? T_7 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_6 ? T_6 extends "agent" ? T_6 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_6] & string : string | undefined : never : never) ? T_7 extends string ? string extends T_7 ? never : T_7 : never : never : never) extends never ? {
+    src: "agent";
+    logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+    id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never;
+} : never) | (((import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_8 ? T_8 extends "human" ? T_8 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_8] & string : string | undefined : never : never) extends infer T_9 ? T_9 extends (import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_8 ? T_8 extends "human" ? T_8 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_8] & string : string | undefined : never : never) ? T_9 extends string ? string extends T_9 ? never : T_9 : never : never : never) extends never ? {
+    src: "human";
+    logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+    id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never;
+} : never) extends never ? "exclude" : "include"] extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never, Record<string, import("xstate").AnyActorRef | undefined>>, {
+    src: "agent";
+    logic: import("xstate").PromiseActorLogic<Event, AgentInvocation, import("xstate").EventObject>;
+    id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "agent" extends infer T_2 ? T_2 extends "agent" ? T_2 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_2] & string : string | undefined : never : never;
+} | {
+    src: "human";
+    logic: import("xstate").PromiseActorLogic<Event, HumanRequest, import("xstate").EventObject>;
+    id: import("xstate").IsNever<TResolvedChildren> extends true ? string | undefined : "human" extends infer T_3 ? T_3 extends "human" ? T_3 extends keyof import("xstate").Invert<TResolvedChildren> ? import("xstate").Invert<TResolvedChildren>[T_3] & string : string | undefined : never : never;
+}, {
+    type: "humanInputFinished";
+    params: unknown;
+} | {
+    type: "humanInputStarted";
+    params: unknown;
+}, never, never, import("xstate").ToStateValue<TConfig>, string, import("xstate").NonReducibleUnknown, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, { -readonly [K in keyof TConfig as K & ("id" | "states")]: K extends "states" ? { [SK in keyof TConfig["states"]]: NonNullable<TConfig["states"][SK]> extends infer T_10 extends import("xstate").StateSchema ? { -readonly [K_1 in keyof T_10 as K_1 & ("id" | "states")]: K_1 extends "states" ? { [SK_1 in keyof T_10["states"]]: NonNullable<T_10["states"][SK_1]> extends infer T_11 extends import("xstate").StateSchema ? { -readonly [K_2 in keyof T_11 as K_2 & ("id" | "states")]: K_2 extends "states" ? { [SK_2 in keyof T_11["states"]]: NonNullable<T_11["states"][SK_2]> extends infer T_12 extends import("xstate").StateSchema ? { -readonly [K_3 in keyof T_12 as K_3 & ("id" | "states")]: K_3 extends "states" ? { [SK_3 in keyof T_12["states"]]: NonNullable<T_12["states"][SK_3]> extends infer T_13 extends import("xstate").StateSchema ? { -readonly [K_4 in keyof T_13 as K_4 & ("id" | "states")]: K_4 extends "states" ? { [SK_4 in keyof T_13["states"]]: NonNullable<T_13["states"][SK_4]> extends infer T_14 extends import("xstate").StateSchema ? { -readonly [K_5 in keyof T_14 as K_5 & ("id" | "states")]: K_5 extends "states" ? { [SK_5 in keyof T_14["states"]]: NonNullable<T_14["states"][SK_5]> extends infer T_15 extends import("xstate").StateSchema ? { -readonly [K_6 in keyof T_15 as K_6 & ("id" | "states")]: K_6 extends "states" ? { [SK_6 in keyof T_15["states"]]: NonNullable<T_15["states"][SK_6]> extends infer T_16 extends import("xstate").StateSchema ? { -readonly [K_7 in keyof T_16 as K_7 & ("id" | "states")]: K_7 extends "states" ? { [SK_7 in keyof T_16["states"]]: NonNullable<T_16["states"][SK_7]> extends infer T_17 extends import("xstate").StateSchema ? { -readonly [K_8 in keyof T_17 as K_8 & ("id" | "states")]: K_8 extends "states" ? { [SK_8 in keyof T_17["states"]]: NonNullable<T_17["states"][SK_8]> extends infer T_18 extends import("xstate").StateSchema ? { -readonly [K_9 in keyof T_18 as K_9 & ("id" | "states")]: K_9 extends "states" ? { [SK_9 in keyof T_18["states"]]: NonNullable<T_18["states"][SK_9]> extends infer T_19 extends import("xstate").StateSchema ? { -readonly [K_10 in keyof T_19 as K_10 & ("id" | "states")]: K_10 extends "states" ? { [SK_10 in keyof T_19["states"]]: /*elided*/ any; } : T_19[K_10]; } : never; } : T_18[K_9]; } : never; } : T_17[K_8]; } : never; } : T_16[K_7]; } : never; } : T_15[K_6]; } : never; } : T_14[K_5]; } : never; } : T_13[K_4]; } : never; } : T_12[K_3]; } : never; } : T_11[K_2]; } : never; } : T_10[K_1]; } : never; } : TConfig[K]; }>;
+export declare function operation<const TTransitions extends Readonly<Record<string, unknown>>>(runOperation: () => Event | Promise<Event>, on: TTransitions): {
+    readonly invoke: {
+        readonly src: import("xstate").PromiseActorLogic<Event, import("xstate").NonReducibleUnknown, import("xstate").EventObject>;
+        readonly onDone: {
+            readonly actions: readonly [(args: unknown) => void, import("xstate").ActionFunction<any, any, Event, undefined, never, never, never, never, never>];
+        };
+        readonly onError: {
+            readonly actions: (args: unknown) => never;
+        };
+    };
+    readonly on: TTransitions;
+};
+export declare function human<const TTransitions extends Readonly<Record<string, unknown>>>(prompt: HumanPrompt, on: TTransitions, options?: HumanOptions): {
+    readonly entry: "humanInputStarted";
+    readonly exit: "humanInputFinished";
+    readonly invoke: {
+        readonly src: "human";
+        readonly input: () => {
+            prompt: string;
+            choices?: readonly string[] | undefined;
+            suggestions?: readonly string[] | undefined;
+        };
+        readonly onDone: {
+            readonly actions: readonly [(args: unknown) => void, import("xstate").ActionFunction<any, any, Event, undefined, never, never, never, never, never>];
+        };
+        readonly onError: {
+            readonly actions: (args: unknown) => never;
+        };
+    };
+    readonly on: TTransitions;
+};
+export declare function agent<const TTransitions extends Readonly<Record<string, unknown>>>(prompt: AgentPrompt, on: TTransitions, options?: AgentOptions): {
+    readonly meta: {
+        readonly "machines.agent": {
+            readonly using: string;
+        };
+    };
+    readonly invoke: {
+        readonly src: "agent";
+        readonly input: () => {
+            using: string;
+            prompt: string;
+            outcomes: string[];
+            cwd?: string | undefined;
+        };
+        readonly onDone: {
+            readonly actions: readonly [(args: unknown) => void, import("xstate").ActionFunction<any, any, Event, undefined, never, never, never, never, never>];
+        };
+        readonly onError: {
+            readonly actions: (args: unknown) => never;
+        };
+    };
+    readonly on: TTransitions;
+};
+export declare function final(): {
+    readonly type: "final";
+};
+export interface MachinePrimitives {
+    readonly agent: typeof agent;
+    readonly final: typeof final;
+    readonly human: typeof human;
+    readonly machine: typeof machine;
+    readonly operation: typeof operation;
+}
+export declare function requiredAgentNames(definition: AnyStateMachine): readonly string[];
+export declare function run<TMachine extends AnyStateMachine>(definition: TMachine, options?: RunOptions): Promise<SnapshotFrom<TMachine>>;
+export {};

package/dist/src/index.js

@@ -0,0 +1,204 @@
+import { terminalHuman } from "./terminal-human.js";
+import { createActor, fromPromise, raise, setup, } from "xstate";
+const machines = setup({
+    actions: {
+        humanInputFinished: () => { },
+        humanInputStarted: () => { },
+    },
+    actors: {
+        agent: fromPromise(async () => {
+            throw new Error("This Machine reached an Agent state, but no Agent runner was supplied");
+        }),
+        human: fromPromise(async ({ input }) => submittedHumanEvent(input, terminalHuman)),
+    },
+});
+const agentMetaKey = "machines.agent";
+export const machine = machines.createMachine;
+export function operation(runOperation, on) {
+    return {
+        invoke: {
+            src: fromPromise(async () => runOperation()),
+            ...actorLifecycle("Operation", on),
+        },
+        on,
+    };
+}
+export function human(prompt, on, options = {}) {
+    if (options.choices !== undefined && options.choices.length === 0) {
+        throw new Error("Human choices must include at least one value");
+    }
+    return {
+        entry: "humanInputStarted",
+        exit: "humanInputFinished",
+        invoke: {
+            src: "human",
+            input: () => ({
+                prompt: typeof prompt === "function" ? prompt() : prompt,
+                ...(options.choices === undefined ? {} : { choices: options.choices }),
+                ...(options.suggestions === undefined
+                    ? {}
+                    : { suggestions: options.suggestions }),
+            }),
+            ...actorLifecycle("Human", on),
+        },
+        on,
+    };
+}
+export function agent(prompt, on, options = {}) {
+    const using = options.using ?? "default";
+    if (typeof using !== "string" || using.trim() === "" || using !== using.trim()) {
+        throw new Error("Agent runner name must be a non-empty trimmed string");
+    }
+    return {
+        meta: {
+            [agentMetaKey]: { using },
+        },
+        invoke: {
+            src: "agent",
+            input: () => ({
+                using,
+                prompt: typeof prompt === "function" ? prompt() : prompt,
+                outcomes: Object.keys(on),
+                ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            }),
+            ...actorLifecycle("Agent", on),
+        },
+        on,
+    };
+}
+function actorLifecycle(actorName, on) {
+    return {
+        onDone: {
+            actions: [
+                (args) => {
+                    const { event, self } = args;
+                    assertHandledEvent(actorName, event.output, on, self.getSnapshot().value);
+                },
+                raise(({ event }) => event.output),
+            ],
+        },
+        onError: {
+            actions: (args) => {
+                const { event, self } = args;
+                throw actorError(actorName, event.error, self.getSnapshot().value);
+            },
+        },
+    };
+}
+async function submittedHumanEvent(request, runner) {
+    // XState can start an initial invoked actor before its parent's entry actions.
+    // Let onHumanInput(true) release terminal hotkeys before the runner takes stdin.
+    const answer = await Promise.resolve().then(() => runner(request));
+    if (typeof answer !== "string") {
+        throw new Error("Human runner must return a string");
+    }
+    if (request.choices !== undefined && !request.choices.includes(answer)) {
+        throw new Error(`Expected one of: ${request.choices.join(", ")}`);
+    }
+    return { type: "submitted", value: answer };
+}
+export function final() {
+    return { type: "final" };
+}
+export function requiredAgentNames(definition) {
+    const names = new Set();
+    collectAgentNames(definition.config, names);
+    return [...names].sort((left, right) => left.localeCompare(right));
+}
+export function run(definition, options = {}) {
+    return new Promise((resolve, reject) => {
+        const agentRunners = options.agents ?? {};
+        assertAgentRunners(agentRunners);
+        assertRequiredAgentRunners(definition, agentRunners);
+        const runnable = definition.provide({
+            actions: {
+                humanInputFinished: () => options.onHumanInput?.(false),
+                humanInputStarted: () => options.onHumanInput?.(true),
+            },
+            actors: {
+                human: fromPromise(async ({ input }) => submittedHumanEvent(input, options.human ?? terminalHuman)),
+                ...(Object.keys(agentRunners).length === 0
+                    ? {}
+                    : {
+                        agent: fromPromise(async ({ input }) => {
+                            const { using, ...request } = input;
+                            const runner = agentRunners[using];
+                            if (runner === undefined) {
+                                throw new Error(`Agent runner "${using}" was not supplied`);
+                            }
+                            return runner(request, options.onAgentUpdate);
+                        }),
+                    }),
+            },
+        });
+        const actor = createActor(runnable);
+        const initialValue = actor.getSnapshot().value;
+        let previousState = JSON.stringify(initialValue);
+        actor.subscribe({
+            next: (snapshot) => {
+                const value = snapshot.value;
+                const state = JSON.stringify(value);
+                if (state === previousState)
+                    return;
+                previousState = state;
+                options.onState?.(value);
+            },
+            complete: () => resolve(actor.getSnapshot()),
+            error: reject,
+        });
+        options.onState?.(initialValue);
+        actor.start();
+    });
+}
+function collectAgentNames(value, names) {
+    if (value === null || typeof value !== "object")
+        return;
+    const state = value;
+    const metadata = state.meta?.[agentMetaKey];
+    if (metadata !== null
+        && typeof metadata === "object"
+        && "using" in metadata
+        && typeof metadata.using === "string") {
+        names.add(metadata.using);
+    }
+    if (state.states !== undefined) {
+        for (const child of Object.values(state.states))
+            collectAgentNames(child, names);
+    }
+}
+function assertAgentRunners(runners) {
+    for (const [name, runner] of Object.entries(runners)) {
+        if (name.trim() === "" || name !== name.trim()) {
+            throw new Error("Agent runner names must be non-empty trimmed strings");
+        }
+        if (typeof runner !== "function") {
+            throw new Error(`Agent runner "${name}" must be a function`);
+        }
+    }
+}
+function assertRequiredAgentRunners(definition, runners) {
+    const missing = requiredAgentNames(definition)
+        .filter((name) => !Object.hasOwn(runners, name));
+    if (missing.length === 0)
+        return;
+    const noun = missing.length === 1 ? "runner" : "runners";
+    throw new Error(`Machine requires missing Agent ${noun}: ${missing.join(", ")}`);
+}
+function assertHandledEvent(actorName, event, transitions, state) {
+    if (event === null
+        || typeof event !== "object"
+        || !("type" in event)
+        || typeof event.type !== "string") {
+        throw new Error(`${actorName} in state "${formatState(state)}" returned an invalid event`);
+    }
+    if (!Object.hasOwn(transitions, event.type)) {
+        throw new Error(`State "${formatState(state)}" does not handle event "${event.type}"`);
+    }
+}
+function actorError(actorName, cause, state) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new Error(`${actorName} failed in state "${formatState(state)}": ${message}`, { cause });
+}
+function formatState(state) {
+    return typeof state === "string" ? state : JSON.stringify(state);
+}

package/dist/src/launcher.d.ts

@@ -0,0 +1,19 @@
+import type { AnyStateMachine, SnapshotFrom } from "xstate";
+import { type LauncherLocation, type MachineSummary, type AgentPresetSummary } from "./catalog.ts";
+export type { LauncherLocation, MachineSummary, AgentPresetSummary } from "./catalog.ts";
+import { type RunOptions } from "./index.ts";
+export interface PrepareMachineRunOptions extends LauncherLocation {
+    readonly machine: string;
+    readonly input?: string;
+    readonly agents?: Readonly<Record<string, string>>;
+}
+export interface PreparedMachineRun {
+    readonly name: string;
+    readonly description: string;
+    readonly path: string;
+    readonly agentRoles: Readonly<Record<string, string>>;
+    start(options?: Omit<RunOptions, "agents">): Promise<SnapshotFrom<AnyStateMachine>>;
+}
+export declare function listMachines(location?: LauncherLocation): Promise<readonly MachineSummary[]>;
+export declare function listAgentPresets(location?: LauncherLocation): Promise<readonly AgentPresetSummary[]>;
+export declare function prepareMachineRun(options: PrepareMachineRunOptions): Promise<PreparedMachineRun>;

package/dist/src/launcher.js

@@ -0,0 +1,98 @@
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { configuredAgentPresets } from "./catalog.js";
+import { queryCatalog } from "./discovery-worker.js";
+import { loadMachineModule, readAgentRoles, requireMachineDescription } from "./machine-module.js";
+import { discoverMachines, machinesUserHome } from "./discovery.js";
+import { agent, final, human, machine, operation, requiredAgentNames, run, } from "./index.js";
+export async function listMachines(location = {}) {
+    return queryCatalog("machines", location);
+}
+export async function listAgentPresets(location = {}) {
+    return queryCatalog("agents", location);
+}
+export async function prepareMachineRun(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const home = options.home ?? machinesUserHome();
+    const path = await resolveMachine(options.machine, cwd, home);
+    const loaded = await loadMachineModule(path);
+    const description = requireMachineDescription(loaded, path);
+    const agentRoles = readAgentRoles(loaded, path);
+    if (typeof loaded.default !== "function") {
+        throw new Error(`Machine "${path}" must default-export a factory`);
+    }
+    const definition = await loaded.default({ agent, final, human, machine, operation }, options.input ?? "");
+    const configured = await configuredAgentPresets(cwd, home);
+    const usedAgentRoles = requiredAgentNames(definition);
+    const agents = applyAgentOverrides(path, configured.agents, configured.presets, new Set([...usedAgentRoles, ...Object.keys(agentRoles)]), options.agents ?? {});
+    preflightAgentRoles(path, usedAgentRoles, agentRoles, agents);
+    let started = false;
+    return {
+        name: machineName(path),
+        description,
+        path,
+        agentRoles,
+        start(runOptions = {}) {
+            if (started)
+                throw new Error(`Prepared Machine "${path}" has already started`);
+            started = true;
+            return run(definition, { ...runOptions, agents });
+        },
+    };
+}
+async function resolveMachine(selector, cwd, home) {
+    if (isAbsolute(selector) || selector.includes("/") || selector.endsWith(".ts")) {
+        return resolve(cwd, selector);
+    }
+    const machines = await discoverMachines(cwd, home);
+    const found = machines.find((candidate) => candidate.name === selector);
+    if (found === undefined) {
+        throw new Error(`Machine "${selector}" not found. Run "machine list" to see available Machines.`);
+    }
+    return found.path;
+}
+function applyAgentOverrides(machinePath, agents, presets, requiredRoles, overrides) {
+    const resolved = { ...agents };
+    for (const [role, presetName] of Object.entries(overrides)) {
+        if (role.trim() === "" || role !== role.trim()) {
+            throw new Error("Agent override roles must be non-empty trimmed strings");
+        }
+        if (presetName.trim() === "" || presetName !== presetName.trim()) {
+            throw new Error(`Agent override for role "${role}" must name a preset`);
+        }
+        if (!requiredRoles.has(role)) {
+            throw new Error(`Machine "${machinePath}" does not declare or use Agent role "${role}"`);
+        }
+        const selected = Object.hasOwn(presets, presetName) ? presets[presetName] : undefined;
+        if (selected === undefined) {
+            const available = Object.keys(presets).sort().join(", ");
+            throw new Error(`Agent preset "${presetName}" was not found for role "${role}". Available presets: ${available}`);
+        }
+        resolved[role] = selected.runner;
+    }
+    return resolved;
+}
+function preflightAgentRoles(machinePath, usedNames, declaredRoles, agents) {
+    const undeclared = usedNames.filter((name) => name !== "default" && !Object.hasOwn(declaredRoles, name));
+    if (undeclared.length > 0) {
+        throw new Error(`Machine "${machinePath}" uses undeclared Agent roles: ${undeclared.join(", ")}`);
+    }
+    const required = new Set([...usedNames, ...Object.keys(declaredRoles)]);
+    const missing = [...required].filter((name) => !Object.hasOwn(agents, name));
+    if (missing.length === 0)
+        return;
+    const lines = missing.map((name) => {
+        const description = declaredRoles[name];
+        return description === undefined ? `- ${name}` : `- ${name}: ${description}`;
+    });
+    throw new Error([
+        `Machine "${machinePath}" is missing required Agent runners:`,
+        ...lines,
+        "Configure them in ~/.machines/agents.ts or the nearest project .machines/agents.ts.",
+    ].join("\n"));
+}
+function machineName(path) {
+    const fileName = basename(path);
+    return fileName === "index.ts"
+        ? basename(dirname(path))
+        : fileName.replace(/\.ts$/u, "");
+}

package/dist/src/machine-module.d.ts

@@ -0,0 +1,3 @@
+export declare function loadMachineModule(machinePath: string): Promise<Record<string, unknown>>;
+export declare function requireMachineDescription(loaded: Record<string, unknown>, machinePath: string): string;
+export declare function readAgentRoles(loaded: Record<string, unknown>, machinePath: string): Readonly<Record<string, string>>;

package/dist/src/machine-module.js

@@ -0,0 +1,55 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { pathToFileURL } from "node:url";
+export async function loadMachineModule(machinePath) {
+    try {
+        return await import(__rewriteRelativeImportExtension(pathToFileURL(machinePath).href));
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new Error(`Could not load Machine "${machinePath}": ${message}`, { cause });
+    }
+}
+export function requireMachineDescription(loaded, machinePath) {
+    const { description } = loaded;
+    if (description === undefined) {
+        throw new Error(`Machine "${machinePath}" must export a description`);
+    }
+    if (typeof description !== "string" || description.trim() === "") {
+        throw new Error(`Machine "${machinePath}" description must be a non-empty string`);
+    }
+    const value = description.trim();
+    if (/\r|\n|\t/u.test(value)) {
+        throw new Error(`Machine "${machinePath}" description must fit in one tab-safe line`);
+    }
+    return value;
+}
+export function readAgentRoles(loaded, machinePath) {
+    const { agentRoles } = loaded;
+    if (agentRoles === undefined)
+        return {};
+    if (agentRoles === null || typeof agentRoles !== "object" || Array.isArray(agentRoles)) {
+        throw new Error(`Machine "${machinePath}" agentRoles must be an object`);
+    }
+    const roles = {};
+    for (const [name, description] of Object.entries(agentRoles)) {
+        if (name.trim() === "" || name !== name.trim()) {
+            throw new Error(`Machine "${machinePath}" contains a non-trimmed or empty Agent role name`);
+        }
+        if (typeof description !== "string" || description.trim() === "") {
+            throw new Error(`Agent role "${name}" in "${machinePath}" must have a description`);
+        }
+        const value = description.trim();
+        if (/\r|\n|\t/u.test(value)) {
+            throw new Error(`Agent role "${name}" in "${machinePath}" must fit in one line`);
+        }
+        roles[name] = value;
+    }
+    return roles;
+}

package/dist/src/session.d.ts

@@ -0,0 +1,40 @@
+import type { StateValue } from "xstate";
+import { type HostedHumanRequest } from "./host.ts";
+import type { AgentUpdate } from "./index.ts";
+import type { PrepareMachineRunOptions } from "./launcher.ts";
+export type RunStatus = "running" | "waiting" | "completed" | "failed";
+export interface RunSnapshot {
+    readonly id: string;
+    readonly machine: string;
+    readonly description: string;
+    readonly path: string;
+    readonly cwd: string;
+    readonly status: RunStatus;
+    readonly state?: StateValue;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+    readonly elapsedSeconds: number;
+    readonly agent?: Extract<AgentUpdate, {
+        type: "identity";
+    }>;
+    readonly human?: HostedHumanRequest;
+    readonly error?: string;
+}
+export interface SessionEvent {
+    readonly type: "updated" | "human" | "finished";
+    readonly run: RunSnapshot;
+}
+/** Owns runs from startup to disposal. Presentation belongs to its subscribers. */
+export declare class MachineSession {
+    #private;
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    start(options: PrepareMachineRunOptions): Promise<RunSnapshot>;
+    status(runId?: string): RunSnapshot[];
+    respond(input: {
+        readonly runId: string;
+        readonly requestId: string;
+        readonly response: string;
+    }): Promise<RunSnapshot>;
+    close(): void;
+}
+export declare function isActive(status: RunStatus): boolean;