@aragon-agent/cli 0.6.31 → 0.6.33

package/dist/tools/job-tools.js

@@ -0,0 +1,329 @@
+/**
+ * `job_wait` and `job_list`, plus the notice tail every tool result carries
+ * (long-task-jobs §4.4.2 / §4.4.3 / §4.6).
+ *
+ * ASCII ONLY: `src/tools/**` is inside the glyph scanner's scope.
+ *
+ * WHY TWO NEW TOOLS RATHER THAN A `block` PARAMETER ON `bash_output` (D-10):
+ * the tool list IS the discoverable capability surface. A model that can SEE
+ * `job_wait` knows that waiting is a legal step in a plan; a hidden `block: 30`
+ * parameter is a feature it will never use, and extending `bash_output`'s output
+ * would also rewrite assertions that pin its current grammar word for word.
+ *
+ * EVERY RESULT IS A FIXED GRAMMAR OF AT MOST TWELVE LINES. That is not tidiness:
+ * the entire economic argument for this feature is that one wait costs ~150
+ * tokens instead of a 200-row tail, so an unbounded result would delete the
+ * reason the feature exists.
+ */
+import { defineTool, errorResult, textResult } from '@aragon-agent/core';
+import { formatDuration } from '../agent/usage.js';
+import { JOB_WAIT_MARGIN_MS, PROC_LIMITS } from '../proc/limits.js';
+import { renderJobNotices } from '../proc/notices.js';
+import { isTerminalStatus } from '../proc/types.js';
+import { waitForJob } from '../proc/wait.js';
+/**
+ * Split a page into "completed rows" and "the carry line".
+ *
+ * THE PAGE NAMES ITS CARRY: `LogRingPage.carryRow` is the not-yet-terminated line,
+ * and `rows` ends with it when it is non-empty. A page from a caller that does not
+ * provide it (a test double, `bash_output`) is treated as all-completed, which
+ * keeps this a pure refinement rather than a new requirement.
+ */
+function splitCarry(page) {
+    const rows = page?.rows ?? [];
+    const carry = page?.carryRow ?? '';
+    if (carry.length === 0)
+        return { rows, carry };
+    const last = rows[rows.length - 1];
+    return last === carry ? { rows: rows.slice(0, -1), carry } : { rows, carry };
+}
+/**
+ * Clamp `timeoutSeconds` into `[jobs.waitSeconds, 60]` and then into the tool
+ * ceiling (I-4).
+ *
+ * TWO CONVERGENCES, BOTH REQUIRED. The first honours `WAIT_SECONDS_RANGE`; the
+ * second is what makes it impossible for a wait to outlive the tool that is
+ * hosting it, which is the difference between "a bounded wait" and "another
+ * `Command timed out after 180000ms`".
+ */
+function clampWaitSeconds(deps, requested) {
+    const configured = deps.waitSeconds();
+    const asked = requested === undefined || !Number.isFinite(requested) || requested < PROC_LIMITS.waitMinSeconds
+        ? configured
+        : requested;
+    const bounded = Math.max(PROC_LIMITS.waitMinSeconds, Math.min(Math.floor(asked), PROC_LIMITS.waitMaxSeconds));
+    const ceiling = Math.floor((deps.toolTimeoutMs() - JOB_WAIT_MARGIN_MS) / 1000);
+    // `Math.max(1, ...)` rather than `Math.max(waitMinSeconds, ...)`: when an
+    // operator sets a tool ceiling below the margin, "the wait fits inside the
+    // ceiling" is the invariant that must win. Nothing here ever silently produces
+    // a wait longer than the tool call that hosts it.
+    return Math.max(1, Math.min(bounded, ceiling));
+}
+/** `JOB t3  task  running  12m34s` - the one header grammar for every outcome. */
+function headerLine(job, nowMs) {
+    const elapsed = formatDuration((job.endedAt ?? nowMs) - job.startedAt);
+    const code = job.exitCode !== null
+        ? ` code ${job.exitCode}`
+        : job.signal !== null
+            ? ` signal ${job.signal}`
+            : '';
+    return `JOB ${job.id}  ${job.kind}  ${job.status}${code}  ${elapsed}`;
+}
+/** `[stalled] ...` - only for a live job whose silence passed the threshold. */
+function stalledLine(job, nowMs, stallSeconds) {
+    // A FINISHED JOB CANNOT BE STALLED. `snapshot()` derives the flag only for a
+    // live job, so this guard is about the OTHER direction: a snapshot captured
+    // while the job was quiet and delivered after it ended must not claim silence.
+    if (job.stalled !== true || isTerminalStatus(job.status))
+        return undefined;
+    const quiet = formatDuration(Math.max(0, nowMs - job.lastOutputAt));
+    return (`[stalled] no output for ${quiet} (threshold ${stallSeconds}s). Keep waiting, ` +
+        `stop it with bash_kill({ job: "${job.id}" }), or read the tail with bash_output.`);
+}
+/**
+ * Assemble one job's block.
+ *
+ * THE ROW BLOCK IS THE ONLY ELASTIC PART, and it shrinks first when the fixed
+ * lines grow - which is how "at most twelve lines" survives a job that is both
+ * stalled and truncated without either sentence being dropped.
+ */
+function renderJobBlock(args) {
+    const { job, rows, cursor, since, nowMs } = args;
+    const terminal = isTerminalStatus(job.status);
+    const fixed = [headerLine(job, nowMs)];
+    const progress = job.progress?.text;
+    if (progress !== undefined) {
+        fixed.push(`[progress] ${progress}${args.progressUnchanged ? ' (unchanged)' : ''}`);
+    }
+    const stalled = stalledLine(job, nowMs, args.stalledSeconds);
+    if (stalled !== undefined)
+        fixed.push(stalled);
+    if (args.truncatedNote !== undefined)
+        fixed.push(args.truncatedNote);
+    const tail = [`[cursor ${cursor}]`];
+    if (terminal) {
+        tail.push(`[done] the job finished. Read more with bash_output({ service: "${job.id}" }) if you need it.`);
+    }
+    else {
+        const quiet = formatDuration(Math.max(0, nowMs - job.lastOutputAt));
+        tail.push(`[wait ${args.waitSeconds}s] still running. No output for ${quiet}.`);
+        tail.push(`[next] job_wait({ job: "${job.id}", since: ${cursor} }) to keep waiting, ` +
+            'or continue with other work.');
+    }
+    // TWELVE LINES, AND THE ROW BLOCK IS THE ONLY ELASTIC PART. Its header costs a
+    // line of its own, so the budget is computed with it already deducted; a stalled
+    // or truncated job therefore loses output rows rather than the sentence that
+    // says what is wrong.
+    const rowLineHint = rows.length > 0 ? 1 : 0;
+    const budget = Math.max(0, 12 - fixed.length - tail.length - rowLineHint);
+    const shown = rows.slice(-Math.min(PROC_LIMITS.waitTailRows, budget));
+    const sinceClause = since === undefined ? '' : ` since ${since}`;
+    return [
+        ...fixed,
+        ...(shown.length > 0 ? [`[... ${shown.length} row(s)${sinceClause} ...]`] : []),
+        ...shown.map((row) => `  ${row}`),
+        ...tail,
+    ];
+}
+/** The three-state "no such id" answer (RV-P2-7). */
+function unknownJobMessage(deps, requested) {
+    // RECLAIMED FIRST, AND THAT ORDER IS THE POINT (RV-P2-7). State two is the one
+    // that costs money if it is missed: a model told `No job "t9"` about a
+    // forty-minute training run that FINISHED will start it again. The live-id list
+    // is only useful once we know the id never named a job this session.
+    const reclaimed = deps.terminalRecord?.(requested);
+    if (reclaimed) {
+        return errorResult(`Job "${requested}" already finished (${reclaimed.kind} ${reclaimed.status}) and was ` +
+            'reclaimed; its outcome was delivered in a <job_notices> block. Do not re-run it.');
+    }
+    const live = deps.supervisor
+        .list()
+        .filter((job) => !isTerminalStatus(job.status))
+        .slice(0, PROC_LIMITS.listRows)
+        .map((job) => `${job.id} (${job.status} ${formatDuration(Date.now() - job.startedAt)})`);
+    if (live.length > 0) {
+        return errorResult(`No job "${requested}". Live: ${live.join(', ')}. ` +
+            'Call job_list for detail.');
+    }
+    return errorResult(`No job "${requested}". Start one with bash({ command, background: true }).`);
+}
+function isLive(job) {
+    return !isTerminalStatus(job.status);
+}
+export function makeJobWait(deps) {
+    const memory = new Map();
+    return defineTool({
+        name: 'job_wait',
+        label: 'Wait for job',
+        description: 'Wait a bounded time for a background job (service or task) and return its ' +
+            'status, one line of progress, and only the output since `since`. Returns ' +
+            'immediately when the job is already finished. Waiting is bounded (5-60s), ' +
+            'so call it again only after deciding what to do.',
+        parameters: {
+            type: 'object',
+            properties: {
+                job: { type: 'string', description: '"t3", "s1", or "all".' },
+                timeoutSeconds: {
+                    type: 'number',
+                    description: '5-60. Omit for the configured default.',
+                },
+                since: {
+                    type: 'number',
+                    description: 'Cursor from a previous call; omit for the smallest useful window.',
+                },
+            },
+            required: ['job'],
+        },
+        async execute(_id, rawParams, ctx) {
+            const params = rawParams;
+            const requested = String(params.job);
+            const targets = requested === 'all'
+                ? deps.supervisor.list().filter(isLive).map((job) => job.id)
+                : [requested];
+            if (requested !== 'all' && !deps.supervisor.get(requested)) {
+                return unknownJobMessage(deps, requested);
+            }
+            if (targets.length === 0) {
+                return textResult('No background jobs are running. Start one with ' +
+                    'bash({ command, background: true }).');
+            }
+            const waitSeconds = clampWaitSeconds(deps, params.timeoutSeconds);
+            const outcome = await waitForJob(deps.supervisor, {
+                targets,
+                timeoutMs: waitSeconds * 1000,
+                ...(ctx.signal ? { signal: ctx.signal } : {}),
+                ...(params.since !== undefined ? { since: params.since } : {}),
+            });
+            if (outcome.aborted) {
+                return errorResult(`The wait on ${targets.join(', ')} was aborted after ` +
+                    `${formatDuration(outcome.waitedMs)}. The job was not stopped; ` +
+                    'call job_wait again when you want to keep waiting.');
+            }
+            const nowMs = Date.now();
+            const stallSeconds = deps.stallSeconds();
+            const blocks = [];
+            for (const job of outcome.jobs) {
+                const page = outcome.pages.get(job.id);
+                // THE CARRY LINE IS NOT AN INCREMENT WHEN IT HAS NOT MOVED (RV-P1-5). A
+                // carriage-return-rewritten progress bar completes no rows, so the ring
+                // hands the same line back on every wait: reprinting it would spend the
+                // six-row budget on one unchanging sentence, and counting it as new output
+                // would reset the spin guard so a genuinely stalled job never earns its
+                // `[guard]` line. It still reports through `[progress] (unchanged)`.
+                const { rows: rowsNew, carry } = splitCarry(page);
+                const carryUnchanged = carry.length > 0 && carry === memory.get(job.id)?.lastCarry;
+                const carryMoved = carry.length > 0 && !carryUnchanged;
+                const shownRows = carryMoved ? [...rowsNew, carry] : rowsNew;
+                const memoryForJob = memory.get(job.id) ?? { noChange: 0 };
+                const previous = memoryForJob.lastProgress;
+                const current = job.progress?.text;
+                // TWO DIFFERENT QUESTIONS, deliberately kept apart:
+                //  - `progressUnchanged` is a RENDERING decision (print `(unchanged)`);
+                //  - `advanced` is the SPIN-GUARD decision, and the first wait of a job is
+                //    always "advanced" because it establishes the baseline. Counting it
+                //    otherwise would put the guard line on the sixth wait instead of the
+                //    seventh (AC-20).
+                const hasBaseline = previous !== undefined;
+                const progressUnchanged = hasBaseline && current === previous;
+                const newRows = shownRows.length;
+                const advanced = !hasBaseline || newRows > 0 || !progressUnchanged;
+                memoryForJob.noChange = advanced ? 0 : memoryForJob.noChange + 1;
+                if (current !== undefined)
+                    memoryForJob.lastProgress = current;
+                if (carry.length > 0)
+                    memoryForJob.lastCarry = carry;
+                memory.set(job.id, memoryForJob);
+                // THE SPIN GUARD (R-3): counted per job, reset by ANY change. It never
+                // refuses the wait; it prepends one line naming four ways out.
+                const guard = memoryForJob.noChange >= deps.maxConsecutiveWaits
+                    ? [
+                        `[guard] ${memoryForJob.noChange} waits with no change. This job may be stalled. ` +
+                            'Options: keep waiting, stop it (bash_kill), read the tail (bash_output), or ask the user.',
+                    ]
+                    : [];
+                blocks.push([
+                    ...guard,
+                    ...renderJobBlock({
+                        job,
+                        rows: shownRows,
+                        cursor: page?.cursor ?? job.rowsSeen,
+                        since: params.since,
+                        nowMs,
+                        stalledSeconds: stallSeconds,
+                        waitSeconds,
+                        progressUnchanged,
+                        truncatedNote: page?.truncated === true
+                            ? '[note] older rows were dropped - the tail keeps the last ' +
+                                `${PROC_LIMITS.serviceTailRows} rows` +
+                                (job.logPath ? `. Full log: ${job.logPath}` : '.')
+                            : undefined,
+                    }),
+                ]);
+            }
+            const shown = blocks.slice(0, PROC_LIMITS.listRows);
+            const lines = shown.flat();
+            if (blocks.length > shown.length) {
+                lines.push(`[... ${blocks.length - shown.length} more job(s): job_list ...]`);
+            }
+            return textResult(lines.join('\n'));
+        },
+    });
+}
+export function makeJobList(deps) {
+    return defineTool({
+        name: 'job_list',
+        label: 'List jobs',
+        description: 'One line per background job: id, kind, status, elapsed, progress. Use it ' +
+            'when you need the id you started.',
+        parameters: { type: 'object', properties: {} },
+        async execute() {
+            const jobs = deps.supervisor.list();
+            if (jobs.length === 0) {
+                return textResult('No background jobs. Start one with bash({ command, background: true }).');
+            }
+            const nowMs = Date.now();
+            // LIVE FIRST, then by start time - the same trade `selectPanelRows` makes
+            // for the team panel: what is running is what the reader wants.
+            const ordered = [...jobs].sort((a, b) => {
+                const liveDelta = Number(isLive(b)) - Number(isLive(a));
+                return liveDelta !== 0 ? liveDelta : a.startedAt - b.startedAt;
+            });
+            const rows = ordered.slice(0, PROC_LIMITS.listRows).map((job) => oneRow(job, nowMs));
+            const liveCount = jobs.filter(isLive).length;
+            const serviceCount = jobs.filter((job) => job.kind === 'service').length;
+            const taskCount = jobs.length - serviceCount;
+            const summary = `${liveCount} live of ${jobs.length} (${taskCount} task, ${serviceCount} service). ` +
+                'Wait: job_wait({ job: "<id>" }). Full tail: bash_output({ service: "<id>", since: <cursor> }).';
+            if (ordered.length > rows.length)
+                rows.push(`[+${ordered.length - rows.length} more]`);
+            return textResult([...rows, summary].join('\n'));
+        },
+    });
+}
+/** `t3  task  running  12m34s  47%` - one line, fixed column count. */
+function oneRow(job, nowMs) {
+    const elapsed = formatDuration((job.endedAt ?? nowMs) - job.startedAt);
+    const aside = job.progress?.text ?? job.url ?? '';
+    return `${job.id}  ${job.kind}  ${job.status}  ${elapsed}${aside ? `  ${aside}` : ''}`;
+}
+/**
+ * Append pending `<job_notices>` to every tool result (the PULL channel).
+ *
+ * SAME SHAPE AS `withMailboxTail`, AND FOR THE SAME REASON: the engine is told
+ * nothing, the wrapper rides `{...tool, execute}`, and the notice is delivered on
+ * the next tool call whatever that call is. The queue is drained EVEN WHEN the
+ * wrapped tool errored - a refused `bash` is still a delivery opportunity.
+ */
+export function withJobNoticeTail(tool, drain) {
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const result = await original(id, params, ctx);
+            const block = renderJobNotices(drain());
+            if (block.length === 0)
+                return result;
+            return { ...result, content: [...result.content, { type: 'text', text: block }] };
+        },
+    };
+}

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

@@ -17,7 +17,7 @@
  * command is still arbitrary.
  */
 import { type AgentTool } from '@aragon-agent/core';
-import type { ProcSupervisorPort } from '../proc/types.js';
+import { type ProcSupervisorPort } from '../proc/types.js';
 export interface ProcToolDeps {
     supervisor: ProcSupervisorPort;
 }

package/dist/tools/proc-tools.js

@@ -18,9 +18,16 @@
  */
 import { defineTool, errorResult, textResult } from '@aragon-agent/core';
 import { PROC_LIMITS } from '../proc/limits.js';
-/** One line of status, shared by both tools so the two can never disagree. */
+import { isTerminalStatus } from '../proc/types.js';
+/**
+ * One line of status, shared by both tools so the two can never disagree.
+ *
+ * IT NAMES THE KIND, because `s1` and `t3` are two different things to be holding
+ * and the model has to know which one it is looking at to decide whether waiting
+ * is even meaningful.
+ */
 function statusLine(service) {
-    const bits = [`service ${service.id}  ${service.status}`];
+    const bits = [`${service.kind} ${service.id}  ${service.status}`];
     if (service.url)
         bits.push(service.url);
     if (service.exitCode !== null)
@@ -31,18 +38,30 @@ function statusLine(service) {
         bits.push('(may have left a detached child)');
     return `${bits.join('  ')}\n$ ${service.command}`;
 }
+/** `[progress] 47%` and `[stalled] ...` - the two lines worth adding to a tail. */
+function progressLines(service) {
+    const lines = [];
+    if (service.progress)
+        lines.push(`[progress] ${service.progress.text}`);
+    if (service.stalled === true) {
+        lines.push('[stalled] no output for a while - it has not failed. Keep waiting, stop it ' +
+            `with bash_kill({ service: "${service.id}" }), or read the tail.`);
+    }
+    return lines;
+}
 export function makeBashOutput(deps) {
     return defineTool({
         name: 'bash_output',
-        label: 'Service log',
-        description: 'Read a background service log tail and its current status. Pass the ' +
+        label: 'Job log',
+        description: 'Read a background job log tail and its current status. Pass the ' +
             '`since` cursor returned by a previous call to read only what is new. ' +
-            'Use this to verify a service actually started, and to read a build or ' +
-            'test watcher as it runs.',
+            'Accepts both ids: "s1" for a service and "t3" for a task. Use this to ' +
+            'verify a service actually started, and to read a build or test watcher ' +
+            'as it runs.',
         parameters: {
             type: 'object',
             properties: {
-                service: { type: 'string', description: 'The service id, e.g. "s1".' },
+                service: { type: 'string', description: 'The job id: "s1" or "t3".' },
                 since: {
                     type: 'number',
                     description: 'Cursor from a previous call; omit to read the whole tail.',
@@ -54,13 +73,18 @@ export function makeBashOutput(deps) {
             const params = rawParams;
             const service = deps.supervisor.get(params.service);
             if (!service) {
-                return errorResult(`No service "${params.service}". Start one with bash({ command, background: true }).`);
+                return errorResult(`No job "${params.service}". Start one with bash({ command, background: true }).`);
             }
             const page = deps.supervisor.read(params.service, params.since);
-            const lines = [statusLine(service)];
+            const lines = [statusLine(service), ...progressLines(service)];
             if (page?.truncated) {
+                // THE PATH IS THE ESCAPE HATCH (long-task-jobs §4.8). Past 200 rows the
+                // ring has forgotten the error the model needs, and the full log is on
+                // disk; naming it lets `grep`/`read_file` answer a question this buffer
+                // no longer can.
                 lines.push(`[note] older rows were dropped - the tail keeps the last ` +
-                    `${PROC_LIMITS.serviceTailRows} rows.`);
+                    `${PROC_LIMITS.serviceTailRows} rows` +
+                    (service.logPath ? `. Full log: ${service.logPath}` : '.'));
             }
             if (!page || page.rows.length === 0) {
                 lines.push('(no new output)');
@@ -76,27 +100,35 @@ export function makeBashOutput(deps) {
 export function makeBashKill(deps) {
     return defineTool({
         name: 'bash_kill',
-        label: 'Stop service',
-        description: 'Stop a background service by id, or every service with "all". Stop the ' +
-            'services you started once you are finished with them, unless the user ' +
-            'asked for them to stay up.',
+        label: 'Stop job',
+        description: 'Stop a background job (service or task) by id, or every job with "all". ' +
+            'Stop the jobs you started once you are finished with them, unless the ' +
+            'user asked them to stay up.',
         parameters: {
             type: 'object',
             properties: {
-                service: { type: 'string', description: 'The service id, or "all".' },
+                service: { type: 'string', description: 'The job id ("s1" or "t3"), or "all".' },
             },
             required: ['service'],
         },
         async execute(_id, rawParams) {
             const params = rawParams;
             if (params.service !== 'all' && !deps.supervisor.get(params.service)) {
-                return errorResult(`No service "${params.service}".`);
+                return errorResult(`No job "${params.service}".`);
             }
             const stopped = await deps.supervisor.stop(params.service);
             if (stopped.length === 0)
                 return textResult('Nothing to stop.');
             const lines = stopped.map((s) => statusLine(s));
-            return textResult(`Stopped ${stopped.length} service${stopped.length === 1 ? '' : 's'}.\n${lines.join('\n')}`);
+            // A JOB THAT HAD ALREADY FINISHED IS NOT A STOP (AC-37). `stop()` returns
+            // the snapshot either way, so the count has to exclude terminal records or
+            // `bash_kill` reports having killed something that ended ten minutes ago.
+            const ended = stopped.filter((s) => isTerminalStatus(s.status)).length;
+            const killed = stopped.length - ended;
+            const summary = killed === 0
+                ? `Nothing to stop - ${stopped.length === 1 ? 'it had' : 'they had'} already finished.`
+                : `Stopped ${killed} job${killed === 1 ? '' : 's'}.`;
+            return textResult(`${summary}\n${lines.join('\n')}`);
         },
     });
 }

package/dist/ui/ActivityLine.js

@@ -10,6 +10,13 @@ export function liveSpinner(reducedMotion, caps) {
 }
 /** Explicit execution facts outrank compatibility tool names and rotating phrases. */
 export function resolveActivityLabel(activity, glyphs) {
+    // A WAIT OUTRANKS EVERYTHING BELOW IT, and sits ABOVE `runningTool` on purpose:
+    // "Running job_wait" names the tool, "Waiting on t3 (up to 30s)" names the
+    // situation. It is placed after the phase/outcome branch because a settled run
+    // must never claim to be waiting for anything.
+    if (activity.phase === undefined && activity.outcome === undefined && activity.wait) {
+        return `Waiting on ${activity.wait.jobId} (up to ${activity.wait.upToSeconds}s)`;
+    }
     if (activity.phase !== undefined || activity.activeTool !== undefined || activity.outcome !== undefined) {
         return phaseLabels({
             phase: activity.phase ?? (activity.activeTool ? 'tool' : 'idle'),