@dna113p/machines 0.3.4 → 0.3.6

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;