@chrok/pi-braid 0.4.0 → 0.5.0

package/dist/status-text.js

@@ -58,11 +58,23 @@ function workspaceLine(workspace) {
         parts.push(`${item.executionId} ${item.disposition}: ${item.reason}`);
     return parts.join(" · ");
 }
+/** Who paused an execution; a node timeout pause also says how long it ran. */
+export function pausedBy(suspension) {
+    if (suspension.source !== "node_timeout")
+        return `paused by ${suspension.source}`;
+    return suspension.timeout ? `paused by node timeout after ${duration(suspension.timeout.activeMs)} (budget ${duration(suspension.timeout.nodeTimeoutMs)})` : "paused by node timeout";
+}
+/** A node timeout pause waits for the parent's decision. */
+const TIMEOUT_PAUSE_NOTE = "Its node timeout ran out. Resume it with braid_resume (optionally with nodeTimeoutMs; the default is the job's nodeTimeoutMs again), or fail only this execution with braid_cancel and executionIds. Its successors wait until then.";
 function executionLine(execution) {
     const parts = [execution.executionId ?? "(no execution)", `node ${execution.id}`];
     if (execution.iteration)
         parts.push(`iteration ${execution.iteration}`);
     parts.push(execution.skipReason ? `${execution.status} (${execution.skipReason})` : execution.status);
+    if (execution.suspension)
+        parts.push(`${execution.suspension.state}, ${pausedBy(execution.suspension)}`);
+    if (pendingHold(execution))
+        parts.push(`holds when finished, set by ${holdSource(execution.holdAfter)}`);
     if (execution.latencyMs !== undefined)
         parts.push(duration(execution.latencyMs));
     if (execution.decision)
@@ -77,8 +89,27 @@ export function formatJobList(jobs) {
     return [`${jobs.length} Braid job${jobs.length === 1 ? "" : "s"} in this session, newest first:`,
         ...jobs.map(job => `- ${job.handle} · ${job.status} · started ${iso(job.createdAt)} · id ${job.jobId}\n  Goal: ${job.goal}`)].join("\n");
 }
+/** Held (pauseAfter) and suspended executions are resumed the same way; a job pause has its own resume. */
 function control(execution) {
-    return execution ? `Graph ${execution.status} · revision ${execution.revision} · paused executions: ${ids(execution.pausedExecutionIds)}` : "Graph not started";
+    if (!execution)
+        return "Graph not started";
+    const parts = [`Graph ${execution.status}`, `revision ${execution.revision}`, `paused executions: ${ids(execution.pausedExecutionIds)}`];
+    if (execution.suspendedExecutionIds?.length)
+        parts.push(`suspended executions: ${ids(execution.suspendedExecutionIds)}`);
+    if (execution.pause)
+        parts.push(`job paused by ${execution.pause.source} at ${iso(execution.pause.pausedAt)}`);
+    return parts.join(" · ");
+}
+/** Paused-by-user work is the user's call: say so wherever the parent sees it. */
+const USER_PAUSE_NOTE = "The user paused this; do not resume it unless the user asks.";
+const USER_HOLD_NOTE = "The user set this hold; do not remove it or release the result unless the user asks.";
+/** A hold that applies once a still-unsettled execution finishes. Settled holds are paused executions. */
+function pendingHold(execution) {
+    return Boolean(execution.holdAfter) && (execution.status === "running" || execution.status === "runnable");
+}
+const holdSource = (hold) => hold.source === "definition" ? "pauseAfter" : hold.source;
+function userPaused(execution, executions) {
+    return execution?.pause?.source === "user" || executions.some(item => item.suspension?.source === "user" || item.holdAfter?.source === "user");
 }
 /** The submission receipt. The caller already has the graph it submitted. */
 export function formatReceipt(job, message) {
@@ -86,10 +117,40 @@ export function formatReceipt(job, message) {
 }
 export function formatUpdate(job) {
     return [`Braid job ${job.handle} updated to revision ${job.execution.revision}.`,
-        `Paused executions: ${ids(job.execution.pausedExecutionIds)}`, "Current graph:", formatGraph(job.execution.graph)].join("\n");
+        `Paused executions: ${ids(job.execution.pausedExecutionIds)}`,
+        ...job.execution.suspendedExecutionIds?.length ? [`Suspended executions: ${ids(job.execution.suspendedExecutionIds)}`] : [],
+        "Current graph:", formatGraph(job.execution.graph)].join("\n");
 }
 export function formatResume(job) {
-    return `Braid job ${job.handle} resumed at revision ${job.execution.revision}. Still paused: ${ids(job.execution.pausedExecutionIds)}.`;
+    const execution = job.execution;
+    return `Braid job ${job.handle} resumed at revision ${execution.revision}. Still paused: ${ids(execution.pausedExecutionIds)}. ` +
+        `Still suspended: ${ids(execution.suspendedExecutionIds)}.${execution.pause ? ` The job itself is still paused by ${execution.pause.source}.` : ""}`;
+}
+/** The result of braid_pause or braid_resume with after=true. */
+export function formatHold(job, executionIds, hold) {
+    const execution = job.execution;
+    if (!hold)
+        return [`Braid job ${job.handle}: hold removed for ${ids(executionIds)}; their results go downstream when they finish.`, control(execution)].join("\n");
+    return [
+        `Braid job ${job.handle}: ${ids(executionIds)} keep running and will be held when they finish; downstream work waits until you release them.`,
+        control(execution),
+        "Each one appears in paused executions once it finishes, and you get a pause reminder. Review it with braid_status, then release it with " +
+            `braid_resume({"jobId":"${job.handle}","expectedRevision":<current>,"executionIds":[...]}), or atomically with braid_update resume. ` +
+            `To remove the hold before it finishes, use braid_resume({"jobId":"${job.handle}","executionIds":[...],"after":true}).`,
+    ].join("\n");
+}
+/** The result of braid_pause: what is pausing now and how to continue. */
+export function formatPause(job, executionIds) {
+    const execution = job.execution;
+    const pausing = Object.values(execution.executions).filter(item => item.suspension?.state === "pausing").map(item => item.executionId);
+    return [
+        executionIds ? `Braid job ${job.handle}: pause requested for ${ids(executionIds)}.` : `Braid job ${job.handle} paused: no new executions start, and running ones pause.`,
+        control(execution),
+        `Pausing (each stops before its next model request; a running tool finishes first): ${ids(pausing)}.`,
+        "Suspended executions keep their conversation and workspace and release their concurrency slot. The node timeout stops while suspended; the graph timeout keeps running. " +
+            (executionIds ? `Continue with braid_resume({"jobId":"${job.handle}","expectedRevision":${execution.revision},"executionIds":[...]}).`
+                : `Continue with braid_resume({"jobId":"${job.handle}"}).`),
+    ].join("\n");
 }
 export function formatActivity(activity, now, jobId) {
     const lines = [`Activity: ${activity.phase} for ${duration(now - activity.phaseStartedAt)}; last observed signal ${duration(now - activity.lastActivityAt)} ago (${activity.lastActivity}). Model requests ${activity.modelRequests}, tool calls ${activity.toolCalls}.`];
@@ -124,6 +185,8 @@ export function formatActivity(activity, now, jobId) {
 /** A focused read: the current control state, then one execution in full. */
 export function formatNodeStatus({ job, node, activity, now }) {
     const lines = [`Braid job ${job.handle} · ${job.status} · ${control(job.execution)}`,
+        ...node.suspension ? [`Execution is ${node.suspension.state}, ${pausedBy(node.suspension)}${node.suspension.suspendedAt !== undefined ? ` since ${iso(node.suspension.suspendedAt)}` : ""}.${node.suspension.source === "user" ? ` ${USER_PAUSE_NOTE}` : node.suspension.source === "node_timeout" ? ` ${TIMEOUT_PAUSE_NOTE}` : ""}`] : [],
+        ...pendingHold(node) ? [`Its result will be held when it finishes (set by ${holdSource(node.holdAfter)}).${node.holdAfter.source === "user" ? ` ${USER_HOLD_NOTE}` : ""}`] : [],
         `Execution ${node.executionId ?? "(none yet)"} · node ${node.id}${node.node ? ` (${node.node.type})` : ""}${node.iteration ? ` · iteration ${node.iteration}` : ""} · ${node.skipReason ? `${node.status} (${node.skipReason})` : node.status}`];
     const timing = [node.startedAt !== undefined && `started ${iso(node.startedAt)}`, node.latencyMs !== undefined && `took ${duration(node.latencyMs)}`,
         node.model && `model ${node.model}`, node.usage && `usage input ${node.usage.inputTokens}, output ${node.usage.outputTokens}`].filter(Boolean);
@@ -148,6 +211,8 @@ export function formatJobStatus(job, now) {
     const state = job.result ?? job.execution;
     // Control fields lead: a long goal or output must not push them out of a truncated preview.
     const header = [`Braid job ${job.handle} · ${job.status}`, `ID: ${job.jobId}`, control(job.execution)];
+    if (job.status === "running" && userPaused(job.execution, Object.values(job.execution?.executions ?? {})))
+        header.push(USER_PAUSE_NOTE);
     const error = job.error ?? (job.result?.error ? failure(job.result.error) : job.execution?.error ? failure(job.execution.error) : undefined);
     if (error)
         header.push(`Error: ${error}`);
@@ -177,3 +242,24 @@ export function formatJobStatus(job, now) {
         sections.push(`Current graph (revision ${job.execution.revision}):\n${formatGraph(job.execution.graph)}`);
     return sections.join("\n\n");
 }
+/** The waking reminder for an execution its node timeout paused. */
+export function formatTimeoutPause(pause) {
+    const execution = `${pause.executionId}${pause.iteration ? ` (iteration ${pause.iteration})` : ""}`;
+    return [
+        `Braid job ${pause.handle} node ${JSON.stringify(pause.nodeId)} execution ${execution} was paused because it exceeded its node timeout:`,
+        `it ran ${duration(pause.activeMs)} against a budget of ${duration(pause.nodeTimeoutMs)}.`,
+        pause.activity ? `When the timeout fired it was: ${pause.activity}.` : "",
+        "Its conversation, workspace, and tool budgets are kept; the step that was interrupted is reported to it after resume.",
+        "Its successors wait until you decide. Check it with",
+        `braid_status(${JSON.stringify({ jobId: pause.handle, executionId: pause.executionId })}), then either`,
+        `resume it with braid_resume({"jobId":"${pause.handle}","executionIds":["${pause.executionId}"],"expectedRevision":<current>}) — it gets the job's nodeTimeoutMs again, or pass nodeTimeoutMs —`,
+        "or resume it in braid_update with resume and resumeOptions together with graph changes,",
+        `or fail only this execution with braid_cancel({"jobId":"${pause.handle}","executionIds":["${pause.executionId}"]}).`,
+        "The graph timeout keeps running while it is paused.",
+    ].filter(Boolean).join(" ");
+}
+/** The result of braid_cancel with executionIds. */
+export function formatCancelExecutions(job, executionIds) {
+    return [`Braid job ${job.handle}: cancellation requested for ${ids(executionIds)}. They fail; their successors follow the usual failure rules.`,
+        control(job.execution)].join("\n");
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@chrok/pi-braid",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "Pi extension for Braid: background agent graphs, bounded loops, live updates, and a flow panel",
   "type": "module",
   "dependencies": {
     "grok-mermaid": "^0.2.2",
-    "@chrok/braid": "0.4.0"
+    "@chrok/braid": "0.5.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",