@dna113p/machines 0.3.4 → 0.3.6

package/dist/src/run-ui.d.ts

@@ -0,0 +1,62 @@
+import { type RunStatusRecord } from "./run-status.ts";
+/**
+ * `machine ui`: a local page that shows every published run as it happens,
+ * with its Machine's graph, and the project's own panels beside them. It reads
+ * the run-status directory and answers a waiting run through its inbox, as
+ * `machine respond` does; nothing else in the page changes anything.
+ */
+export interface RunUiOptions {
+    /** The run-status directory. */
+    readonly directory: string;
+    /** The project whose `.machines/ui.json` names panels; its name heads the page. */
+    readonly projectDir: string;
+    readonly port?: number;
+    /** How often the directory is read for changes. */
+    readonly pollMilliseconds?: number;
+}
+export interface RunUi {
+    readonly url: string;
+    close(): Promise<void>;
+}
+/** A run as the page shows it: `lost` when its record says running or waiting and its process is gone. */
+export type UiRun = Omit<RunStatusRecord, "status"> & {
+    readonly status: RunStatusRecord["status"] | "lost";
+};
+/** What a panel command prints: a few lines a person can take in at a glance. */
+export interface UiPanel {
+    readonly title: string;
+    readonly summary?: string;
+    readonly items: readonly UiPanelItem[];
+    readonly error?: string;
+    readonly checkedAt?: string;
+}
+export interface UiPanelItem {
+    readonly text: string;
+    readonly detail?: string;
+    /** Colours the item: `bad` and `warn` draw the eye, `active` is work under way. */
+    readonly status?: "ok" | "warn" | "bad" | "active" | "idle";
+    readonly href?: string;
+    readonly at?: string;
+}
+interface PanelSource {
+    readonly title: string;
+    readonly command: readonly string[];
+    readonly refreshSeconds: number;
+}
+export declare const defaultUiPort = 4777;
+/** The nearest directory at or above `start` that has a `.machines` directory, or `start` itself. */
+export declare function uiProjectDir(start: string): string;
+/** Every published run, with runs whose process is gone shown as lost. */
+export declare function uiRuns(directory: string, isAlive?: (pid: number) => boolean): UiRun[];
+/**
+ * Reads `.machines/ui.json`: `{ "panels": [{ "title", "command": [...], "refreshSeconds"? }] }`.
+ * A missing file is no panels; a malformed one is one panel saying what is wrong.
+ */
+export declare function readPanelSources(projectDir: string): {
+    sources: PanelSource[];
+    error?: string;
+};
+/** Turns a panel command's output into a panel, or says why it could not. */
+export declare function parsePanelOutput(title: string, stdout: string): UiPanel;
+export declare function startRunUi(options: RunUiOptions): Promise<RunUi>;
+export {};

package/dist/src/run-ui.js

@@ -0,0 +1,258 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { basename, dirname, join, resolve } from "node:path";
+import { respondToRun } from "./run-inbox.js";
+import { runUiPage } from "./run-ui-page.js";
+import { isProcessAlive, readRunStatuses } from "./run-status.js";
+export const defaultUiPort = 4777;
+const panelTimeoutMilliseconds = 30_000;
+const maxPanelItems = 50;
+/** The nearest directory at or above `start` that has a `.machines` directory, or `start` itself. */
+export function uiProjectDir(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".machines")) && statSync(join(current, ".machines")).isDirectory())
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return resolve(start);
+        current = parent;
+    }
+}
+/** Every published run, with runs whose process is gone shown as lost. */
+export function uiRuns(directory, isAlive = isProcessAlive) {
+    return readRunStatuses(directory)
+        .map((record) => ((record.status === "running" || record.status === "waiting") && !isAlive(record.pid)
+        ? { ...record, status: "lost" }
+        : record))
+        .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+}
+/**
+ * Reads `.machines/ui.json`: `{ "panels": [{ "title", "command": [...], "refreshSeconds"? }] }`.
+ * A missing file is no panels; a malformed one is one panel saying what is wrong.
+ */
+export function readPanelSources(projectDir) {
+    const file = join(projectDir, ".machines", "ui.json");
+    if (!existsSync(file))
+        return { sources: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!Array.isArray(parsed.panels))
+            throw new Error("panels must be an array");
+        const sources = parsed.panels.map((panel, index) => {
+            const { title, command, refreshSeconds } = (panel ?? {});
+            if (typeof title !== "string" || title.trim() === "")
+                throw new Error(`panels[${index}].title must be a non-empty string`);
+            if (!Array.isArray(command) || command.length === 0 || !command.every((part) => typeof part === "string")) {
+                throw new Error(`panels[${index}].command must be a non-empty array of strings`);
+            }
+            if (refreshSeconds !== undefined && (typeof refreshSeconds !== "number" || !(refreshSeconds >= 1))) {
+                throw new Error(`panels[${index}].refreshSeconds must be a number of at least 1`);
+            }
+            return { title, command, refreshSeconds: refreshSeconds ?? 10 };
+        });
+        return { sources };
+    }
+    catch (cause) {
+        return { sources: [], error: `${file}: ${cause instanceof Error ? cause.message : String(cause)}` };
+    }
+}
+/** Turns a panel command's output into a panel, or says why it could not. */
+export function parsePanelOutput(title, stdout) {
+    const parsed = JSON.parse(stdout);
+    if (parsed === null || typeof parsed !== "object" || !Array.isArray(parsed.items)) {
+        throw new Error("the command must print a JSON object with an items array");
+    }
+    const statuses = new Set(["ok", "warn", "bad", "active", "idle"]);
+    const text = (value, limit) => typeof value === "string" && value.trim() !== "" ? value.slice(0, limit) : undefined;
+    const items = parsed.items.slice(0, maxPanelItems).flatMap((item) => {
+        const entry = (item ?? {});
+        const line = text(entry.text, 300);
+        if (line === undefined)
+            return [];
+        const href = text(entry.href, 2000);
+        return [{
+                text: line,
+                ...(text(entry.detail, 600) === undefined ? {} : { detail: text(entry.detail, 600) }),
+                ...(typeof entry.status === "string" && statuses.has(entry.status) ? { status: entry.status } : {}),
+                // Only web links: a panel never gets the page to open anything else.
+                ...(href !== undefined && /^https?:\/\//u.test(href) ? { href } : {}),
+                ...(text(entry.at, 40) !== undefined && !Number.isNaN(Date.parse(entry.at)) ? { at: entry.at } : {}),
+            }];
+    });
+    return { title, ...(text(parsed.summary, 300) === undefined ? {} : { summary: text(parsed.summary, 300) }), items };
+}
+export async function startRunUi(options) {
+    const { directory, projectDir } = options;
+    const token = randomBytes(24).toString("hex");
+    const poll = options.pollMilliseconds ?? 1_000;
+    const clients = new Set();
+    const panels = new Map();
+    let port = 0;
+    let last = "";
+    const refreshPanels = () => {
+        const { sources, error } = readPanelSources(projectDir);
+        if (error !== undefined) {
+            panels.set("\0config", { panel: { title: "ui.json", items: [], error }, checkedAt: Date.now(), running: false });
+        }
+        else
+            panels.delete("\0config");
+        const wanted = new Set(sources.map((source) => source.title));
+        for (const title of panels.keys())
+            if (title !== "\0config" && !wanted.has(title))
+                panels.delete(title);
+        for (const source of sources) {
+            const known = panels.get(source.title);
+            if (known?.running || (known !== undefined && Date.now() - known.checkedAt < source.refreshSeconds * 1_000))
+                continue;
+            const entry = { panel: known?.panel ?? { title: source.title, items: [] }, checkedAt: Date.now(), running: true };
+            panels.set(source.title, entry);
+            execFile(source.command[0], source.command.slice(1), {
+                cwd: projectDir, timeout: panelTimeoutMilliseconds, maxBuffer: 4 * 1024 * 1024, encoding: "utf8",
+            }, (failure, stdout, stderr) => {
+                let panel;
+                try {
+                    if (failure)
+                        throw new Error((stderr.trim() || failure.message).split("\n").slice(-3).join(" "));
+                    panel = parsePanelOutput(source.title, stdout);
+                }
+                catch (cause) {
+                    panel = { ...entry.panel, error: cause instanceof Error ? cause.message : String(cause) };
+                }
+                panels.set(source.title, { panel: { ...panel, checkedAt: new Date().toISOString() }, checkedAt: Date.now(), running: false });
+                broadcast();
+            });
+        }
+    };
+    const snapshot = () => ({
+        project: { name: basename(projectDir), dir: projectDir },
+        directory,
+        runs: uiRuns(directory),
+        panels: [...panels.values()].map((entry) => entry.panel),
+    });
+    const broadcast = (force = false) => {
+        const state = snapshot();
+        const text = JSON.stringify(state);
+        if (!force && text === last)
+            return;
+        last = text;
+        for (const client of clients)
+            client.write(`data: ${text}\n\n`);
+    };
+    const timer = setInterval(() => {
+        refreshPanels();
+        broadcast();
+    }, poll);
+    timer.unref();
+    // A quiet connection is closed by some proxies and browsers; a comment keeps it open.
+    const heartbeat = setInterval(() => { for (const client of clients)
+        client.write(": ping\n\n"); }, 15_000);
+    heartbeat.unref();
+    const server = createServer((request, response) => {
+        void handle(request, response).catch((cause) => {
+            if (!response.headersSent)
+                send(response, 500, { error: cause instanceof Error ? cause.message : String(cause) });
+            else
+                response.end();
+        });
+    });
+    async function handle(request, response) {
+        // Another site can make the browser send to this port, but not with this host name: a page served
+        // from a name that resolves here (DNS rebinding) is refused, and only the page itself holds the token.
+        const host = request.headers.host ?? "";
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`)
+            return send(response, 421, { error: "unexpected host" });
+        const url = new URL(request.url ?? "/", `http://${host}`);
+        if (request.method === "GET" && url.pathname === "/") {
+            response.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+                "x-content-type-options": "nosniff",
+            });
+            response.end(runUiPage(token));
+            return;
+        }
+        if (request.method === "GET" && url.pathname === "/api/state")
+            return send(response, 200, snapshot());
+        if (request.method === "GET" && url.pathname === "/api/events") {
+            response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+            clients.add(response);
+            response.write(`data: ${JSON.stringify(snapshot())}\n\n`);
+            request.on("close", () => clients.delete(response));
+            return;
+        }
+        if (request.method === "POST" && url.pathname === "/api/respond") {
+            if (request.headers["x-machines-ui"] !== token)
+                return send(response, 403, { error: "missing or wrong page token" });
+            const body = await readBody(request);
+            const { runId, requestId, response: text, question } = body;
+            if (typeof runId !== "string" || typeof requestId !== "string" || typeof text !== "string" || text.trim() === "") {
+                return send(response, 400, { error: "runId, requestId, and a non-empty response are required" });
+            }
+            const answer = question === true ? { type: "question", text } : text;
+            try {
+                await respondToRun({ directory, runId, requestId, response: answer });
+            }
+            catch (cause) {
+                return send(response, 409, { error: cause instanceof Error ? cause.message : String(cause) });
+            }
+            broadcast(true);
+            return send(response, 200, { ok: true });
+        }
+        send(response, 404, { error: "not found" });
+    }
+    const start = options.port ?? defaultUiPort;
+    // The first free port from the one asked for: a second page for another project is not an error.
+    for (let candidate = start;; candidate += 1) {
+        try {
+            await new Promise((resolveListen, rejectListen) => {
+                server.once("error", rejectListen);
+                server.listen(candidate, "127.0.0.1", () => {
+                    server.off("error", rejectListen);
+                    resolveListen();
+                });
+            });
+            port = candidate;
+            break;
+        }
+        catch (cause) {
+            if (cause.code !== "EADDRINUSE" || candidate - start >= 20 || options.port === 0)
+                throw cause;
+        }
+    }
+    const address = server.address();
+    if (address !== null && typeof address === "object")
+        port = address.port;
+    refreshPanels();
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        close: () => new Promise((resolveClose) => {
+            clearInterval(timer);
+            clearInterval(heartbeat);
+            for (const client of clients)
+                client.end();
+            server.close(() => resolveClose());
+        }),
+    };
+}
+function send(response, status, body) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    response.end(JSON.stringify(body));
+}
+async function readBody(request) {
+    let text = "";
+    for await (const chunk of request) {
+        text += String(chunk);
+        if (text.length > 64 * 1024)
+            throw new Error("request body too large");
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/src/run-viewer.d.ts

@@ -2,6 +2,8 @@ import { type RunStatusRecord } from "./run-status.ts";
 import { type RunWatch } from "./run-watch.ts";
 export { readRunStatuses, runSessionId, runStatusDirectory } from "./run-status.ts";
 export type { RunStatusAgent, RunStatusHuman, RunStatusLimit, RunStatusRecord } from "./run-status.ts";
+export { statePaths } from "./run-graph.ts";
+export type { RunGraph, RunGraphEdge, RunGraphState, RunTrailStep } from "./run-graph.ts";
 export { readRunWatches } from "./run-watch.ts";
 export type { RunWatch } from "./run-watch.ts";
 /** How long a settled or lost run stays with its viewers before it drops out. */

package/dist/src/run-viewer.js

@@ -4,6 +4,7 @@ import { isWithinDirectory, runWatchMatches } from "./run-watch.js";
 // application needs to draw its own widgets for published runs. It only reads;
 // the publisher and the watch-list writer stay in the runtime.
 export { readRunStatuses, runSessionId, runStatusDirectory } from "./run-status.js";
+export { statePaths } from "./run-graph.js";
 export { readRunWatches } from "./run-watch.js";
 /** How long a settled or lost run stays with its viewers before it drops out. */
 export const settledRunVisibleMilliseconds = 30_000;

package/docs/authoring.md

@@ -101,6 +101,10 @@ 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.
 
+When designing verification and repair routes, follow
+[Checks the Machine owns](../skills/machine-builder/SKILL.md#checks-the-machine-owns)
+for the checks and evidence the workflow must own.
+
 ### Handling a usage limit in the Machine
 
 By default an Agent state never sees its provider's usage limit: the launcher
@@ -471,6 +475,15 @@ Options:
   `MACHINES_AGENT_MODEL` / `MACHINES_AGENT_EFFORT`. The `env` option overrides
   matching parent variables. With no setting, Codex selects its configured values;
   effort must be supported by the selected model.
+- `serviceTier`: selects a Codex service tier, for example
+  `codexAgent("codex", [], { serviceTier: "fast" })` for Fast mode or
+  `codexAgent("codex", [], { serviceTier: "ultrafast" })` for Ultrafast. Overrides
+  `CODEX_SERVICE_TIER` (including values supplied through `env`); when neither
+  is set, the runner leaves Codex's configured tier unchanged. The built-in
+  preset also accepts `CODEX_SERVICE_TIER=fast` or `CODEX_SERVICE_TIER=ultrafast`.
+  Both are opt-in; Machines does not enable either tier by default. Supported
+  tiers depend on the installed CLI, model, and account. See the
+  [Codex configuration reference](https://developers.openai.com/codex/config-reference#service_tier).
 - `output`: `stream` (default) writes agent messages and stderr to the terminal;
   `capture` keeps them off the terminal and includes final prose in the event's
   `message`. Both modes report activity to observers.

package/docs/integrations.md

@@ -220,6 +220,22 @@ choice to publish that text. `machine run` exports its run id as
 `MACHINES_RUN_PARENT`, so a Machine started by one of its Operations or Agents
 records that id as `parent`; the status line shows only top-level runs.
 
+`graph` is the Machine's states and transitions, published once when the run
+starts: `initial`, `states` (each with an `id`, a `kind` of `agent`, `human`,
+`operation`, `final`, `group`, or `state`, an Agent's `role`, and the `parent`
+group of a nested state), and `edges` (`from`, `to`, and the `event` taken). Ids
+are state paths joined by dots, so a nested state is `review.round`. A Machine
+with more than 300 states or 1000 transitions publishes no graph. `trail` is the
+states the run entered, oldest first, each with the time it was entered, as the
+same dotted paths; it keeps the latest 200. Both are additions to version 2:
+a reader that does not know them ignores them.
+
+The graph does not depend on publication. `machineGraph(definition)` from
+`@dna113p/machines` returns it for any Machine definition a program holds, or
+undefined for one too large to draw. The value `startMachineHost` resolves to
+carries the run's `graph` whether or not the host publishes, and its `onState`
+callback reports each state a trail is made of.
+
 A run hosted through `startMachineHost` from `@dna113p/machines/host` publishes
 the same record when its host asks with `publishRunStatus: true` and
 publication is on in the hosting process, as a daemon that runs tickets does. A
@@ -282,8 +298,17 @@ taken a response from its inbox, its record lists that delivery's id in
 id stays listed for at least a minute, however many responses the run takes
 after it, and never contains the response.
 
-Machine input, Machine output, and Human responses are never recorded. A Human
-prompt and its choices are written to the `0600` file while the request is
+When a run finishes, `machine run`, the MCP server, and a host that asks for
+publication all three publish the optional `note` field if the final output
+is an object with a non-empty string `summary`. It is trimmed and limited to
+2000 characters, including a trailing `…` when shortened
+at a word boundary (a single word longer than the limit is cut to fit).
+Empty or whitespace-only summaries leave the field absent. The whole note,
+including its line breaks, is available in JSON. This optional field keeps
+`schemaVersion` at 2; readers should accept records with or without it.
+
+Machine input, output fields other than that summary, and Human responses are
+never recorded. A Human prompt and its choices are written to the `0600` file while the request is
 waiting. The standard directory is private to you; one you name instead should
 be a directory only you can read and write.
 
@@ -333,7 +358,9 @@ session and project; `--for` narrows it to
 [what one viewer shows](#drawing-your-own-widgets). `--all`, with or without `--json`, lists every published
 run: also the ones whose records remain after they finished, as `completed` or
 `failed`, or after their process disappeared, as `lost` (in JSON such a record
-keeps the status it last published). A run answered through its host shows
+keeps the status it last published). For a completed or failed run, the first
+non-empty line of its note is printed beneath the row; `--json` includes the
+whole note. A run answered through its host shows
 `answered through its host` in place of a request id:
 
 ```text
@@ -444,6 +471,36 @@ for the same time, so the status line must run where it can see that process.
 Set `NO_COLOR` (to any value, even an empty one) for plain text and `COLUMNS`
 to change the 120-column truncation.
 
+### Watching runs in a browser
+
+```bash
+machine ui [--port <port>] [--project <dir>]
+```
+
+serves a live page on `127.0.0.1` (port 4777, or the next free one) of every
+published run: what is waiting on you, what is running, and what finished, with
+each run's Machine drawn as a graph, its current state marked, the states and
+transitions it has taken counted, and the path it took so far. A waiting run
+that takes outside responses is answered from the page, as `machine respond`
+answers it; a run answered through its host, such as a daemon's, names where to
+answer it instead. The page loads nothing from outside, accepts requests only
+under its own host name, and answers a run only with a token it was served.
+
+A project adds its own panels beside the runs, such as its tickets or pull
+requests, in `.machines/ui.json` in the project (the nearest directory above the
+current one that has a `.machines` directory, or `--project`):
+
+```json
+{ "panels": [{ "title": "Tickets", "command": ["node", "scripts/ui-panels.mjs", "tickets"], "refreshSeconds": 10 }] }
+```
+
+Each command runs in the project directory every `refreshSeconds` (10 by
+default) and prints one JSON object: `{ "summary"?, "items": [{ "text",
+"detail"?, "status"?, "href"?, "at"? }] }`, where `status` is `ok`, `warn`,
+`bad`, `active`, or `idle`, `href` is a web link, and `at` a time. Commands are
+project code, trusted as `.machines/` Machines are; a command that fails or
+prints something else shows its error in its panel.
+
 ### Watching other runs
 
 A session can pull in runs it did not start: a ticket that a daemon runs, or a
@@ -472,7 +529,8 @@ machine watch --for <session> org-9   # the same commands for another session's
 - An entry keeps matching runs that start later, so a ticket can be watched
   before its run exists. `machine watch` lists a matched run for as long as its
   record remains, with the status `machine runs --all` gives it, so it also
-  says how a watched run ended.
+  says how a watched run ended, with the first non-empty line of its note
+  beneath the row when present.
 - `--for <session>`, first, makes `machine watch` and `machine unwatch` read
   and change the list of the session it names instead of this process's own.
   A program that draws [its own widgets](#drawing-your-own-widgets) for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dna113p/machines",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Reusable workflows coordinating agents, local operations, and human decisions.",
   "license": "MIT",
   "repository": {
@@ -20,30 +20,96 @@
   },
   "types": "./dist/src/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
-    "./acp": { "types": "./dist/src/acp.d.ts", "import": "./dist/src/acp.js" },
-    "./agy": { "types": "./dist/src/agy.d.ts", "import": "./dist/src/agy.js" },
-    "./chatgpt-web": { "types": "./dist/src/chatgpt-web.d.ts", "import": "./dist/src/chatgpt-web.js" },
-    "./claude": { "types": "./dist/src/claude.d.ts", "import": "./dist/src/claude.js" },
-    "./conversation": { "types": "./dist/src/conversation.d.ts", "import": "./dist/src/conversation.js" },
-    "./codex": { "types": "./dist/src/codex.d.ts", "import": "./dist/src/codex.js" },
-    "./deepseek": { "types": "./dist/src/deepseek.d.ts", "import": "./dist/src/deepseek.js" },
-    "./decision": { "types": "./dist/src/decision.d.ts", "import": "./dist/src/decision.js" },
-    "./jev": { "types": "./dist/src/jev.d.ts", "import": "./dist/src/jev.js" },
-    "./openrouter": { "types": "./dist/src/openrouter.d.ts", "import": "./dist/src/openrouter.js" },
-    "./laya": { "types": "./dist/src/laya.d.ts", "import": "./dist/src/laya.js" },
-    "./von": { "types": "./dist/src/von.d.ts", "import": "./dist/src/von.js" },
-    "./host": { "types": "./dist/src/host.d.ts", "import": "./dist/src/host.js" },
-    "./launcher": { "types": "./dist/src/launcher.d.ts", "import": "./dist/src/launcher.js" },
-    "./mcp": { "types": "./dist/mcp/server.d.ts", "import": "./dist/mcp/server.js" },
-    "./pi-extension": { "types": "./dist/pi-extension/index.d.ts", "import": "./dist/pi-extension/index.js" },
-    "./run-status": { "types": "./dist/src/run-viewer.d.ts", "import": "./dist/src/run-viewer.js" }
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./acp": {
+      "types": "./dist/src/acp.d.ts",
+      "import": "./dist/src/acp.js"
+    },
+    "./agy": {
+      "types": "./dist/src/agy.d.ts",
+      "import": "./dist/src/agy.js"
+    },
+    "./chatgpt-web": {
+      "types": "./dist/src/chatgpt-web.d.ts",
+      "import": "./dist/src/chatgpt-web.js"
+    },
+    "./claude": {
+      "types": "./dist/src/claude.d.ts",
+      "import": "./dist/src/claude.js"
+    },
+    "./conversation": {
+      "types": "./dist/src/conversation.d.ts",
+      "import": "./dist/src/conversation.js"
+    },
+    "./codex": {
+      "types": "./dist/src/codex.d.ts",
+      "import": "./dist/src/codex.js"
+    },
+    "./deepseek": {
+      "types": "./dist/src/deepseek.d.ts",
+      "import": "./dist/src/deepseek.js"
+    },
+    "./decision": {
+      "types": "./dist/src/decision.d.ts",
+      "import": "./dist/src/decision.js"
+    },
+    "./jev": {
+      "types": "./dist/src/jev.d.ts",
+      "import": "./dist/src/jev.js"
+    },
+    "./openrouter": {
+      "types": "./dist/src/openrouter.d.ts",
+      "import": "./dist/src/openrouter.js"
+    },
+    "./laya": {
+      "types": "./dist/src/laya.d.ts",
+      "import": "./dist/src/laya.js"
+    },
+    "./von": {
+      "types": "./dist/src/von.d.ts",
+      "import": "./dist/src/von.js"
+    },
+    "./host": {
+      "types": "./dist/src/host.d.ts",
+      "import": "./dist/src/host.js"
+    },
+    "./launcher": {
+      "types": "./dist/src/launcher.d.ts",
+      "import": "./dist/src/launcher.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js"
+    },
+    "./pi-extension": {
+      "types": "./dist/pi-extension/index.d.ts",
+      "import": "./dist/pi-extension/index.js"
+    },
+    "./run-status": {
+      "types": "./dist/src/run-viewer.d.ts",
+      "import": "./dist/src/run-viewer.js"
+    }
   },
-  "files": ["dist", "claude/statusline.mjs", "docs/architecture.md", "docs/authoring.md", "docs/integrations.md", "docs/local-decisions.md", "services/laya/server.py", "skills", "LICENSE", "README.md"],
+  "files": [
+    "dist",
+    "claude/statusline.mjs",
+    "docs/architecture.md",
+    "docs/authoring.md",
+    "docs/integrations.md",
+    "docs/local-decisions.md",
+    "services/laya/server.py",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "build": "node scripts/build.mjs",
     "build:plugin": "npm run build && node scripts/build-plugin.mjs",
-    "check": "npm run typecheck && npm test",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "lint": "oxlint --deny-warnings",
     "example": "node examples/operation.ts",
     "example:agents": "node examples/named-agents.ts",
     "example:agy": "node examples/agy.ts",
@@ -73,6 +139,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "oxlint": "^1.87.0",
     "typescript": "^7.0.2"
   }
 }

package/skills/machine-builder/SKILL.md

@@ -31,6 +31,11 @@ needs. Existing Machines and examples are starting points, not a fixed menu.
 Make consequential checks and decisions explicit in states when they need to
 control progress. Choose the complexity needed to complete the task reliably.
 
+Machine Shop is an optional starter library of common software-task Machines,
+kept in its own repository at `https://github.com/dna113p/machine-shop`. Nothing
+here requires it; clone it to try a default or adapt one, as
+[machine-project-setup](../machine-project-setup/SKILL.md) describes.
+
 Look for common task sequences and recurring manual workflows while doing the
 work. Convert them into Machines when explicit steps would improve repeatability
 or code quality. Parameterize assignment details so the workflow can serve the
@@ -82,3 +87,29 @@ Agent runners or injected Human input where possible. A successful run reaches
 the intended final state and produces the requested artifact or effect. Run real
 external work only within the user's authorized scope. Report what was verified
 and any branch that still requires a configured harness or human interaction.
+
+## Checks the Machine owns
+
+Design the workflow so these checks control progress and leave evidence for the
+next repair round or person taking over:
+
+- Run every gate, not only up to the first failure, so one repair round sees
+  all failures.
+- Keep the project's gate list in one place that every route reads.
+- For new behaviour, write tests first; have an Operation see them fail before
+  implementation, then pass after implementation.
+- After each editing Agent, run an Operation that compares the changed paths
+  against the paths the assignment allows.
+- Ask for a structured review: each acceptance criterion met or not, findings
+  tagged by severity. Let an Operation, not the reviewer's verdict word, decide
+  what happens next.
+- Match a reviewer's findings across rounds by their place in the conversation,
+  never by their wording.
+- End stuck unattended runs with work kept and a written note of what a person
+  must decide, instead of waiting in a Human state. Every stop keeps both so a later
+  run or a person can continue from them.
+- Before implementation, have a read-only Agent try to show the assignment is
+  wrong, already done, or underspecified; require options and a recommended answer
+  for each question it raises.
+- Tell editing Agents that checks they cannot run in their environment are the
+  workflow's to run, so a sandboxed Agent returns its work instead of `blocked`.