@dna113p/machines 0.1.0

package/dist/src/session.js

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { startMachineHost } from "./host.js";
+/** Owns runs from startup to disposal. Presentation belongs to its subscribers. */
+export class MachineSession {
+    #runs = new Map();
+    #starting = new Set();
+    #listeners = new Set();
+    #closed = false;
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    async start(options) {
+        if (this.#closed)
+            throw new Error("Machine session is closed");
+        const cancellation = new AbortController();
+        this.#starting.add(cancellation);
+        const id = randomUUID();
+        const startedAt = Date.now();
+        const update = (type, change) => {
+            const run = this.#runs.get(id);
+            if (run === undefined || !isActive(run.status))
+                return;
+            change(run);
+            run.updatedAt = Date.now();
+            this.#emit(type, run);
+        };
+        let host;
+        try {
+            host = await startMachineHost({
+                ...options,
+                signal: cancellation.signal,
+                onState: (state) => update("updated", (run) => {
+                    if (JSON.stringify(run.state) !== JSON.stringify(state))
+                        run.agent = undefined;
+                    run.state = state;
+                }),
+                onAgentUpdate: (agent) => {
+                    if (agent.type === "identity")
+                        update("updated", (run) => { run.agent = agent; });
+                },
+                onHumanRequest: (request) => update("human", (run) => {
+                    run.status = "waiting";
+                    run.human = request;
+                }),
+            });
+        }
+        finally {
+            this.#starting.delete(cancellation);
+        }
+        if (this.#closed) {
+            host.terminate();
+            throw new Error("Machine session is closed");
+        }
+        const run = {
+            id,
+            cwd: options.cwd ?? process.cwd(),
+            host,
+            startedAt,
+            updatedAt: Date.now(),
+            status: "running",
+        };
+        this.#runs.set(id, run);
+        void host.result.then(({ state }) => this.#finish(run, { state }), (cause) => this.#finish(run, { error: errorMessage(cause) }));
+        this.#emit("updated", run);
+        return snapshot(run);
+    }
+    status(runId) {
+        const runs = runId === undefined
+            ? [...this.#runs.values()].sort((left, right) => right.updatedAt - left.updatedAt)
+            : [this.#requireRun(runId)];
+        return runs.map(snapshot);
+    }
+    async respond(input) {
+        const run = this.#requireRun(input.runId);
+        if (run.status !== "waiting" || run.human === undefined) {
+            throw new Error(`Machine run "${input.runId}" is not waiting for Human input`);
+        }
+        if (run.human.requestId !== input.requestId) {
+            throw new Error("Machine Human request is stale; read the current requestId");
+        }
+        if (run.human.choices !== undefined && !run.human.choices.includes(input.response)) {
+            throw new Error(`Expected one of: ${run.human.choices.join(", ")}`);
+        }
+        // Claim synchronously in the session as well as in the host. New requests or
+        // terminal events arriving during IPC must never be overwritten by this reply.
+        run.status = "running";
+        run.human = undefined;
+        run.updatedAt = Date.now();
+        const sent = run.host.respond(input.response, input.requestId);
+        this.#emit("updated", run);
+        await sent;
+        return snapshot(run);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#listeners.clear();
+        for (const cancellation of this.#starting)
+            cancellation.abort();
+        this.#starting.clear();
+        for (const run of this.#runs.values())
+            run.host.terminate();
+        this.#runs.clear();
+    }
+    #requireRun(id) {
+        const run = this.#runs.get(id);
+        if (run === undefined)
+            throw new Error(`Machine run "${id}" not found in this session`);
+        return run;
+    }
+    #finish(run, outcome) {
+        if (this.#closed || !isActive(run.status))
+            return;
+        run.status = "state" in outcome ? "completed" : "failed";
+        if ("state" in outcome)
+            run.state = outcome.state;
+        else
+            run.error = outcome.error;
+        run.human = undefined;
+        run.agent = undefined;
+        run.updatedAt = Date.now();
+        const terminal = [...this.#runs.values()]
+            .filter((item) => !isActive(item.status))
+            .sort((left, right) => right.updatedAt - left.updatedAt);
+        for (const item of terminal.slice(5))
+            this.#runs.delete(item.id);
+        this.#emit("finished", run);
+    }
+    #emit(type, run) {
+        for (const listener of this.#listeners) {
+            try {
+                listener({ type, run: snapshot(run) });
+            }
+            catch (cause) {
+                // Rendering and notifications cannot change the outcome of an owned run.
+                process.emitWarning(errorMessage(cause), { type: "MachineSessionObserverError" });
+            }
+        }
+    }
+}
+export function isActive(status) {
+    return status === "running" || status === "waiting";
+}
+function snapshot(run) {
+    return {
+        id: run.id,
+        machine: run.host.name,
+        description: run.host.description,
+        path: run.host.path,
+        cwd: run.cwd,
+        status: run.status,
+        ...(run.state === undefined ? {} : { state: structuredClone(run.state) }),
+        startedAt: new Date(run.startedAt).toISOString(),
+        updatedAt: new Date(run.updatedAt).toISOString(),
+        elapsedSeconds: Math.floor(((isActive(run.status) ? Date.now() : run.updatedAt) - run.startedAt) / 1_000),
+        ...(run.agent === undefined ? {} : { agent: { ...run.agent } }),
+        ...(run.human === undefined ? {} : { human: structuredClone(run.human) }),
+        ...(run.error === undefined ? {} : { error: run.error }),
+    };
+}
+function errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/src/terminal-human.d.ts

@@ -0,0 +1,2 @@
+import type { HumanRequest } from "./index.ts";
+export declare function terminalHuman(request: HumanRequest): Promise<string>;

package/dist/src/terminal-human.js

@@ -0,0 +1,100 @@
+import { clearScreenDown, createInterface, cursorTo, emitKeypressEvents, moveCursor, } from "node:readline";
+import { cyan, dim, green } from "yoctocolors";
+export function terminalHuman(request) {
+    const values = request.choices ?? request.suggestions ?? [];
+    const allowOther = request.suggestions !== undefined;
+    if (values.length > 0
+        && process.stdin.isTTY
+        && process.stdout.isTTY
+        && typeof process.stdin.setRawMode === "function") {
+        return selectHumanInput(request.prompt, values, allowOther);
+    }
+    return readFreeformInput(request.prompt, values, allowOther ? "Suggestions" : "Choices");
+}
+function readFreeformInput(prompt, values = [], heading = "Suggestions") {
+    const terminal = createInterface({ input: process.stdin, output: process.stdout });
+    const suggestionText = values.length === 0
+        ? ""
+        : `\n${heading}:\n${values.map((value) => `- ${value}`).join("\n")}`;
+    return new Promise((resolve, reject) => {
+        let answered = false;
+        terminal.once("close", () => {
+            if (!answered)
+                reject(new Error("Terminal input closed before a response"));
+        });
+        terminal.question(`${prompt}${suggestionText}\n> `, (answer) => {
+            answered = true;
+            terminal.close();
+            resolve(answer);
+        });
+    });
+}
+function selectHumanInput(prompt, values, allowOther) {
+    return new Promise((resolve, reject) => {
+        const choices = allowOther ? [...values, "Other…"] : [...values];
+        const initialRawMode = process.stdin.isRaw;
+        let selected = 0;
+        let renderedLines = 0;
+        function clearMenu() {
+            if (renderedLines === 0)
+                return;
+            moveCursor(process.stdout, 0, -renderedLines);
+            cursorTo(process.stdout, 0);
+            clearScreenDown(process.stdout);
+            renderedLines = 0;
+        }
+        function render() {
+            clearMenu();
+            const lines = choices.map((choice, index) => (index === selected ? `${cyan("❯")} ${cyan(choice)}` : `  ${choice}`));
+            lines.push(dim("↑↓ select · enter confirm"));
+            process.stdout.write(`${lines.join("\n")}\n`);
+            renderedLines = lines.length;
+        }
+        function cleanup() {
+            process.stdin.off("keypress", onKeypress);
+            process.stdin.off("end", onInputClosed);
+            process.stdin.off("close", onInputClosed);
+            process.stdin.setRawMode(initialRawMode ?? false);
+            if (!initialRawMode)
+                process.stdin.pause();
+        }
+        function onInputClosed() {
+            cleanup();
+            reject(new Error("Terminal input closed before a response"));
+        }
+        function onKeypress(_character, key) {
+            if (key.ctrl && key.name === "c") {
+                clearMenu();
+                cleanup();
+                process.kill(process.pid, "SIGINT");
+            }
+            else if (key.name === "up" || key.name === "down") {
+                const direction = key.name === "up" ? -1 : 1;
+                selected = (selected + direction + choices.length) % choices.length;
+                render();
+            }
+            else if (key.name === "return" || key.name === "enter") {
+                const answer = choices[selected];
+                if (answer === undefined)
+                    return;
+                clearMenu();
+                cleanup();
+                if (!allowOther || selected < values.length) {
+                    process.stdout.write(`${green("✔")} ${answer}\n`);
+                    resolve(answer);
+                }
+                else {
+                    void readFreeformInput("Feedback").then(resolve, reject);
+                }
+            }
+        }
+        process.stdout.write(`${prompt}\n\n`);
+        emitKeypressEvents(process.stdin);
+        process.stdin.setRawMode(true);
+        process.stdin.on("keypress", onKeypress);
+        process.stdin.once("end", onInputClosed);
+        process.stdin.once("close", onInputClosed);
+        process.stdin.resume();
+        render();
+    });
+}

package/docs/architecture.md

@@ -0,0 +1,111 @@
+# Architecture
+
+Machines separates workflow decisions from execution and presentation. A Machine
+can say “review after implementation” without knowing whether an Agent uses ACP,
+a Human uses a terminal, or a run is displayed in Codex.
+
+## Vocabulary and ownership
+
+| Concept | Responsibility |
+| --- | --- |
+| Machine | Finite-state policy mapping returned events to the next state |
+| State | Named position invoking one Agent, Human, or Operation, or a final state |
+| Agent | Bounded request implemented by an `AgentRunner` |
+| Operation | Trusted local function returning an event |
+| Human | Input request returning a `submitted` event with the response |
+| Run | One execution of a Machine |
+| Adapter | Mechanism connecting a primitive or run to an external interface |
+
+XState owns transitions and actor lifecycle. Each primitive returns a semantic
+event; the active state declares its accepted event types. Adapters return events
+and report observations. Destination states stay in the Machine definition.
+
+Workflow-specific retries, escalation, approval, merging, and cleanup belong in
+Machines. Add shared runtime behavior when multiple real workflows require the
+same mechanism and cannot reasonably own it themselves.
+
+## Module boundaries
+
+```text
+CLI ──────────────────────→ launcher → runtime → AgentRunner / HumanRunner
+Pi extension ──┐                          ↑
+               ├─→ session → child host ─┘
+MCP server ────┘       ↑
+                      └── snapshots and notifications → adapter presentation
+```
+
+| Module | Owns |
+| --- | --- |
+| `src/index.ts` | Typed primitives, Machine validation, XState execution, observer contracts |
+| `src/terminal-human.ts` | Default terminal Human input, selectors, raw-mode restoration |
+| `src/machine-module.ts` | Shared module contract and metadata validation |
+| `src/catalog.ts` | Definition and preset catalog reads |
+| `src/acp.ts` | ACP process/session protocol, bounded Agent result, normalized activity |
+| `src/discovery.ts` | Project/global definition locations and precedence |
+| `src/launcher.ts` | Definition metadata, Agent bindings, preflight, single-use launch preparation |
+| `src/discovery-worker.ts` | Fresh metadata imports in disposable workers |
+| `src/host.ts` | One child run, IPC, Human request identity, owned process termination |
+| `src/session.ts` | Shared Pi/MCP run lifecycle, snapshots, response handling, retention, shutdown |
+| `src/cli.ts` | Command parsing, terminal progress, source inspection |
+| `pi-extension/index.ts` | Pi tools, widgets, notifications, native input presentation |
+| `mcp/server.ts` | MCP schemas, tool results, and the optional HTML resource |
+| `codex/machines/ui/machines.html` | Status rendering and submission of the current Human request |
+
+## Discovery and launch
+
+Discovery combines the nearest project directory with the global directory. Each
+listing uses a disposable worker so edits to definitions, presets, and imported
+helpers are visible without restarting the interface. An invalid definition has
+an `error` in its listing; valid definitions remain available. The CLI displays
+all entries and exits unsuccessfully if any definition is invalid.
+
+Workers isolate module caches and ordinary output, not file or network permissions.
+Importing metadata still executes code. Definition factories run during launch
+preparation, so side effects that require a successful preflight belong inside an
+Operation rather than the factory.
+
+The launcher resolves required semantic Agent roles and configured presets before
+starting the actor. Missing bindings, invalid overrides, or invalid definitions
+fail preflight. The resulting prepared run can be started once. Long-lived hosted
+runs get a fresh child process; direct runtime users own their own definitions.
+
+## Session and process lifecycle
+
+Pi and MCP delegate to the same session module. The session owns hosts from the
+start of launch, keeps authoritative snapshots, and closes permanently. Presentation
+adapters subscribe to changes and format them for their own surfaces.
+
+Each pending Human prompt has a unique request ID. A response names both the run
+and that request. Claiming a request before asynchronous delivery prevents two
+answers from being accepted, and the identity prevents a stale card or dialog from
+answering a later prompt. Restricted choices are validated for every interface.
+
+Closing a session terminates active and starting hosts. Host termination includes
+ordinary descendants in the host's owned process group on POSIX and process-tree
+termination on Windows. Deliberately detached processes can escape normal ownership;
+Machines should await work they own and avoid launching untracked background jobs.
+Abrupt operating-system termination cannot guarantee cleanup. Stopping processes
+also cannot reverse a completed external action.
+The automated process-lifecycle checks run on Linux; the Windows termination path
+has not been exercised in this environment.
+
+Human drafts and focus belong to the presentation adapter while the request ID is
+unchanged. The card polls authoritative status; it does not decide transitions or
+persist a second copy of the workflow state.
+
+## Distribution
+
+Development runs source TypeScript on Node 24. `npm run build` emits JavaScript and
+declarations under `dist/`, rewrites relative TypeScript import extensions, and
+copies UI assets at the same relative paths used by the server. The npm package
+exports built entry points so runtime loading works inside `node_modules`.
+
+`npm run build:plugin` assembles a self-contained directory with built code, UI,
+authoring instructions, and production dependencies. It needs Node on PATH but
+has no dependency on the source checkout after copying. Packaging smoke tests
+exercise a real installed tarball and a relocated plugin, including discovery,
+the MCP widget resource, and a hosted Human response.
+
+The earlier implementation plans are retained in the repository's
+[history directory](https://github.com/dna113p/machines/tree/main/docs/history) for rationale.
+Their phase ordering and manual proof gates describe past work.

package/docs/authoring.md

@@ -0,0 +1,193 @@
+# Authoring Machines
+
+## Definition contract
+
+Store a workflow in `.machines/name.ts` or `.machines/name/index.ts` in the project.
+The [README quickstart](../README.md#run-your-own-workflows) is a complete minimal
+definition. Export a non-empty, one-line `description` and a default factory:
+
+```ts
+import type { MachinePrimitives } from "@dna113p/machines";
+
+export const description = "Prints a supplied message after a Human confirms it.";
+
+export default function printMessage(
+  { machine, operation, human, final }: MachinePrimitives,
+  input: string,
+) {
+  return machine({
+    initial: "confirm",
+    states: {
+      confirm: human(`Print ${JSON.stringify(input)}?`, {
+        submitted: "print",
+      }, { choices: ["print"] }),
+      print: operation(() => {
+        console.log(input);
+        return { type: "completed" };
+      }, { completed: "done" }),
+      done: final(),
+    },
+  });
+}
+```
+
+Factories receive primitives, so workflow execution need not resolve the runtime
+package from a global `~/.machines/` folder. A type-only import is erased by Node;
+installing the local package makes those types available to your editor.
+
+Keep top-level evaluation free of side effects. Discovery imports the definition
+and its helpers to inspect metadata. Keep effects inside states: the launcher
+calls the factory before it finishes Agent preflight.
+
+## Events and Human input
+
+An Operation or Agent returns `{ type: "eventName", ...data }`. Its state maps
+that type to a target. An unexpected event fails the run. Human returns
+`{ type: "submitted", value: response }`; use an XState transition action or guard
+to inspect `event.value`.
+
+```ts
+human("Feedback?", { submitted: "revise" });
+human("Approve or give feedback", { submitted: "decide" }, {
+  suggestions: ["approve"],
+});
+human("Choose the outcome", { submitted: "decide" }, {
+  choices: ["approve", "deny"],
+});
+```
+
+Suggestions preserve free-form input. Explicit choices are restrictive and are
+validated by the runtime across terminal, injected, Pi, and MCP Human runners.
+Both properties cannot be supplied together. Terminal selectors support arrow
+keys; piped input stays plain text.
+
+Here is a complete Agent/Human feedback loop. Save as `.machines/review-task.ts`:
+
+```ts
+import type { Event, MachinePrimitives } from "@dna113p/machines";
+
+export const description = "Implements a task and revises it until the Human approves.";
+export const agentRoles = { implementer: "Implements the task and review feedback" };
+
+export default function reviewTask(
+  { machine, agent, human, final }: MachinePrimitives,
+  input: string,
+) {
+  let feedback = "";
+  return machine({
+    initial: "implement",
+    states: {
+      implement: agent(
+        () => `${input}\n${feedback}`,
+        { completed: "review" },
+        { using: "implementer", cwd: process.cwd() },
+      ),
+      review: human("Approve or describe changes", {
+        submitted: [
+          { guard: ({ event }: { event: Event }) => event.value === "approve", target: "done" },
+          {
+            target: "implement",
+            actions: ({ event }: { event: Event }) => { feedback = String(event.value); },
+          },
+        ],
+      }, { suggestions: ["approve"] }),
+      done: final(),
+    },
+  });
+}
+```
+
+The Machine owns this loop. An Agent runner only returns an allowed outcome; it
+does not decide destination states. Add verification Operations where the workflow
+has a concrete condition to check.
+
+## Agent presets
+
+Named Agent states select a semantic role with `using`. Declare each named role in
+`agentRoles` with a one-line description. Unnamed states use `default`.
+
+The launcher provides `default` through `npx -y pi-acp`. For deterministic local
+practice, this `.machines/agents.ts` preset satisfies the example role without a
+model or credentials:
+
+```ts
+export default () => ({
+  implementer: {
+    description: "Demonstrates the review loop without changing files",
+    runner: async () => ({ type: "completed" }),
+  },
+});
+```
+
+Run `machine agents`, then `machine run review-task "Demonstrate the loop"`.
+Supply feedback once, then `approve`, to exercise both transitions.
+
+To use a real ACP harness, replace the preset with:
+
+```ts
+export default ({ acpAgent }: { acpAgent: typeof import("@dna113p/machines/acp").acpAgent }) => ({
+  implementer: {
+    description: "Uses the locally configured Pi Agent to implement changes",
+    harness: "pi-acp",
+    runner: acpAgent("npx", ["-y", "pi-acp"], {
+      harness: "pi-acp",
+      output: "capture",
+    }),
+  },
+});
+```
+
+Install/configure the selected harness and its model credentials first. `acpAgent`
+accepts any compatible ACP command and argument array; the Pi adapter uses ACP as
+its supported execution path. The former `machines/pi` export has been retired;
+use `acpAgent` from `machines/acp` for Pi execution.
+
+Global presets live in `~/.machines/agents.ts`; project presets replace matching
+global names. Each preset requires a description and runner. Optional `harness`,
+`model`, and `thinking` fields are discovery labels, while the runner reports its
+actual identity during execution. Harness configuration belongs in the runner
+command, arguments, or `env` option; labels do not change model settings.
+
+Use `machine agents` to inspect configured names. Rebind a role for one run:
+
+```bash
+machine run review-task --agent implementer=anotherConfiguredPreset -- "Implement the task"
+```
+
+Repeat `--agent role=preset` for multiple overrides. `--` ends launcher options.
+The launcher rejects unknown roles/presets, duplicate overrides, and missing roles
+before starting the actor. `machine list` refreshes metadata on each call and
+reports missing bindings or invalid definitions.
+`ready` describes valid metadata and resolved roles; it does not verify that a
+real harness is installed, authenticated, or able to run the requested model.
+
+## Programmatic execution and verification
+
+Direct runtime users supply runners through `run(definition, { agents, human })`.
+An `AgentRunner` receives `prompt`, allowed `outcomes`, and optional `cwd`, plus an
+optional reporter for `identity`, `output`, and `tool` updates. It returns one event.
+A `HumanRunner` receives the prompt, suggestions, or choices and returns a string.
+
+For example, exercise the feedback loop in an installed project:
+
+```ts
+import { prepareMachineRun } from "@dna113p/machines/launcher";
+
+const answers = ["Please revise", "approve"];
+const prepared = await prepareMachineRun({
+  cwd: process.cwd(),
+  machine: "review-task",
+  input: "Demonstrate the loop",
+});
+const result = await prepared.start({ human: () => answers.shift() ?? "approve" });
+console.log(result.value); // done
+```
+
+Use the fake preset above for deterministic verification. A prepared run is
+single-use. Omit `human` to retain terminal input. For direct runtime examples,
+see the built package's `dist/examples/operation.js`, `human.js`, and
+`named-agents.js`; source equivalents live in the checkout's `examples/`.
+
+Verify the final state and the expected effect, including a feedback/error branch
+when it changes behavior. Real Agent execution is a separate check that requires
+the configured harness and any external authorization for the task.