@dna113p/machines 0.3.4 → 0.3.5

package/README.md

@@ -176,10 +176,10 @@ npm ci
 npm pack
 ```
 
-Then install the generated `dna113p-machines-0.3.4.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.4.tgz
+npm install /absolute/path/to/machines/dna113p-machines-0.3.5.tgz
 npx machine list
 ```
 
@@ -205,6 +205,7 @@ machine runs --for [<session>] [--project <dir>] [--json] [--all]   # the runs o
 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
@@ -220,6 +221,10 @@ such as a ticket a daemon runs. See
 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

@@ -16,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.
@@ -196,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,15 +10,17 @@ 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) {
@@ -62,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:",
@@ -76,6 +81,7 @@ try {
             `  ${unwatchUsage}`,
             `  ${watchForUsage}`,
             `  ${unwatchForUsage}`,
+            `  ${uiUsage}`,
         ].join("\n"));
     }
 }
@@ -105,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;
@@ -140,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) {
@@ -320,8 +332,12 @@ 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 is read or changed, this process's own unless one is named, and where the list is kept. */
 function requireWatchList(named) {
@@ -351,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) {
@@ -465,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. */
@@ -472,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);
@@ -486,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;
+    });
+}

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

@@ -1,5 +1,6 @@
 import type { StateValue } from "xstate";
 import type { AgentUpdate } from "./index.ts";
+import { type RunGraph, type RunTrailStep } from "./run-graph.ts";
 /** One published run, stored as `<id>.json` in the run-status directory. */
 export interface RunStatusRecord {
     /** Version 1 records carry only `human.prompt`. */
@@ -30,6 +31,12 @@ export interface RunStatusRecord {
     /** Names the inbox responses the run took lately, so that each sender can tell; never a response. */
     readonly deliveries?: readonly string[];
     readonly error?: string;
+    /** The finished run's summary, at most 2000 characters including any ellipsis. */
+    readonly note?: string;
+    /** The Machine's states and transitions, when it is small enough to draw. */
+    readonly graph?: RunGraph;
+    /** The states the run entered, oldest first: the latest `trailLimit` of them. */
+    readonly trail?: readonly RunTrailStep[];
     readonly startedAt: string;
     readonly updatedAt: string;
 }
@@ -63,6 +70,7 @@ export interface RunStatusRun {
     /** Replaces `MACHINES_RUN_LABEL`, and is shortened as it is. */
     readonly label?: string;
     readonly answeredBy?: "host";
+    readonly graph?: RunGraph;
 }
 /** A present key replaces its field; a present key holding `undefined` clears it. */
 export interface RunStatusChange {
@@ -77,6 +85,7 @@ export interface RunStatusChange {
 }
 export type RunStatusOutcome = {
     readonly state?: StateValue;
+    readonly note?: string;
 } | {
     readonly error: string;
 };
@@ -89,6 +98,8 @@ export interface RunStatusPublisher {
     update(change: RunStatusChange): void;
     finish(outcome: RunStatusOutcome): void;
 }
+/** How many entered states a record keeps: enough for a long run's repairs, small enough to rewrite at every step. */
+export declare const trailLimit = 200;
 /** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
 export declare const deliveryRetentionMilliseconds = 60000;
 /** How long a session's watch list is kept after its last change: sessions end without saying so. */
@@ -115,8 +126,9 @@ export declare function runDeliveryPath(directory: string, id: string, delivery:
 /**
  * Publishes one run for hosts that can only read files, such as a status line,
  * in `runStatusDirectory`. Publication is presentation: it never throws, and it
- * records neither Machine input nor output. A run whose first record cannot be
- * written, as in a read-only home, is not published at all.
+ * records no Machine input and only the supplied summary of its output.
+ * A run whose first record cannot be written, as in a read-only home, is not
+ * published at all.
  */
 export declare function createRunStatusPublisher(run: RunStatusRun, environment?: NodeJS.ProcessEnv): RunStatusPublisher;
 /**
@@ -139,3 +151,5 @@ export declare function readRunStatuses(directory: string): RunStatusRecord[];
 /** The id becomes a file name, so it must not be able to leave the directory. */
 export declare function isFileSafeId(id: string): boolean;
 export declare function isProcessAlive(pid: number): boolean;
+/** Only an object's non-empty summary is published from a Machine's output. */
+export declare function runOutputSummary(output: unknown): string | undefined;

package/dist/src/run-status.js

@@ -2,7 +2,10 @@ import { randomUUID } from "node:crypto";
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join, resolve } from "node:path";
 import { machinesUserHome } from "./discovery.js";
+import { statePaths } from "./run-graph.js";
 const staleAfterMilliseconds = 60 * 60 * 1_000;
+/** How many entered states a record keeps: enough for a long run's repairs, small enough to rewrite at every step. */
+export const trailLimit = 200;
 /** How long a record goes on naming a response its run took: longer than a sender waits to hear of it. */
 export const deliveryRetentionMilliseconds = 60_000;
 /** How long a session's watch list is kept after its last change: sessions end without saying so. */
@@ -59,8 +62,9 @@ export function runDeliveryPath(directory, id, delivery) {
 /**
  * Publishes one run for hosts that can only read files, such as a status line,
  * in `runStatusDirectory`. Publication is presentation: it never throws, and it
- * records neither Machine input nor output. A run whose first record cannot be
- * written, as in a read-only home, is not published at all.
+ * records no Machine input and only the supplied summary of its output.
+ * A run whose first record cannot be written, as in a read-only home, is not
+ * published at all.
  */
 export function createRunStatusPublisher(run, environment = process.env) {
     const directory = runStatusDirectory(environment);
@@ -79,6 +83,14 @@ export function createRunStatusPublisher(run, environment = process.env) {
     let human;
     let deliveries = [];
     let error;
+    let note;
+    let trail = [];
+    const enter = (entered, at) => {
+        const path = entered === undefined ? "" : statePaths(entered).join(", ");
+        if (path === "" || trail.at(-1)?.state === path)
+            return;
+        trail = [...trail, { state: path, at }].slice(-trailLimit);
+    };
     const publish = () => {
         const record = {
             schemaVersion: 2,
@@ -99,6 +111,9 @@ export function createRunStatusPublisher(run, environment = process.env) {
             ...(run.answeredBy === undefined ? {} : { answeredBy: run.answeredBy }),
             ...(deliveries.length === 0 ? {} : { deliveries: deliveries.map((delivery) => delivery.id) }),
             ...(error === undefined ? {} : { error }),
+            ...(note === undefined ? {} : { note }),
+            ...(run.graph === undefined ? {} : { graph: run.graph }),
+            ...(trail.length === 0 ? {} : { trail }),
             startedAt,
             updatedAt: new Date().toISOString(),
         };
@@ -153,8 +168,10 @@ export function createRunStatusPublisher(run, environment = process.env) {
             // Repeated notifications for an unchanged run do not need another write.
             if (JSON.stringify(next) === JSON.stringify({ status, state, agent, limit, human, deliveries }))
                 return;
-            if (next.state !== state)
+            if (next.state !== state) {
                 stateSince = new Date().toISOString();
+                enter(next.state, stateSince);
+            }
             ({ status, state, agent, limit, human, deliveries } = next);
             publish();
         },
@@ -168,6 +185,8 @@ export function createRunStatusPublisher(run, environment = process.env) {
             else {
                 status = "completed";
                 state = formatState(outcome.state) ?? state;
+                note = formatNote(outcome.note);
+                enter(state, new Date().toISOString());
             }
             stateSince = undefined;
             agent = undefined;
@@ -353,9 +372,23 @@ function isRunStatusRecord(value) {
         && (record.answeredBy === undefined || record.answeredBy === "host")
         && isOptionalStrings(record.deliveries)
         && isOptionalString(record.error)
+        && isOptionalString(record.note)
+        && (record.graph === undefined || isGraph(record.graph))
+        && (record.trail === undefined || (Array.isArray(record.trail) && record.trail.every((step) => step !== null && typeof step === "object" && typeof step.state === "string" && isTimestamp(step.at))))
         && isTimestamp(record.startedAt)
         && isTimestamp(record.updatedAt);
 }
+function isGraph(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const graph = value;
+    return isOptionalString(graph.initial)
+        && Array.isArray(graph.states) && graph.states.every((state) => state !== null && typeof state === "object"
+        && typeof state.id === "string" && typeof state.kind === "string"
+        && isOptionalString(state.parent) && isOptionalString(state.role))
+        && Array.isArray(graph.edges) && graph.edges.every((edge) => edge !== null && typeof edge === "object"
+        && typeof edge.from === "string" && typeof edge.to === "string" && typeof edge.event === "string");
+}
 function isOptionalString(value) {
     return value === undefined || typeof value === "string";
 }
@@ -384,6 +417,26 @@ function formatState(state) {
         return undefined;
     return typeof state === "string" ? state : JSON.stringify(state);
 }
+/** Only an object's non-empty summary is published from a Machine's output. */
+export function runOutputSummary(output) {
+    if (output === null || typeof output !== "object" || Array.isArray(output))
+        return undefined;
+    const summary = output.summary;
+    return typeof summary === "string" && summary.trim() !== "" ? summary : undefined;
+}
+function formatNote(note) {
+    const text = note?.trim();
+    if (!text)
+        return undefined;
+    if (text.length <= 2000)
+        return text;
+    // Reserve one character for the ellipsis, keeping the last whole word that fits.
+    let end = 1999;
+    while (end > 0 && !/\s/u.test(text[end]))
+        end -= 1;
+    // A single word longer than the limit still has to fit in the record.
+    return `${text.slice(0, end || 1999).trimEnd()}…`;
+}
 /** One short line: a label is a caption, not a place for task text. */
 function formatLabel(label) {
     const line = label?.split(/\r?\n/u).map((part) => part.trim()).find((part) => part !== "");

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

@@ -0,0 +1,6 @@
+/**
+ * The page `machine ui` serves: one self-contained document, with no outside
+ * scripts, styles, or fonts, so it works offline and loads nothing but its own
+ * data. The token lets only this page answer a run.
+ */
+export declare function runUiPage(token: string): string;