@dna113p/machines 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machines contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# Machines
+
+Reusable workflows that coordinate agents, local operations, and human decisions.
+
+A Machine makes a repeatable process explicit: ask an Agent to implement a change,
+run an Operation to check it, and ask a Human to approve or provide feedback. Each
+state returns an event; the Machine decides what happens next. XState handles the
+transitions, while the same workflow can run from a terminal, Pi, or Codex.
+
+```text
+implement (Agent) → check (Operation) → review (Human) → done
+        ↑                                  │
+        └──────────── feedback ────────────┘
+```
+
+Use Machines when a sequence and its decision points are worth repeating. A
+one-off prompt or shell script remains useful for work that needs no workflow.
+
+## Quickstart
+
+Requires **Node.js 24 or later** and npm. From a checkout of this repository:
+
+```bash
+npm ci
+npm run check
+npm run example
+```
+
+The deterministic example needs no credentials or Agent installation and prints:
+
+```text
+calculate --completed--> done
+```
+
+Here is its complete implementation, runnable as `demo.ts` in the checkout root:
+
+```ts
+import { final, machine, operation, run } from "./src/index.ts";
+
+const workflow = machine({
+  initial: "calculate",
+  states: {
+    calculate: operation(
+      () => ({ type: "completed" }),
+      { completed: "done" },
+    ),
+    done: final(),
+  },
+});
+
+const result = await run(workflow);
+console.log(`calculate --completed--> ${String(result.value)}`);
+```
+
+Run it with `node demo.ts`. No build is needed to develop against the source.
+
+| Example | Command | Requirements |
+| --- | --- | --- |
+| Deterministic Operation | `npm run example` | Node only |
+| Human input | `node examples/human.ts` | Terminal input |
+| Suggestions and choices | `node examples/choices.ts` | Terminal input |
+| Agent contract | `node examples/agent.ts` | Built-in fake runner |
+| Agent escalation | `npm run example:agents` | Built-in fake runners |
+| Child host and Human response | `npm run example:host` | Node only |
+| Real Agent writes and verifies a file | `npm run example:pi` | Configured Pi through `pi-acp`; may use network and model credits |
+
+## Run your own workflows
+
+Save this as `.machines/hello.ts` in your project:
+
+```ts
+import type { MachinePrimitives } from "@dna113p/machines";
+
+export const description = "Prints the supplied message without an Agent.";
+
+export default function hello(
+  { machine, operation, final }: MachinePrimitives,
+  input: string,
+) {
+  return machine({
+    initial: "print",
+    states: {
+      print: operation(() => {
+        console.log(input || "Hello from Machines.");
+        return { type: "completed" };
+      }, { completed: "done" }),
+      done: final(),
+    },
+  });
+}
+```
+
+From the checkout, run:
+
+```bash
+./machine list
+./machine show hello
+./machine run hello "Hello from Machines."
+```
+
+The command reports the Machine path and state progress, then prints `--> done`.
+In another project, use the checkout's absolute `machine` path or install the npm
+package below. The `MachinePrimitives` import is type-only; executing this definition
+uses the primitives supplied by the launcher.
+
+Discovery checks the nearest project `.machines/` and then `~/.machines/`.
+Project definitions replace global definitions with the same name. Files can be
+`name.ts` or `name/index.ts`; the single file wins if both exist. `agents.ts` is
+reserved for Agent presets. Invalid definitions remain visible with their own
+diagnostics; other valid Machines remain usable.
+
+Read [Authoring Machines](docs/authoring.md) for Human input, Agent roles and
+presets, feedback loops, and the programmatic launcher.
+
+## Install from npm
+
+Install the package in your project:
+
+```bash
+npm install @dna113p/machines
+npx machine list
+```
+
+Or run the CLI without adding a project dependency:
+
+```bash
+npx @dna113p/machines list
+```
+
+The command is still named `machine`. For a global installation, run
+`npm install --global @dna113p/machines`, then use `machine list` or `machine run`.
+
+To install a build from a checkout instead:
+
+```bash
+npm ci
+npm pack
+```
+
+Then install the generated `dna113p-machines-0.1.0.tgz` into a project:
+
+```bash
+npm install /absolute/path/to/machines/dna113p-machines-0.1.0.tgz
+npx machine list
+```
+
+The package contains JavaScript and TypeScript declarations. Application code can
+import `{ machine, agent, human, operation, final, run }` from `"@dna113p/machines"`.
+Workflow definitions remain ordinary TypeScript outside `node_modules`.
+
+For **Codex MCP**, **the portable Codex plugin**, or **the Pi extension**, follow
+[Integrations](docs/integrations.md). No personal marketplace or developer-only
+installation script is required for the direct MCP setup.
+
+## Execution model and limitations
+
+Machine definitions and Agent preset files are **trusted executable code**.
+Discovery imports them to inspect metadata, including their relative imports.
+Keep module initialization free of side effects and do work inside states.
+Disposable discovery workers refresh imported metadata; they are not a sandbox.
+Operations and configured Agents run with the launching process's available access
+and can modify files or contact external services.
+
+Pi and MCP runs belong to the current session. Closing or reloading that session
+terminates its owned hosts; runs are not persisted or resumable. Process shutdown
+does not undo files or Git changes. A Machine owns its own retry, approval, merge,
+and cleanup decisions. See [Architecture](docs/architecture.md) for ownership and
+process-lifecycle limits.
+
+ACP permission requests are currently unsupported and fail the Agent state. Choose
+a harness configuration that can carry out the intended bounded task and put
+workflow decisions in Human states. The launcher defaults unnamed Agents to
+`npx -y pi-acp`; [Agent presets](docs/authoring.md#agent-presets) let you select
+another ACP command or runner explicitly.
+
+## Checks
+
+```bash
+npm run check          # typecheck and behavior tests
+npm run build          # JavaScript, declarations, examples, and UI assets
+npm run smoke:package  # install a tarball in a temporary project and exercise it
+npm run build:plugin
+npm run smoke:plugin   # exercise a relocated standalone plugin
+```
+
+Licensed under the [MIT License](LICENSE).

package/dist/codex/machines/ui/machines.html

@@ -0,0 +1,286 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    :root {
+      color-scheme: light dark;
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      --bg: light-dark(#f7f7f5, #171715);
+      --panel: light-dark(#ffffff, #22221f);
+      --line: light-dark(#deded8, #3d3d38);
+      --text: light-dark(#20201d, #f1f1ec);
+      --muted: light-dark(#6d6d66, #aaa9a0);
+      --accent: light-dark(#287a6a, #62c8b1);
+      --warn: light-dark(#8a5b00, #f2c45e);
+      --bad: light-dark(#a2352a, #ff8d82);
+      --good: light-dark(#247342, #68cf8a);
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; color: var(--text); background: transparent; }
+    main {
+      overflow: hidden;
+      border: 1px solid var(--line);
+      border-radius: 14px;
+      background: var(--panel);
+      box-shadow: 0 10px 28px color-mix(in srgb, #000 12%, transparent);
+    }
+    header { display: flex; align-items: center; gap: 10px; padding: 14px 16px 10px; }
+    .mark { color: var(--accent); font-size: 18px; line-height: 1; }
+    h1 { min-width: 0; flex: 1; margin: 0; overflow: hidden; font-size: 15px; text-overflow: ellipsis; white-space: nowrap; }
+    .badge { border-radius: 999px; padding: 4px 8px; background: color-mix(in srgb, var(--accent) 13%, transparent); color: var(--accent); font-size: 12px; font-weight: 650; }
+    .badge.waiting { background: color-mix(in srgb, var(--warn) 14%, transparent); color: var(--warn); }
+    .badge.completed { background: color-mix(in srgb, var(--good) 14%, transparent); color: var(--good); }
+    .badge.failed { background: color-mix(in srgb, var(--bad) 14%, transparent); color: var(--bad); }
+    .body { padding: 0 16px 15px; }
+    .state { display: flex; align-items: baseline; gap: 8px; font-size: 14px; }
+    .state strong { font-weight: 680; }
+    .elapsed, .meta { color: var(--muted); font-size: 12px; }
+    .meta { margin-top: 5px; }
+    .human { margin-top: 13px; border-top: 1px solid var(--line); padding-top: 12px; }
+    .prompt { margin: 0 0 10px; font-size: 14px; line-height: 1.45; white-space: pre-wrap; }
+    .actions { display: flex; flex-wrap: wrap; gap: 7px; }
+    button, input { font: inherit; }
+    button {
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 7px 10px;
+      color: var(--text);
+      background: var(--bg);
+      cursor: pointer;
+    }
+    button:hover { border-color: var(--accent); }
+    button:focus-visible, input:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    button:disabled, input:disabled { cursor: default; opacity: .55; }
+    form { display: flex; width: 100%; gap: 7px; margin-top: 8px; }
+    input { min-width: 0; flex: 1; border: 1px solid var(--line); border-radius: 8px; padding: 7px 9px; color: var(--text); background: var(--bg); }
+    .error { margin: 12px 0 0; color: var(--bad); font-size: 13px; line-height: 1.4; }
+    .done { margin: 11px 0 0; color: var(--muted); font-size: 13px; }
+  </style>
+</head>
+<body>
+  <main aria-live="polite">
+    <header>
+      <span class="mark" aria-hidden="true">◆</span>
+      <h1 id="machine">Machine</h1>
+      <span class="badge" id="status">starting</span>
+    </header>
+    <section class="body">
+      <div class="state"><strong id="state">starting</strong><span class="elapsed" id="elapsed"></span></div>
+      <div class="meta" id="agent"></div>
+      <div class="human" id="human" hidden>
+        <p class="prompt" id="prompt"></p>
+        <div class="actions" id="actions"></div>
+      </div>
+      <p class="error" id="error" hidden></p>
+      <p class="done" id="done" hidden></p>
+    </section>
+  </main>
+  <script>
+    const elements = Object.fromEntries(
+      ["machine", "status", "state", "elapsed", "agent", "human", "prompt", "actions", "error", "done"]
+        .map((id) => [id, document.getElementById(id)])
+    );
+    const pending = new Map();
+    let requestId = 1;
+    let run;
+    let timer;
+    let busy = false;
+    let refreshing = false;
+    let closed = false;
+    let revision = 0;
+    let renderedHumanKey;
+    let responseError;
+    let statusError;
+
+    function callTool(name, args) {
+      if (window.openai?.callTool) return window.openai.callTool(name, args);
+      const id = requestId++;
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        window.parent.postMessage({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }, "*");
+      });
+    }
+
+    function toolData(result) {
+      const payload = result?.result ?? result;
+      if (payload?.isError) {
+        const message = payload.content?.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+        throw new Error(message || "The Machine tool failed.");
+      }
+      const data = payload?.structuredContent;
+      if (!data?.run && !data?.runs?.length) throw new Error("The Machine tool did not return a run.");
+      return data;
+    }
+
+    function receive(data) {
+      const next = data?.run ?? data?.runs?.[0];
+      if (!next || closed) return;
+      if (humanKey(next) !== humanKey(run)) responseError = undefined;
+      statusError = undefined;
+      revision += 1;
+      run = next;
+      render();
+      schedule();
+    }
+
+    function humanKey(snapshot) {
+      return snapshot?.status === "waiting" && snapshot.human
+        ? JSON.stringify([snapshot.id, snapshot.human.requestId])
+        : undefined;
+    }
+
+    function renderError() {
+      const error = run?.error ?? responseError ?? statusError;
+      elements.error.hidden = !error;
+      elements.error.textContent = error ?? "";
+    }
+
+    function render() {
+      const terminal = run.status === "completed" || run.status === "failed";
+      elements.machine.textContent = run.machine;
+      elements.status.textContent = run.status === "waiting" ? "input needed" : run.status;
+      elements.status.className = `badge ${run.status}`;
+      elements.state.textContent = typeof run.state === "string" ? run.state : run.state ? JSON.stringify(run.state) : "starting";
+      elements.elapsed.textContent = `${run.elapsedSeconds}s`;
+      elements.agent.textContent = run.agent
+        ? [run.agent.harness, run.agent.model, run.agent.thinking ? `thinking ${run.agent.thinking}` : undefined].filter(Boolean).join(" · ")
+        : "";
+      renderError();
+      elements.done.hidden = !terminal || Boolean(run.error);
+      elements.done.textContent = run.status === "completed" ? "Finished." : "";
+      renderHuman();
+    }
+
+    function renderHuman() {
+      const human = run.status === "waiting" ? run.human : undefined;
+      elements.human.hidden = !human;
+      const key = humanKey(run);
+      if (key === renderedHumanKey) {
+        for (const control of elements.actions.querySelectorAll("button, input")) control.disabled = busy;
+        return;
+      }
+      renderedHumanKey = key;
+      elements.actions.replaceChildren();
+      if (!human) return;
+      elements.prompt.textContent = human.prompt;
+      const target = { runId: run.id, requestId: human.requestId };
+      const values = human.choices ?? human.suggestions ?? [];
+      for (const value of values) {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.textContent = value;
+        button.disabled = busy;
+        button.onclick = () => respond(target, value);
+        elements.actions.append(button);
+      }
+      if (!human.choices) {
+        const form = document.createElement("form");
+        const input = document.createElement("input");
+        const submit = document.createElement("button");
+        input.placeholder = "Other response";
+        input.setAttribute("aria-label", "Machine response");
+        input.disabled = busy;
+        submit.type = "submit";
+        submit.textContent = "Send";
+        submit.disabled = busy;
+        form.append(input, submit);
+        form.onsubmit = (event) => {
+          event.preventDefault();
+          if (input.value !== "") respond(target, input.value);
+        };
+        elements.actions.append(form);
+      }
+    }
+
+    async function respond(target, response) {
+      const key = JSON.stringify([target.runId, target.requestId]);
+      if (closed || busy || key !== humanKey(run)) return;
+      const focused = elements.actions.contains(document.activeElement) ? document.activeElement : undefined;
+      busy = true;
+      responseError = undefined;
+      const startedAt = ++revision;
+      clearTimeout(timer);
+      renderHuman();
+      renderError();
+      try {
+        const result = await callTool("machine_respond", { ...target, response });
+        if (!closed && revision === startedAt) receive(toolData(result));
+      } catch (error) {
+        if (!closed && key === humanKey(run)) {
+          responseError = error?.message ?? String(error);
+          renderError();
+        }
+      } finally {
+        busy = false;
+        if (!closed) {
+          renderHuman();
+          if (focused && elements.actions.contains(focused) && (!document.activeElement || document.activeElement === document.body)) focused.focus();
+          schedule();
+        }
+      }
+    }
+
+    function schedule(delay = 1000) {
+      clearTimeout(timer);
+      if (closed || busy || refreshing || !run || run.status === "completed" || run.status === "failed") return;
+      timer = setTimeout(refresh, delay);
+    }
+
+    async function refresh() {
+      if (closed || refreshing || busy || !run) return;
+      refreshing = true;
+      const startedAt = revision;
+      let delay = 1000;
+      try {
+        const result = await callTool("machine_status", { runId: run.id });
+        if (!closed && revision === startedAt) {
+          const data = toolData(result);
+          receive(data);
+        }
+      } catch (error) {
+        if (!closed && revision === startedAt) {
+          statusError = error?.message ?? String(error);
+          renderError();
+          delay = 3000;
+        }
+      } finally {
+        refreshing = false;
+        schedule(delay);
+      }
+    }
+
+    window.addEventListener("message", (event) => {
+      if (closed || event.source !== window.parent) return;
+      const message = event.data;
+      if (!message || message.jsonrpc !== "2.0") return;
+      if (message.id !== undefined && pending.has(message.id)) {
+        const request = pending.get(message.id);
+        pending.delete(message.id);
+        if (message.error) request.reject(message.error);
+        else request.resolve(message.result);
+        return;
+      }
+      if (message.method === "ui/notifications/tool-result") {
+        try {
+          receive(toolData(message.params));
+        } catch (error) {
+          statusError = error?.message ?? String(error);
+          renderError();
+          schedule(3000);
+        }
+      }
+    }, { passive: true });
+
+    window.addEventListener("pagehide", () => {
+      closed = true;
+      clearTimeout(timer);
+      for (const request of pending.values()) request.reject(new Error("The Machine card was closed."));
+      pending.clear();
+    }, { once: true });
+
+    receive(window.openai?.toolOutput);
+  </script>
+</body>
+</html>

package/dist/examples/agent.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/agent.js

@@ -0,0 +1,19 @@
+import { agent, final, human, machine, operation, run, } from "../src/index.js";
+const fakeAgent = (request) => {
+    console.log("Agent request:");
+    console.log(`prompt: ${request.prompt}`);
+    console.log(`cwd: ${request.cwd}`);
+    console.log(`outcomes: ${request.outcomes.join(", ")}`);
+    return { type: "completed" };
+};
+const example = machine({
+    initial: "work",
+    states: {
+        work: agent("Implement the tiny task", { completed: "confirm" }, { cwd: "/tmp/machines-fake" }),
+        confirm: human("Continue to verification?", { submitted: "verify" }),
+        verify: operation(() => ({ type: "passed" }), { passed: "done" }),
+        done: final(),
+    },
+});
+const result = await run(example, { agents: { default: fakeAgent } });
+console.log(`verified --> ${String(result.value)}`);

package/dist/examples/choices.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/choices.js

@@ -0,0 +1,17 @@
+import { final, human, machine, run, } from "../src/index.js";
+const example = machine({
+    initial: "choose",
+    states: {
+        choose: human("Approve or deny?", {
+            submitted: {
+                target: "done",
+                actions: ({ event }) => {
+                    console.log(`submitted "${String(event.value)}"`);
+                },
+            },
+        }, { choices: ["approve", "deny"] }),
+        done: final(),
+    },
+});
+const result = await run(example);
+console.log(`--> ${String(result.value)}`);

package/dist/examples/host.d.ts

@@ -0,0 +1,3 @@
+import type { MachinePrimitives } from "../src/index.ts";
+export declare const description = "Demonstrates one asynchronous child-hosted Machine.";
+export default function hostedExample({ final, human, machine, operation }: MachinePrimitives): ReturnType<MachinePrimitives["machine"]>;

package/dist/examples/host.js

@@ -0,0 +1,32 @@
+import { fileURLToPath } from "node:url";
+import { startMachineHost } from "../src/host.js";
+export const description = "Demonstrates one asynchronous child-hosted Machine.";
+export default function hostedExample({ final, human, machine, operation }) {
+    return machine({
+        initial: "work",
+        states: {
+            work: operation(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                return { type: "completed" };
+            }, { completed: "review" }),
+            review: human("Approve the hosted example?", { submitted: "done" }, { choices: ["approve", "deny"] }),
+            done: final(),
+        },
+    });
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    let resolveHuman;
+    const human = new Promise((resolve) => {
+        resolveHuman = resolve;
+    });
+    const hosted = await startMachineHost({
+        machine: fileURLToPath(import.meta.url),
+        onState: (state) => console.log(`state: ${String(state)}`),
+        onHumanRequest: resolveHuman,
+    });
+    console.log(`started: ${hosted.name}`);
+    const request = await human;
+    console.log(`human: ${request.prompt}`);
+    await hosted.respond("approve", request.requestId);
+    console.log(`completed: ${String((await hosted.result).state)}`);
+}

package/dist/examples/human.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/human.js

@@ -0,0 +1,17 @@
+import { final, human, machine, run, } from "../src/index.js";
+const example = machine({
+    initial: "choose",
+    states: {
+        choose: human("What should happen?", {
+            submitted: {
+                target: "done",
+                actions: ({ event }) => {
+                    console.log(`submitted "${String(event.value)}"`);
+                },
+            },
+        }, { suggestions: ["Use the default"] }),
+        done: final(),
+    },
+});
+const result = await run(example);
+console.log(`--> ${String(result.value)}`);

package/dist/examples/named-agents.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/named-agents.js

@@ -0,0 +1,38 @@
+import { agent, final, machine, operation, run, } from "../src/index.js";
+let failedReviews = 0;
+const fastReviewer = (request, report) => {
+    report?.({
+        type: "identity",
+        harness: "antigravity",
+        model: "gemini-flash",
+    });
+    console.log(`fastReviewer: ${request.prompt}`);
+    return { type: "changesRequested" };
+};
+const strongReviewer = (request, report) => {
+    report?.({
+        type: "identity",
+        harness: "claude-code",
+        model: "opus-5",
+        thinking: "high",
+    });
+    console.log(`strongReviewer: ${request.prompt}`);
+    return { type: "approved" };
+};
+const example = machine({
+    initial: "review",
+    states: {
+        review: agent("Review the implementation quickly", { changesRequested: "countFailure" }, { using: "fastReviewer" }),
+        countFailure: operation(() => {
+            failedReviews += 1;
+            return { type: failedReviews >= 2 ? "escalate" : "retry" };
+        }, { retry: "review", escalate: "escalatedReview" }),
+        escalatedReview: agent("Perform an escalated review", { approved: "done" }, { using: "strongReviewer" }),
+        done: final(),
+    },
+});
+const result = await run(example, {
+    agents: { fastReviewer, strongReviewer },
+});
+console.log(`Failed fast reviews: ${failedReviews}`);
+console.log(`--> ${String(result.value)}`);

package/dist/examples/operation.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/operation.js

@@ -0,0 +1,10 @@
+import { final, machine, operation, run, } from "../src/index.js";
+const example = machine({
+    initial: "calculate",
+    states: {
+        calculate: operation(() => ({ type: "completed" }), { completed: "done" }),
+        done: final(),
+    },
+});
+const result = await run(example);
+console.log(`calculate --completed--> ${String(result.value)}`);

package/dist/examples/pi.d.ts

@@ -0,0 +1 @@
+export {};