@dna113p/machines 0.3.3 → 0.3.5

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.3.tgz` into a project:
+Then install the generated `dna113p-machines-0.3.5.tgz` into a project:
 
 ```bash
-npm install /absolute/path/to/machines/dna113p-machines-0.3.3.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.5.tgz
 npx machine list
 ```
 
@@ -201,9 +201,11 @@ answered from outside its own terminal:
 
 ```bash
 machine runs [--json] [--all]                      # running and waiting runs; --all adds finished and lost ones
+machine runs --for [<session>] [--project <dir>] [--json] [--all]   # the runs one viewer shows
 machine respond <run-id> <request-id> <response>   # answer a waiting run
 machine watch [<run-id-or-label-start> | --dir <path>]     # show other runs on this session's status line
 machine unwatch <run-id-or-label-start> | --dir <path> | --all
+machine ui [--port <port>] [--project <dir>]       # a live page of every run, with its Machine drawn as a graph
 ```
 
 `machine runs` shows each waiting run's prompt, request id, and choices. A run
@@ -215,6 +217,14 @@ Runs hosted through `startMachineHost` publish too and are answered through thei
 host. A session shows the runs it started; `machine watch` adds runs it did not,
 such as a ticket a daemon runs. See
 [watching other runs](docs/integrations.md#watching-other-runs).
+`machine runs --for` and the `@dna113p/machines/run-status` export answer which
+runs one session shows, so any application can
+[draw its own widgets](docs/integrations.md#drawing-your-own-widgets); `watch`
+and `unwatch` take `--for <session>` first to manage that session's list.
+`machine ui` serves a local page of every published run, drawing each run's
+Machine with its current state and the path it took, answering waiting runs, and
+showing a project's own panels; see
+[watching runs in a browser](docs/integrations.md#watching-runs-in-a-browser).
 
 ## Execution model and limitations
 

package/claude/statusline.mjs

@@ -4,8 +4,9 @@
 // docs/integrations.md). It runs on every status refresh, so it imports only
 // node: modules and never loads the runtime; the directory rule and the record
 // shape below mirror runStatusDirectory and RunStatusRecord in
-// src/run-status.ts, and the watch list and its matching mirror
-// src/run-watch.ts.
+// src/run-status.ts, the watch list and its matching mirror src/run-watch.ts,
+// and which runs a session sees, and in what order, mirrors runsForViewer in
+// src/run-viewer.ts, which tests/run-viewer.test.ts checks.
 
 import { readdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
@@ -15,6 +16,7 @@ import { pathToFileURL } from "node:url";
 const terminalVisibleMilliseconds = 30_000;
 const maximumRuns = 5;
 const defaultColumns = 120;
+// oxlint-disable-next-line no-control-regex -- the escape character is the point: this strips terminal styling.
 const ansiSequence = /\x1b\[[0-9;]*m/uy;
 // Combining marks, format characters such as joiners, and Hangul medial and
 // final jamo are drawn on the character before them.
@@ -195,6 +197,7 @@ function formatElapsed(startedAt, endedAt) {
 
 /** Recorded text must not be able to move the cursor or restyle the status line. */
 function plain(text) {
+  // oxlint-disable-next-line no-control-regex -- control characters are what a status line must not carry.
   return text.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").trim();
 }
 

package/dist/mcp/server.js

@@ -10,7 +10,7 @@ import { isJsonValue } from "../src/json.js";
 import { MachineSession as RunSession } from "../src/session.js";
 import { listAgentPresets, listMachines } from "../src/launcher.js";
 import { watchRunInbox } from "../src/run-inbox.js";
-import { createRunStatusPublisher } from "../src/run-status.js";
+import { createRunStatusPublisher, runOutputSummary } from "../src/run-status.js";
 import { machineCoordinatorGuidelines, machineDiscoveryDescription, machineSupervisionGuidelines } from "../src/coordinator-guidance.js";
 const widgetUri = "ui://machines/run-v1.html";
 const cwd = v.pipe(v.string(), v.nonEmpty("cwd must be a non-empty absolute path"), v.check(isAbsolute, "cwd must be an absolute path"));
@@ -219,7 +219,7 @@ export class MachineSession {
             });
             return;
         }
-        publisher.finish(run.status === "completed" ? { state: run.state } : { error: run.error ?? "Machine run failed" });
+        publisher.finish(run.status === "completed" ? { state: run.state, note: runOutputSummary(run.output) } : { error: run.error ?? "Machine run failed" });
         this.#published.delete(run.id);
     }
     /** A published request can also be answered, or asked about, through the run's inbox by `machine respond`. */

package/dist/src/cli.js

@@ -10,13 +10,19 @@ import { assertJsonValue, isJsonValue } from "./json.js";
 import { discoverMachines, machinesUserHome } from "./discovery.js";
 import { listAgentPresets, listMachines, prepareMachineRun, } from "./launcher.js";
 import { inboxHuman, respondToRun } from "./run-inbox.js";
-import { createRunStatusPublisher, isProcessAlive, readRunStatuses, runSessionId, runStatusDirectory, runStatusObserver, } from "./run-status.js";
+import { createRunStatusPublisher, isProcessAlive, readRunStatuses, runOutputSummary, runSessionId, runStatusDirectory, runStatusObserver, } from "./run-status.js";
 import { readRunWatches, runWatch, runWatchMatches, runWatchPath, sameRunWatch, writeRunWatches, } from "./run-watch.js";
+import { runsForViewer } from "./run-viewer.js";
+import { startRunUi, uiProjectDir } from "./run-ui.js";
 const [command, selector, ...argumentsAfterSelector] = process.argv.slice(2);
 const runsOptions = selector === undefined ? [] : [selector, ...argumentsAfterSelector];
 const watchUsage = "machine watch [<run-id-or-label-start> | --dir <path>]";
 const unwatchUsage = "machine unwatch <run-id-or-label-start> | --dir <path> | --all";
+const watchForUsage = "machine watch --for <session> [<run-id-or-label-start> | --dir <path>]";
+const unwatchForUsage = "machine unwatch --for <session> <run-id-or-label-start> | --dir <path> | --all";
+const uiUsage = "machine ui [--port <port>] [--project <dir>]";
 try {
+    const listing = command === "runs" ? parseRunsOptions(runsOptions) : undefined;
     if (command === "list" && selector === undefined) {
         const machines = await listMachines({ cwd: process.cwd() });
         if (machines.length === 0)
@@ -43,9 +49,11 @@ try {
     else if (command === "run" && selector !== undefined) {
         await runMachine(await resolveMachine(selector), argumentsAfterSelector);
     }
-    else if (command === "runs"
-        && runsOptions.every((option, index) => (option === "--json" || option === "--all") && runsOptions.indexOf(option) === index)) {
-        listRuns(runsOptions.includes("--json"), runsOptions.includes("--all"));
+    else if (listing !== undefined) {
+        if (listing.viewer === undefined)
+            listRuns(listing.json, listing.all);
+        else
+            listViewerRuns(listing.json, listing.all, listing.viewer);
     }
     else if (command === "respond" && selector !== undefined) {
         await respond([selector, ...argumentsAfterSelector]);
@@ -56,6 +64,9 @@ try {
     else if (command === "unwatch" && selector !== undefined) {
         unwatch([selector, ...argumentsAfterSelector]);
     }
+    else if (command === "ui") {
+        await ui(selector === undefined ? [] : [selector, ...argumentsAfterSelector]);
+    }
     else {
         throw new Error([
             "Usage:",
@@ -64,9 +75,13 @@ try {
             "  machine show <name-or-file>",
             "  machine run <name-or-file> [--agent role=preset]... [--input-file <file|->] [--] [input]",
             "  machine runs [--json] [--all]",
+            "  machine runs --for [<session>] [--project <dir>] [--json] [--all]",
             "  machine respond [--question] <run-id> <request-id> [--] <response>",
             `  ${watchUsage}`,
             `  ${unwatchUsage}`,
+            `  ${watchForUsage}`,
+            `  ${unwatchForUsage}`,
+            `  ${uiUsage}`,
         ].join("\n"));
     }
 }
@@ -96,7 +111,13 @@ async function runMachine(machinePath, args) {
     });
     const status = createRunStatus(machinePath);
     const runId = randomUUID();
-    const published = createRunStatusPublisher({ id: runId, machine: prepared.name, path: prepared.path, cwd: process.cwd() });
+    const published = createRunStatusPublisher({
+        id: runId,
+        machine: prepared.name,
+        path: prepared.path,
+        cwd: process.cwd(),
+        ...(prepared.graph === undefined ? {} : { graph: prepared.graph }),
+    });
     const statusDirectory = published.directory;
     // Machines started by this run's Operations and Agents are its sub-runs.
     process.env.MACHINES_RUN_PARENT = runId;
@@ -131,7 +152,7 @@ async function runMachine(machinePath, args) {
                 status.onState(state);
             },
         });
-        published.finish({ state: result.value });
+        published.finish({ state: result.value, note: runOutputSummary(result.output) });
         status.succeed();
         console.log(`--> ${String(result.value)}`);
         if (result.output !== undefined) {
@@ -164,56 +185,136 @@ function listRuns(json, all) {
         printRunListing(record, index > 0, watches.some((watched) => runWatchMatches(watched, record)));
     });
 }
+/** What `machine runs` was asked; undefined when the options are not ones it takes. */
+function parseRunsOptions(args) {
+    let json = false;
+    let all = false;
+    let forViewer = false;
+    let session;
+    let project;
+    for (let index = 0; index < args.length; index += 1) {
+        const option = args[index];
+        const next = args[index + 1];
+        // What follows an option is its value unless it is another option.
+        const value = next === undefined || next.startsWith("--") ? undefined : next;
+        if (option === "--json" && !json)
+            json = true;
+        else if (option === "--all" && !all)
+            all = true;
+        else if (option === "--for" && !forViewer) {
+            forViewer = true;
+            // Without a session id the viewer is this process's own session.
+            session = value;
+            if (value !== undefined)
+                index += 1;
+        }
+        else if (option === "--project" && project === undefined && value !== undefined) {
+            project = value;
+            index += 1;
+        }
+        else
+            return undefined;
+    }
+    // A project is a viewer's: without --for the listing is of every session and project.
+    if (!forViewer)
+        return project === undefined ? { json, all } : undefined;
+    const viewer = { ...(session === undefined ? {} : { session }), ...(project === undefined ? {} : { project }) };
+    return { json, all, viewer };
+}
+/** The runs one viewer shows, by the rule its status line applies. */
+function listViewerRuns(json, all, viewer) {
+    if (viewer.project === "")
+        throw new Error("Expected a directory after --project");
+    const { directory, session } = requireWatchList(viewer.session);
+    const watches = readRunWatches(directory, session);
+    // As they are read, not by start time: runs updated in the same millisecond
+    // keep that order, here as in the library and on the status line.
+    const runs = runsForViewer(readRunStatuses(directory), {
+        sessionId: session,
+        // Compared absolute, wherever the command ran and however the path was written.
+        ...(viewer.project === undefined ? {} : { projectDir: resolve(viewer.project) }),
+        watches,
+    }, { all });
+    if (json) {
+        console.log(JSON.stringify(runs, null, 2));
+        return;
+    }
+    if (runs.length === 0)
+        console.log(`Session ${session} shows no Machine runs.`);
+    runs.forEach((run, index) => {
+        printRunListing(run, index > 0, watches.some((watched) => runWatchMatches(watched, run)));
+    });
+}
 /** Every record in the directory, including runs that finished or lost their process and are still recorded. */
 function publishedRuns(directory) {
     return readRunStatuses(directory).sort((left, right) => Date.parse(left.startedAt) - Date.parse(right.startedAt));
 }
 /** A run that stopped reporting without finishing has lost its process, as on the status line. */
 function runStatus(record) {
+    // A viewer's run already has the status its process leaves it.
+    if ("shown" in record)
+        return record.status;
     return record.status !== "completed" && record.status !== "failed" && !isProcessAlive(record.pid) ? "lost" : record.status;
 }
 function isActiveRun(record) {
     const status = runStatus(record);
     return status === "running" || status === "waiting";
 }
-function watch(args) {
-    const { directory, session } = requireWatchList();
+function watch(given) {
+    const { named, args, usage, who } = watchSession(given, watchUsage, watchForUsage);
+    const { directory, session } = requireWatchList(named);
     const watches = readRunWatches(directory, session);
     const runs = publishedRuns(directory);
     if (args.length === 0) {
         if (watches.length === 0)
-            console.log("This session watches no other runs.");
+            console.log(`${who} watches no other runs.`);
         for (const watched of watches) {
             console.log(describeWatch(watched));
             printWatchedRuns(watched, runs);
         }
         return;
     }
-    const added = parseWatch(args, watchUsage);
+    const added = parseWatch(args, usage);
     if (!watches.some((watched) => sameRunWatch(watched, added)))
         writeRunWatches(directory, session, [...watches, added]);
     console.log(`Watching ${describeWatch(added)}`);
     printWatchedRuns(added, runs);
 }
-function unwatch(args) {
-    const { directory, session } = requireWatchList();
+function unwatch(given) {
+    const { named, args, usage, who } = watchSession(given, unwatchUsage, unwatchForUsage);
+    if (args.length === 0)
+        throw new Error(`Usage: ${usage}`);
+    const { directory, session } = requireWatchList(named);
     if (args[0] === "--all") {
         if (args.length !== 1)
-            throw new Error(`Usage: ${unwatchUsage}`);
+            throw new Error(`Usage: ${usage}`);
         writeRunWatches(directory, session, []);
-        console.log("This session watches no other runs.");
+        console.log(`${who} watches no other runs.`);
         return;
     }
-    const removed = parseWatch(args, unwatchUsage);
+    const removed = parseWatch(args, usage);
     const watches = readRunWatches(directory, session);
     const kept = watches.filter((watched) => !sameRunWatch(watched, removed));
     if (kept.length === watches.length) {
-        console.log(`This session was not watching ${describeWatch(removed)}`);
+        console.log(`${who} was not watching ${describeWatch(removed)}`);
         return;
     }
     writeRunWatches(directory, session, kept);
     console.log(`No longer watching ${describeWatch(removed)}`);
 }
+/**
+ * Takes a leading `--for <session>` from what `machine watch` and
+ * `machine unwatch` were given: the list to change is then that session's and
+ * not this process's own.
+ */
+function watchSession(given, usage, forUsage) {
+    if (given[0] !== "--for")
+        return { named: undefined, args: given, usage, who: "This session" };
+    const named = given[1];
+    if (named === undefined || named.startsWith("--"))
+        throw new Error(`Usage: ${forUsage}`);
+    return { named, args: given.slice(2), usage: forUsage, who: `Session ${named}` };
+}
 function parseWatch(args, usage) {
     if (args[0] === "--dir") {
         if (args.length !== 2)
@@ -231,13 +332,17 @@ function printWatchedRuns(watched, runs) {
     const matched = runs.filter((record) => runWatchMatches(watched, record));
     if (matched.length === 0)
         console.log("  no published run matches yet");
-    for (const record of matched)
+    for (const record of matched) {
         console.log(`  ${runColumns(record).join("\t")}`);
+        const note = finishedRunNote(record);
+        if (note !== undefined)
+            console.log(`    ${note}`);
+    }
 }
-/** The session whose watch list this process changes, and where the list is kept. */
-function requireWatchList() {
+/** The session whose watch list is read or changed, this process's own unless one is named, and where the list is kept. */
+function requireWatchList(named) {
     const directory = requireStatusDirectory();
-    const session = runSessionId();
+    const session = named ?? runSessionId();
     if (session === undefined) {
         throw new Error("No session to watch for: set MACHINES_RUN_OWNER to the id of the session whose status line shows the runs.");
     }
@@ -262,6 +367,35 @@ async function respond(args) {
     });
     console.log(`Machine run ${runId} took the ${question ? "question" : "response"}.`);
 }
+/** Serves the live page of published runs until interrupted. */
+async function ui(args) {
+    let port;
+    let project;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        const value = args[index + 1];
+        if (argument === "--port" && value !== undefined && /^\d+$/u.test(value) && Number(value) <= 65_535)
+            port = Number(value);
+        else if (argument === "--project" && value !== undefined)
+            project = resolve(value);
+        else
+            throw new Error(`Usage: ${uiUsage}`);
+        index += 1;
+    }
+    const page = await startRunUi({
+        directory: requireStatusDirectory(),
+        projectDir: project ?? uiProjectDir(process.cwd()),
+        ...(port === undefined ? {} : { port }),
+    });
+    console.log(`Machines UI: ${page.url}`);
+    console.log("Press Ctrl-C to stop.");
+    await new Promise((resolveStop) => {
+        const stop = () => resolveStop();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    await page.close();
+}
 function requireStatusDirectory() {
     const directory = runStatusDirectory();
     if (directory === undefined) {
@@ -376,6 +510,7 @@ function printAgentListing(preset, separate) {
 }
 /** Recorded text must not be able to move the cursor or restyle the terminal. */
 function plain(text) {
+    // oxlint-disable-next-line no-control-regex -- control characters are what this removes.
     return text.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, " ").trim();
 }
 /** A run as tab-separated columns: its label follows the four that were always there. */
@@ -383,6 +518,11 @@ function runColumns(record) {
     const label = record.label === undefined ? "" : plain(record.label);
     return [record.id, record.machine, runStatus(record), record.state ?? "starting"].map(plain).concat(label === "" ? [] : [label]);
 }
+function finishedRunNote(record) {
+    if (record.status !== "completed" && record.status !== "failed")
+        return undefined;
+    return record.note?.split(/\r?\n/u).map(plain).find((line) => line !== "");
+}
 function printRunListing(record, separate, watched) {
     const state = record.state ?? "starting";
     const recorded = runStatus(record);
@@ -397,6 +537,9 @@ function printRunListing(record, separate, watched) {
         ...(human.suggestions === undefined ? [] : [`suggestions: ${human.suggestions.map(plain).join(", ")}`]),
         ...(human.discussion === true ? ["discussion: questions allowed"] : []),
     ];
+    const note = finishedRunNote(record);
+    if (note !== undefined)
+        details.push(note);
     if (!process.stdout.isTTY) {
         const columns = runColumns(record);
         // The mark has its own column, after the label's, whether or not the run has a label.

package/dist/src/codex.d.ts

@@ -5,6 +5,8 @@ export interface CodexAgentOptions {
     readonly model?: string;
     /** A reasoning effort supported by the selected Codex model. */
     readonly effort?: string;
+    /** Codex service tier, e.g. "fast" or "ultrafast"; omitted values inherit the CLI configuration. */
+    readonly serviceTier?: string;
     /** Defaults to read-only; writes and unrestricted access require an explicit choice. */
     readonly sandbox?: "read-only" | "workspace-write" | "danger-full-access";
     readonly skipGitRepoCheck?: boolean;

package/dist/src/codex.js

@@ -17,6 +17,7 @@ export function codexAgent(command = "codex", args = [], options = {}) {
         const env = { ...process.env, ...options.env };
         const model = options.model ?? env.CODEX_MODEL ?? env.MACHINES_AGENT_MODEL;
         const effort = options.effort ?? env.CODEX_EFFORT ?? env.MACHINES_AGENT_EFFORT;
+        const serviceTier = options.serviceTier ?? env.CODEX_SERVICE_TIER;
         const outputMode = options.output ?? "stream";
         report?.({
             type: "identity",
@@ -37,6 +38,7 @@ export function codexAgent(command = "codex", args = [], options = {}) {
                 ...(options.ephemeral === false ? [] : ["--ephemeral"]),
                 ...(model === undefined ? [] : ["--model", model]),
                 ...(effort === undefined ? [] : ["--config", `model_reasoning_effort=${JSON.stringify(effort)}`]),
+                ...(serviceTier === undefined ? [] : ["--config", `service_tier=${JSON.stringify(serviceTier)}`]),
                 "--output-last-message", finalPath, "-",
             ], { cwd: request.cwd, env, stdio: ["pipe", "pipe", "pipe"] });
             const exited = new Promise((resolve, reject) => {

package/dist/src/host.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import * as v from "valibot";
 import { assertJsonValue, isJsonValue } from "./json.js";
 import { prepareMachineRun, } from "./launcher.js";
-import { createRunStatusPublisher, runStatusDirectory, runStatusObserver, } from "./run-status.js";
+import { createRunStatusPublisher, runOutputSummary, runStatusDirectory, runStatusObserver, } from "./run-status.js";
 const childArgument = "--machines-child-host";
 const humanRequestSchema = v.strictObject({
     discussion: v.optional(v.boolean()),
@@ -74,6 +74,8 @@ const childMessageSchema = v.variant("type", [
         description: v.string(),
         path: v.string(),
         agentRoles: v.record(v.string(), v.string()),
+        // Checked as the record is read back; here it only has to be an object.
+        graph: v.optional(v.custom((value) => value !== null && typeof value === "object")),
     }),
     v.strictObject({ type: v.literal("state"), state: stateValueSchema }),
     v.strictObject({ type: v.literal("agentUpdate"), update: agentUpdateSchema }),
@@ -193,6 +195,7 @@ export function startMachineHost(options) {
                         machine: message.name,
                         path: message.path,
                         cwd: resolvePath(cwd),
+                        ...(message.graph === undefined ? {} : { graph: message.graph }),
                         ...(options.label === undefined ? {} : { label: options.label }),
                         ...(options.owner === undefined ? {} : { owner: options.owner }),
                         // Responses reach this run through `respond` and `ask` below, never through an inbox.
@@ -290,7 +293,7 @@ export function startMachineHost(options) {
                 }
                 phase = "completed";
                 pendingHuman = undefined;
-                published?.finish({ state: message.state });
+                published?.finish({ state: message.state, note: runOutputSummary(message.output) });
                 dispose();
                 resolveResult({
                     state: message.state,
@@ -401,6 +404,7 @@ function runChildHost() {
                 description: prepared.description,
                 path: prepared.path,
                 agentRoles: prepared.agentRoles,
+                ...(prepared.graph === undefined ? {} : { graph: prepared.graph }),
             });
             // Machines started by this run's Operations and Agents are its sub-runs.
             if (runId !== undefined)

package/dist/src/launcher.d.ts

@@ -3,6 +3,7 @@ import { type JsonValue } from "./json.ts";
 import { type LauncherLocation, type MachineSummary, type AgentPresetSummary } from "./catalog.ts";
 export type { LauncherLocation, MachineSummary, AgentPresetSummary } from "./catalog.ts";
 import { type RunOptions } from "./index.ts";
+import { type RunGraph } from "./run-graph.ts";
 export interface PrepareMachineRunOptions extends LauncherLocation {
     readonly machine: string;
     readonly input?: JsonValue;
@@ -22,6 +23,8 @@ export interface PreparedMachineRun {
     readonly description: string;
     readonly path: string;
     readonly agentRoles: Readonly<Record<string, string>>;
+    /** The definition's states and transitions, for run status; undefined when it is too large to draw. */
+    readonly graph?: RunGraph;
     start(options?: Omit<RunOptions, "agents">): Promise<SnapshotFrom<AnyStateMachine>>;
 }
 export declare function listMachines(location?: LauncherLocation): Promise<readonly MachineSummary[]>;

package/dist/src/launcher.js

@@ -7,6 +7,7 @@ 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";
+import { machineGraph } from "./run-graph.js";
 export async function listMachines(location = {}) {
     return queryCatalog("machines", location);
 }
@@ -34,11 +35,13 @@ export async function prepareMachineRun(options) {
     preflightAgentRoles(path, usedAgentRoles, agentRoles, agents);
     const limitAware = limitAwareAgents(requiredRoles, overrides, configured, limitPolicy(options.agentLimits));
     let started = false;
+    const graph = machineGraph(definition);
     return {
         name: machineName(path),
         description,
         path,
         agentRoles,
+        ...(graph === undefined ? {} : { graph }),
         start(runOptions = {}) {
             if (started)
                 throw new Error(`Prepared Machine "${path}" has already started`);

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

@@ -0,0 +1,39 @@
+import type { AnyStateMachine } from "xstate";
+/**
+ * A Machine's states and transitions as data, for a surface that draws them.
+ * Ids are state paths joined by dots, with the root left out: `plan`, or
+ * `review.round` for a state nested in `review`.
+ */
+export interface RunGraph {
+    readonly initial?: string;
+    readonly states: readonly RunGraphState[];
+    readonly edges: readonly RunGraphEdge[];
+}
+export interface RunGraphState {
+    readonly id: string;
+    /** The compound state this one is nested in. */
+    readonly parent?: string;
+    /** What runs in the state. `group` holds nested states; `state` runs nothing itself. */
+    readonly kind: "agent" | "human" | "operation" | "final" | "group" | "state";
+    /** The Agent role an Agent state runs. */
+    readonly role?: string;
+}
+export interface RunGraphEdge {
+    readonly from: string;
+    readonly to: string;
+    /** The event the transition takes: an outcome, `done` when a group finishes, or `always`/`after`. */
+    readonly event: string;
+}
+/** One state the run entered, and when. */
+export interface RunTrailStep {
+    readonly state: string;
+    readonly at: string;
+}
+/**
+ * Reads the graph out of a Machine definition, or returns undefined for one too
+ * large to draw or one whose shape this cannot read. Never throws: a picture of
+ * the workflow is never worth the run.
+ */
+export declare function machineGraph(definition: AnyStateMachine): RunGraph | undefined;
+/** A state value as the dotted paths of its active leaves: `{"review":"round"}` is `review.round`. */
+export declare function statePaths(value: unknown): string[];

package/dist/src/run-graph.js

@@ -0,0 +1,91 @@
+/** Past this a Machine is not drawn: its record would grow past what a reader can take in at once. */
+const maxStates = 300;
+const maxEdges = 1_000;
+/**
+ * Reads the graph out of a Machine definition, or returns undefined for one too
+ * large to draw or one whose shape this cannot read. Never throws: a picture of
+ * the workflow is never worth the run.
+ */
+export function machineGraph(definition) {
+    try {
+        const root = definition.root;
+        const states = [];
+        const edges = [];
+        const id = (node) => node.path.join(".");
+        const visit = (node, parent) => {
+            const using = node.meta?.["machines.agent"]?.using;
+            const src = node.invoke[0]?.src;
+            const kind = node.type === "final" ? "final"
+                : node.type === "compound" || node.type === "parallel" ? "group"
+                    : typeof using === "string" ? "agent"
+                        : src === "human" ? "human"
+                            : src !== undefined ? "operation"
+                                : "state";
+            states.push({
+                id: id(node),
+                ...(parent === undefined ? {} : { parent }),
+                kind,
+                ...(kind === "agent" ? { role: using } : {}),
+            });
+            const add = (event, targets) => {
+                for (const target of targets ?? []) {
+                    // A target outside the drawn states is the root itself, which nothing draws.
+                    if (target.path.length > 0)
+                        edges.push({ from: id(node), to: id(target), event });
+                }
+            };
+            for (const [event, definitions] of node.transitions) {
+                // The runtime's own actor events only run actions; the outcome they raise is the transition.
+                // A plain XState state can target from them directly, through `onDone` and `onError`.
+                const label = event.startsWith("xstate.done.state.") || event.startsWith("xstate.done.actor.") ? "done"
+                    : event.startsWith("xstate.error.actor.") ? "error"
+                        : event.startsWith("xstate.after.") ? "after"
+                            : event;
+                for (const transition of definitions)
+                    add(label, transition.target);
+            }
+            for (const transition of node.always ?? [])
+                add("always", transition.target);
+            for (const child of Object.values(node.states))
+                visit(child, kind === "group" ? id(node) : parent);
+        };
+        for (const child of Object.values(root.states))
+            visit(child, undefined);
+        if (states.length === 0 || states.length > maxStates || edges.length > maxEdges)
+            return undefined;
+        const initial = root.initial?.target?.[0];
+        return { ...(initial === undefined ? {} : { initial: id(initial) }), states, edges: dedupe(edges) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A state value as the dotted paths of its active leaves: `{"review":"round"}` is `review.round`. */
+export function statePaths(value) {
+    if (typeof value === "string") {
+        if (!value.startsWith("{"))
+            return [value];
+        try {
+            return statePaths(JSON.parse(value));
+        }
+        catch {
+            return [value];
+        }
+    }
+    if (value === null || typeof value !== "object")
+        return [];
+    return Object.entries(value).flatMap(([key, child]) => {
+        const below = statePaths(child);
+        return below.length === 0 ? [key] : below.map((path) => `${key}.${path}`);
+    });
+}
+function dedupe(edges) {
+    const seen = new Set();
+    return edges.filter((edge) => {
+        const key = `${edge.from}\0${edge.to}\0${edge.event}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}