@aragon-agent/cli 0.6.45 → 0.6.47

package/dist/proc/wait.js

@@ -23,6 +23,20 @@
  *     nothing at all (the supervisor now emits `stopped` from it), and
  *     `dispose()` clears its listener set without emitting; the self-timeout is
  *     therefore a real second path, not belt-and-braces.
+ *  5. THE HEARTBEAT RE-CHECKS THE DEADLINE AGAINST `now()`, NOT AGAINST THE
+ *     TIMER (extended-job-wait). A 20-minute wait spans a laptop lid: Node's
+ *     monotonic `setTimeout` does not count the sleep, so a "10 minute" wait can
+ *     run 40 minutes of wall clock. Each beat compares `now() - startedAt` with
+ *     the budget and settles on the first beat after resume.
+ *
+ * THE WAKE SOURCE IS EDGE-TRIGGERED ONLY - there is no "is something pending"
+ * probe. The engine drains steering before EVERY tool execution
+ * (`core/src/engine/agent-loop.ts`), so input that arrived before this wait began
+ * has already been accepted; only input that arrives AFTER `subscribe()` needs to
+ * end the wait. Between the engine's decision to run `job_wait` and the
+ * `subscribe()` below there is no `await`, so no notification can fall into the
+ * gap. A level-triggered probe would add a stale-state hot loop (every wait
+ * returning at once) for no reachable gain.
  */
 import { isTerminalStatus } from './types.js';
 /** Read one bounded page per target; `read()` returns `undefined` for a vanished id. */
@@ -49,24 +63,41 @@ function allSettled(port, targets) {
         return snapshot === undefined || isTerminalStatus(snapshot.status);
     });
 }
+/** Has any target ended? Same unknown-id rule as `allSettled`. */
+function anySettled(port, targets) {
+    return targets.some((id) => {
+        const snapshot = port.get(id);
+        return snapshot === undefined || isTerminalStatus(snapshot.status);
+    });
+}
 /**
- * Wait up to `timeoutMs` for every target to reach a terminal status.
+ * THE ONE PREDICATE for "is this wait over", shared by the entry fast path and the
+ * `finish` funnel. Using it in only one of them makes `mode: 'any'` subscribe and
+ * burn the whole timeout when a target had already ended.
+ */
+function isDone(port, targets, mode) {
+    return mode === 'any' ? anySettled(port, targets) : allSettled(port, targets);
+}
+/**
+ * Wait up to `timeoutMs` for the targets to reach a terminal status.
  *
  * Resolves - never rejects - and always after at most `timeoutMs`. `now` is
  * injectable so a test can assert `waitedMs` without depending on wall clock.
  */
 export async function waitForJob(port, req, now = Date.now) {
     const { targets, signal } = req;
+    const mode = req.mode ?? 'all';
     const startedAt = now();
     // RULE 1. Nothing to wait for at all, or everything already ended: no
     // subscription, no timer, `waitedMs: 0`.
-    if (targets.length === 0 || allSettled(port, targets)) {
+    if (targets.length === 0 || isDone(port, targets, mode)) {
         return {
             jobs: collect(port, targets),
             terminal: true,
             waitedMs: 0,
             timedOut: false,
             aborted: false,
+            woken: false,
             pages: readPages(port, targets, req.since),
         };
     }
@@ -79,6 +110,8 @@ export async function waitForJob(port, req, now = Date.now) {
         // from inside the listener instead of resolving the wait.
         let unsubscribe = () => { };
         let timer;
+        let beat;
+        let unwake = () => { };
         /** Assigned below; declared here so `finish` never reads an uninitialised binding. */
         let onAbort = () => { };
         // RULE 3: the one funnel. Idempotent, and it releases every reference before
@@ -88,15 +121,19 @@ export async function waitForJob(port, req, now = Date.now) {
                 return;
             done = true;
             unsubscribe();
+            unwake();
             if (timer !== undefined)
                 clearTimeout(timer);
+            if (beat !== undefined)
+                clearInterval(beat);
             signal?.removeEventListener('abort', onAbort);
             resolve({
                 jobs: collect(port, targets),
-                terminal: reason === 'terminal' || allSettled(port, targets),
+                terminal: reason === 'terminal' || isDone(port, targets, mode),
                 waitedMs: now() - startedAt,
                 timedOut: reason === 'timeout',
                 aborted: reason === 'abort',
+                woken: reason === 'wake',
                 pages: readPages(port, targets, req.since),
             });
         };
@@ -105,12 +142,38 @@ export async function waitForJob(port, req, now = Date.now) {
                 return;
             if (!targets.includes(event.service.id))
                 return;
-            if (allSettled(port, targets))
+            if (isDone(port, targets, mode))
                 finish('terminal');
         });
+        // The user spoke. Edge-triggered: only a notification after this line counts.
+        unwake = req.wakeOn?.subscribe(() => finish('wake')) ?? (() => { });
+        if (done) {
+            // A source that notifies synchronously inside `subscribe` already settled us.
+            unwake();
+            return;
+        }
         // RULE 2: `unref`, so a pending wait never keeps a quitting process alive.
         timer = setTimeout(() => finish('timeout'), Math.max(0, req.timeoutMs));
         timer.unref?.();
+        // RULE 5. Also the view's 1 Hz clock. A throwing `onBeat` is a renderer bug and
+        // must never kill a 20-minute wait.
+        if (req.heartbeat) {
+            const { everyMs, onBeat } = req.heartbeat;
+            beat = setInterval(() => {
+                const current = now();
+                if (current - startedAt >= req.timeoutMs) {
+                    finish('timeout');
+                    return;
+                }
+                try {
+                    onBeat(current);
+                }
+                catch {
+                    // Deliberately swallowed: see above.
+                }
+            }, Math.max(1, everyMs));
+            beat.unref?.();
+        }
         onAbort = () => finish('abort');
         // `{ once: true }` AND the explicit removal in `finish`: the option alone
         // leaves the listener registered on a signal that outlives this wait.

package/dist/session/checkpoint.js

@@ -101,6 +101,8 @@ export function settleRunningToolCards(entries) {
             live: undefined,
             liveSeq: undefined,
             lastOutputAt: undefined,
+            wait: undefined,
+            waitSeq: undefined,
         };
     });
     return { entries: out, settled };

package/dist/session/persist.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { getSessionsDir } from '../config/store.js';
 import { stripEphemeralRuns } from '../team/settled.js';
+import { sanitizeInvocationCard } from '../agent/invocation-card.js';
 import { validateSession } from './validate-session.js';
 import { validateCompactionIdentity, verifyCompactionIdentity, } from '../compaction/memory-identity.js';
 import { getLogger } from '../logging/logger.js';
@@ -59,8 +60,20 @@ function defaultStamp() {
  */
 function stripLiveToolOutput(entries) {
     return entries.map((e) => e.kind === 'tool' &&
-        (e.live !== undefined || e.liveSeq !== undefined || e.lastOutputAt !== undefined)
-        ? { ...e, live: undefined, liveSeq: undefined, lastOutputAt: undefined }
+        (e.live !== undefined ||
+            e.liveSeq !== undefined ||
+            e.lastOutputAt !== undefined ||
+            e.wait !== undefined ||
+            e.waitSeq !== undefined)
+        ? {
+            ...e,
+            live: undefined,
+            liveSeq: undefined,
+            lastOutputAt: undefined,
+            // `wait` / `waitSeq` die with `live` (extended-job-wait I-9).
+            wait: undefined,
+            waitSeq: undefined,
+        }
         : e);
 }
 /**
@@ -145,6 +158,11 @@ export function saveSession(filePath, data) {
  */
 export function normalizeLoadedEntries(entries) {
     return entries.map((entry) => {
+        // A runtime-only wait view that reached disk anyway (an older or hand-edited
+        // file) describes a wait that died with the session: drop it (I-9).
+        if (entry.kind === 'tool' && (entry.wait !== undefined || entry.waitSeq !== undefined)) {
+            return { ...entry, wait: undefined, waitSeq: undefined };
+        }
         if (entry.kind === 'team' && entry.active) {
             return { ...entry, active: false, aborted: true };
         }
@@ -227,6 +245,15 @@ export function normalizeLoadedEntries(entries) {
         // THE ID IS KEPT: `restoreEntries` splices these positions into the
         // live transcript, and a fresh id here would collide with the next
         // `e<n>` the reducer allocates.
+        if (entry.kind === 'user' && 'invocation' in entry) {
+            // THE EIGHTH CLAUSE (tui-invocation-cards I-7). A session file is user-editable
+            // and `shape()` ignores undeclared fields, so a card arrives unchecked. Repair
+            // what can be repaired; a card that cannot be is dropped and the entry degrades
+            // to a plain user message - a corrupt card must never cost the session.
+            const { invocation: stored, ...plain } = entry;
+            const card = sanitizeInvocationCard(stored);
+            return card ? { ...plain, invocation: card } : plain;
+        }
         if (entry.kind === 'queued') {
             const downgraded = {
                 id: entry.id,

package/dist/session/validate-session.js

@@ -145,14 +145,16 @@ const subagent = shape({
     retry: optional(shape({ attempt: number, maxRetries: number })),
 });
 const ENTRY_FIELDS = {
-    user: { text: string },
+    // `invocation` is declared for self-description only: `shape()` ignores undeclared
+    // fields, and `normalizeLoadedEntries` repairs or drops a bad card (tui-invocation-cards).
+    user: { text: string, invocation: optional(() => { }) },
     // A GOVERNANCE CARD IS HISTORY, so it is validated LENIENTLY (governance-mode 10.4):
     // unknown fields are ignored (`shape` only reads the declared ones) and `card` is not
     // shape-checked here at all - `sanitizeGovernanceEntries` below repairs a card it can
     // and degrades one it cannot to a one-line notice, so a corrupt footnote never costs
     // the session. `at` is advisory.
     governance: { at: optional(number), card: () => { } },
-    queued: { text: string, queueId: optional(nonempty) },
+    queued: { text: string, queueId: optional(nonempty), invocation: optional(() => { }) },
     notice: { text: string, level: enumeration('info', 'warn', 'error') },
     assistant: {
         text: string, thinking: optional(string), thinkingOpen: boolean, streaming: boolean,
@@ -164,6 +166,9 @@ const ENTRY_FIELDS = {
         status: enumeration('pending', 'running', 'done', 'error'), preview: optional(string),
         durationMs: optional(number), isError: optional(boolean), patch: optional(patch),
         live: optional(array(string)), liveSeq: optional(number), lastOutputAt: optional(number),
+        // Runtime-only (extended-job-wait I-9): never written, but tolerated on read so a
+        // session saved mid-wait by any path still resumes; `normalizeLoadedEntries` drops it.
+        wait: optional(object), waitSeq: optional(number),
     },
     team: { dispatchId: string, requested: number, runs: array(subagent), aborted: boolean,
         durationMs: optional(number), active: boolean },

package/dist/team/forced-mode.d.ts

@@ -106,6 +106,19 @@ export interface ForcedPlan {
  * can apply, because only it can read the live config.
  */
 export declare function planForced(args: SubagentCommandArgs, team: TeamConfig): ForcedPlan;
+/**
+ * The parenthesised disclosure sentence of the plan notice - why the fan-out is not what
+ * the user typed - or `null` when nothing was narrowed.
+ *
+ * SHARED BY `planNotice` AND `forcedCardNote` (tui-invocation-cards RV-4): the notice and
+ * the transcript card must word the same fact the same way, so there is exactly one
+ * place that decides it.
+ *
+ * TWO CEILINGS, TWO SENTENCES. `forcedPartsMax` bounds what one argument may carry and
+ * `team.maxSubagents` bounds what may be dispatched; naming the wrong one sends the user
+ * to change a number that is not the reason.
+ */
+export declare function clampDisclosure(planned: ForcedPlan, team: TeamConfig): string | null;
 /**
  * The one line that says what the NEXT turn will do - a plan, not a result.
  *
@@ -114,3 +127,9 @@ export declare function planForced(args: SubagentCommandArgs, team: TeamConfig):
  * said "4 subagents started" would be a promise the command cannot keep.
  */
 export declare function planNotice(planned: ForcedPlan, team: TeamConfig): string;
+/**
+ * The card's `note`: the same disclosure, as a sentence. `undefined` when nothing was
+ * narrowed - the "Esc stops the turn" follow-up is an operating hint the status bar
+ * carries, not a fact about this invocation.
+ */
+export declare function forcedCardNote(planned: ForcedPlan, team: TeamConfig): string | undefined;

package/dist/team/forced-mode.js

@@ -123,34 +123,56 @@ export function planForced(args, team) {
     };
 }
 /**
- * The one line that says what the NEXT turn will do - a plan, not a result.
+ * The parenthesised disclosure sentence of the plan notice - why the fan-out is not what
+ * the user typed - or `null` when nothing was narrowed.
  *
- * IT IS PRINTED BEFORE THE TURN IS SUBMITTED and it never claims children
- * started: forcing is instruction-level for the first turn, and a notice that
- * said "4 subagents started" would be a promise the command cannot keep.
+ * SHARED BY `planNotice` AND `forcedCardNote` (tui-invocation-cards RV-4): the notice and
+ * the transcript card must word the same fact the same way, so there is exactly one
+ * place that decides it.
+ *
+ * TWO CEILINGS, TWO SENTENCES. `forcedPartsMax` bounds what one argument may carry and
+ * `team.maxSubagents` bounds what may be dispatched; naming the wrong one sends the user
+ * to change a number that is not the reason.
  */
-export function planNotice(planned, team) {
-    const noun = planned.count === 1 ? 'subagent' : 'subagents';
-    const head = `Forcing a fan-out of ${planned.count} ${noun}`;
-    const followUp = `${head} (max ${team.maxSubagents}) - the next turn dispatches them. `
-        + 'Esc stops the turn.';
-    // TWO CEILINGS, TWO SENTENCES. `forcedPartsMax` bounds what one argument may
-    // carry and `team.maxSubagents` bounds what may be dispatched; naming the wrong
-    // one sends the user to change a number that is not the reason.
+export function clampDisclosure(planned, team) {
     if (planned.parts.length > 0) {
         if (planned.parts.length < planned.partsAdmitted) {
-            return `${head} (asked for ${planned.partsRequested} parts; `
-                + `team.maxSubagents is ${team.maxSubagents}).`;
+            return `asked for ${planned.partsRequested} parts; team.maxSubagents is ${team.maxSubagents}`;
         }
         if (planned.partsAdmitted < planned.partsRequested) {
-            return `${head} (asked for ${planned.partsRequested} parts, `
-                + `the first ${planned.parts.length} are used).`;
+            return `asked for ${planned.partsRequested} parts, the first ${planned.parts.length} are used`;
         }
-        return followUp;
+        return null;
     }
     if (planned.requested > planned.count) {
-        return `${head} (asked for ${planned.requested}; `
-            + `team.maxSubagents is ${team.maxSubagents}).`;
+        return `asked for ${planned.requested}; team.maxSubagents is ${team.maxSubagents}`;
     }
-    return followUp;
+    return null;
+}
+/**
+ * The one line that says what the NEXT turn will do - a plan, not a result.
+ *
+ * IT IS PRINTED BEFORE THE TURN IS SUBMITTED and it never claims children
+ * started: forcing is instruction-level for the first turn, and a notice that
+ * said "4 subagents started" would be a promise the command cannot keep.
+ */
+export function planNotice(planned, team) {
+    const noun = planned.count === 1 ? 'subagent' : 'subagents';
+    const head = `Forcing a fan-out of ${planned.count} ${noun}`;
+    const disclosure = clampDisclosure(planned, team);
+    if (disclosure !== null)
+        return `${head} (${disclosure}).`;
+    return `${head} (max ${team.maxSubagents}) - the next turn dispatches them. `
+        + 'Esc stops the turn.';
+}
+/**
+ * The card's `note`: the same disclosure, as a sentence. `undefined` when nothing was
+ * narrowed - the "Esc stops the turn" follow-up is an operating hint the status bar
+ * carries, not a fact about this invocation.
+ */
+export function forcedCardNote(planned, team) {
+    const disclosure = clampDisclosure(planned, team);
+    if (disclosure === null)
+        return undefined;
+    return `${disclosure.charAt(0).toUpperCase()}${disclosure.slice(1)}.`;
 }

package/dist/tools/job-tools.d.ts

@@ -18,14 +18,14 @@
 import { type AgentTool } from '@aragon-agent/core';
 import { type JobNotice } from '../proc/notices.js';
 import type { JobKind, ProcSupervisorPort, ServiceStatus } from '../proc/types.js';
+import { type WakeSource } from '../proc/wait.js';
+import { type WaitListener } from '../proc/wait-view.js';
 export interface JobToolDeps {
     supervisor: ProcSupervisorPort;
     /** `cfg.jobs.waitSeconds`, read LIVE (same rule as `startupSettleMs`). */
     waitSeconds: () => number;
     /** `cfg.jobs.stallSeconds`, read LIVE; only the `[stalled]` sentence uses it. */
     stallSeconds: () => number;
-    /** `cfg.toolTimeoutMs`, read LIVE: I-4's second convergence. */
-    toolTimeoutMs: () => number;
     /** `PROC_LIMITS.maxConsecutiveWaits`. */
     maxConsecutiveWaits: number;
     /**
@@ -40,6 +40,17 @@ export interface JobToolDeps {
         kind: JobKind;
         status: ServiceStatus;
     } | undefined;
+    /** Live view of the wait (`begin` / 1 Hz `update` / `end`); absent for a sub-agent. */
+    onWait?: WaitListener;
+    /**
+     * Runs the whole wait with the idle watchdog paused (`controller.withPausedWatchdog`).
+     * Absent in a sub-agent or a fixture: the wait then runs unwrapped, as before.
+     */
+    holdWatchdog?: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Ends a wait when the user sends a message (edge-triggered; see `proc/wait.ts`). */
+    attention?: WakeSource;
+    /** Test seam; defaults to `Date.now`. */
+    now?: () => number;
 }
 export declare function makeJobWait(deps: JobToolDeps): AgentTool;
 export declare function makeJobList(deps: JobToolDeps): AgentTool;