@dna113p/machines 0.3.3 → 0.3.5

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;
 /**
@@ -129,7 +141,9 @@ export declare function runStatusObserver(update: (change: RunStatusChange) => v
 };
 /**
  * The session a process belongs to: the owner of the runs it starts, and the
- * session whose watch list `machine watch` changes.
+ * session whose watch list `machine watch` changes. `MACHINES_RUN_OWNER` is how
+ * any host names it; the others are what Claude Code, Codex, and Pi give the
+ * commands they start.
  */
 export declare function runSessionId(environment?: NodeJS.ProcessEnv): string | undefined;
 /** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
@@ -137,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;
@@ -228,10 +247,16 @@ export function runStatusObserver(update) {
 }
 /**
  * The session a process belongs to: the owner of the runs it starts, and the
- * session whose watch list `machine watch` changes.
+ * session whose watch list `machine watch` changes. `MACHINES_RUN_OWNER` is how
+ * any host names it; the others are what Claude Code, Codex, and Pi give the
+ * commands they start.
  */
 export function runSessionId(environment = process.env) {
-    return environment.MACHINES_RUN_OWNER || environment.CLAUDE_CODE_SESSION_ID || undefined;
+    return environment.MACHINES_RUN_OWNER
+        || environment.CLAUDE_CODE_SESSION_ID
+        || environment.CODEX_THREAD_ID
+        || environment.PI_SESSION_ID
+        || undefined;
 }
 /** Returns the valid records in a directory. Unreadable or malformed files are skipped. */
 export function readRunStatuses(directory) {
@@ -347,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";
 }
@@ -378,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;