@aragon-agent/cli 0.5.2 → 0.5.4

package/dist/logging/install.js

@@ -300,3 +300,97 @@ export function attachAgentEvents(logger, controller) {
         }
     });
 }
+/**
+ * Record a dispatch's lifecycle.
+ *
+ * WITHOUT THIS, A DISPATCH LEAVES NO TRACE IN THE LOG AT ALL (P1-2 / R-19).
+ * `TeamEvent` is deliberately CLI-local (D-10), so `attachAgentEvents` cannot
+ * see it — which is the wrong outcome for the one feature in this CLI that runs
+ * five agents the user cannot watch, and whose only other artefact is a report
+ * written by the thing that failed. A separate function rather than a branch in
+ * `attachAgentEvents` (D-19): the two consume different unions and want
+ * different level policies.
+ *
+ * TWO RULES, BOTH ABOUT NOT TURNING A LOG INTO A LIABILITY:
+ *
+ *  - A subagent's PROMPT and its SUMMARY are `trace` only, and go through the
+ *    same redaction every other record does. A `prompt` is up to 8 000
+ *    characters of whatever the lead decided to say; at `debug` it would
+ *    dominate the file.
+ *  - A `team_send` BODY is never recorded at any level. The subject is enough to
+ *    reconstruct who talked to whom and when, which is the diagnostic question;
+ *    the body is user content that reached no other sink.
+ *
+ * `agent_update` is recorded on PHASE TRANSITIONS ONLY, not on the 120 ms
+ * coalescer tick: that throttle exists to protect React, and five children at
+ * eight events a second each is 40 lines a second of noise that would push the
+ * retention window down to minutes.
+ */
+export function attachTeamEvents(logger, controller) {
+    if (!controller.subscribeTeam)
+        return () => { };
+    const lastPhase = new Map();
+    return controller.subscribeTeam((event) => {
+        switch (event.type) {
+            case 'dispatch_start': {
+                const specs = event.specs ?? [];
+                logger.info('agent', 'team_dispatch_start', {
+                    dispatchId: event.dispatchId,
+                    requested: event.requested,
+                    accepted: specs.length,
+                    labels: specs.map((s) => s.label ?? '?'),
+                });
+                for (const spec of specs) {
+                    logger.trace('agent', 'team_subagent_brief', {
+                        dispatchId: event.dispatchId,
+                        label: spec.label,
+                        description: spec.description,
+                        prompt: spec.prompt,
+                    });
+                }
+                break;
+            }
+            case 'agent_update': {
+                const key = `${event.dispatchId}:${event.run?.label ?? '?'}`;
+                const phase = event.run?.phase ?? 'unknown';
+                if (lastPhase.get(key) === phase)
+                    break;
+                lastPhase.set(key, phase);
+                logger.debug('agent', 'team_agent_update', {
+                    dispatchId: event.dispatchId,
+                    label: event.run?.label,
+                    phase,
+                    lastTool: event.run?.lastTool,
+                });
+                break;
+            }
+            case 'message':
+                logger.debug('agent', 'team_message', {
+                    dispatchId: event.dispatchId,
+                    from: event.message?.from,
+                    to: event.message?.to,
+                    // SUBJECT ONLY. See the rule above; the body never leaves the process.
+                    subject: event.message?.subject,
+                });
+                break;
+            case 'dispatch_end': {
+                const outcome = event.outcome;
+                const runs = outcome?.runs ?? [];
+                const ok = runs.filter((r) => r.phase === 'done' && !r.error).length;
+                logger.info('agent', 'team_dispatch_end', {
+                    dispatchId: event.dispatchId,
+                    durationMs: Math.max(0, (outcome?.endedAt ?? 0) - (outcome?.startedAt ?? 0)),
+                    ok,
+                    failed: runs.length - ok,
+                    aborted: outcome?.aborted === true,
+                    in: outcome?.usage?.inputTokens ?? 0,
+                    out: outcome?.usage?.outputTokens ?? 0,
+                    filesTouched: [...new Set(runs.flatMap((r) => r.filesTouched ?? []))],
+                });
+                break;
+            }
+            default:
+                break;
+        }
+    });
+}

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'history';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/session/persist.d.ts

@@ -21,4 +21,20 @@ export declare function saveSession(filePath: string, data: {
     messages: Message[];
     entries: Entry[];
 }): void;
+/**
+ * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5).
+ *
+ * `saveSession` writes `entries` verbatim and `loadSession` validates only
+ * array-ness, so a session saved while a dispatch was in flight resumes with a
+ * `kind: 'team'` entry claiming `active: true` while nothing is running. TWO
+ * things then go wrong at once: the card spins forever, and `Transcript`'s
+ * settled boundary is MONOTONIC — an entry that never settles never reaches
+ * `<Static>` and is re-rendered on every frame for the rest of the session.
+ *
+ * `aborted: true` is also simply TRUE: the children died with the process.
+ *
+ * This belongs in the LOAD path rather than the reducer because the reducer
+ * never legitimately sees a stale-active entry — only the file does.
+ */
+export declare function normalizeLoadedEntries(entries: Entry[]): Entry[];
 export declare function loadSession(filePath: string): SavedSession;

package/dist/session/persist.js

@@ -41,11 +41,29 @@ export function saveSession(filePath, data) {
     };
     writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
 }
+/**
+ * Settle any team entry that was saved mid-dispatch (team-subagents §5.3 / P1-5).
+ *
+ * `saveSession` writes `entries` verbatim and `loadSession` validates only
+ * array-ness, so a session saved while a dispatch was in flight resumes with a
+ * `kind: 'team'` entry claiming `active: true` while nothing is running. TWO
+ * things then go wrong at once: the card spins forever, and `Transcript`'s
+ * settled boundary is MONOTONIC — an entry that never settles never reaches
+ * `<Static>` and is re-rendered on every frame for the rest of the session.
+ *
+ * `aborted: true` is also simply TRUE: the children died with the process.
+ *
+ * This belongs in the LOAD path rather than the reducer because the reducer
+ * never legitimately sees a stale-active entry — only the file does.
+ */
+export function normalizeLoadedEntries(entries) {
+    return entries.map((entry) => entry.kind === 'team' && entry.active ? { ...entry, active: false, aborted: true } : entry);
+}
 export function loadSession(filePath) {
     const raw = readFileSync(filePath, 'utf-8');
     const parsed = JSON.parse(raw);
     if (!parsed || !Array.isArray(parsed.messages) || !Array.isArray(parsed.entries)) {
         throw new Error('Invalid session file (missing messages/entries).');
     }
-    return parsed;
+    return { ...parsed, entries: normalizeLoadedEntries(parsed.entries) };
 }

package/dist/team/activity.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Activity strings for the live roster (team-live-activity F-1).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope. That rule binds
+ * the LITERALS IN THIS FILE, not the runtime data flowing through it - a child
+ * may well be reading a CJK path, and `run.description` already carries model
+ * text into the same row.
+ */
+/**
+ * The only part of a tool call this module will ever render (P1-4).
+ *
+ * A PICKED SUBSET, NOT THE ARGS OBJECT. Storing `event.args` whole would put
+ * `write_file`'s `content` - a whole file - on the run, and `TeamRuntime.publish`
+ * shallow-copies the run into the live snapshot AND into every `agent_update`
+ * event, and `dispatch()` copies it again into `DispatchOutcome.runs`, which
+ * `TeamCard` holds in the transcript for the rest of the session. Two facts make
+ * that unacceptable rather than merely wasteful: the retention is unbounded in
+ * the file's size, and one `JSON.stringify` anywhere downstream would put a file
+ * body into a log - the exact liability the logging section spends a paragraph
+ * avoiding.
+ *
+ * This costs nothing in maintenance: the switch below is ALREADY a per-tool
+ * table, so a new tool is one entry either way.
+ */
+export interface ActivityArgs {
+    path?: string;
+    pattern?: string;
+    command?: string;
+    to?: string;
+    from?: string;
+}
+/** Pick at capture time. Called once per `tool_execution_start`. */
+export declare function pickActivityArgs(args: unknown): ActivityArgs;
+/**
+ * Strip anything that could corrupt the frame, collapse whitespace, and clamp.
+ *
+ * THE CONTROL-CHARACTER STRIP IS A CORRECTNESS BOUNDARY, NOT TIDINESS. This
+ * string is model-chosen and reaches an Ink <Text> unescaped. A child running
+ * `bash` with an ANSI escape in the command line would otherwise write that
+ * escape into the roster: at best a mangled row, at worst a cleared screen or a
+ * moved cursor in the middle of someone's transcript. `bash`'s own output never
+ * reaches the panel; its ARGUMENTS now do.
+ *
+ * SURROGATES ARE GUARDED AT BOTH ENDS (P2-3). The trailing guard is the obvious
+ * one. The LEADING one is needed because the caller feeds this a rolling tail
+ * built with `String.slice(-n)`, which cuts on a UTF-16 code-unit boundary and
+ * can therefore hand us a lone LOW surrogate at index 0. Either half of a split
+ * pair renders as a replacement character - the same failure `truncateBytes`
+ * guards one layer down (report.ts).
+ */
+export declare function sanitizeActivity(raw: string, maxChars: number): string;
+/**
+ * One short phrase describing a tool call.
+ *
+ * `wide` false is the narrow-terminal form (D-4). For a path-valued argument
+ * that is the basename; for `bash` it is the PROGRAM NAME (P1-6). Running the
+ * command line through `basename` is wrong twice over: `basename` splits on `/`,
+ * so `npm test -w cli` comes back whole and `./scripts/build.sh --prod` comes
+ * back as `build.sh --prod`. Neither is shorter and the second is a lie about
+ * what ran.
+ *
+ * Anything not in the table renders as its own name. That is the correct
+ * degradation for `skill_find` and for any tool a later round registers on a
+ * child: a name is always true, and inventing an argument mapping for a tool
+ * this module has not been taught is how a formatter starts lying.
+ */
+export declare function describeToolActivity(toolName: string, args: ActivityArgs | undefined, wide: boolean): string;

package/dist/team/activity.js

@@ -0,0 +1,130 @@
+/**
+ * Activity strings for the live roster (team-live-activity F-1).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope. That rule binds
+ * the LITERALS IN THIS FILE, not the runtime data flowing through it - a child
+ * may well be reading a CJK path, and `run.description` already carries model
+ * text into the same row.
+ */
+import { TEAM_LIMITS } from './limits.js';
+/** Pick at capture time. Called once per `tool_execution_start`. */
+export function pickActivityArgs(args) {
+    const a = (args ?? {});
+    const str = (v) => typeof v === 'string' && v.length > 0 ? v.slice(0, TEAM_LIMITS.activityArgChars) : undefined;
+    const picked = {};
+    const path = str(a.path);
+    const pattern = str(a.pattern);
+    const command = str(a.command);
+    const to = str(a.to);
+    const from = str(a.from);
+    if (path !== undefined)
+        picked.path = path;
+    if (pattern !== undefined)
+        picked.pattern = pattern;
+    if (command !== undefined)
+        picked.command = command;
+    if (to !== undefined)
+        picked.to = to;
+    if (from !== undefined)
+        picked.from = from;
+    return picked;
+}
+/**
+ * Strip anything that could corrupt the frame, collapse whitespace, and clamp.
+ *
+ * THE CONTROL-CHARACTER STRIP IS A CORRECTNESS BOUNDARY, NOT TIDINESS. This
+ * string is model-chosen and reaches an Ink <Text> unescaped. A child running
+ * `bash` with an ANSI escape in the command line would otherwise write that
+ * escape into the roster: at best a mangled row, at worst a cleared screen or a
+ * moved cursor in the middle of someone's transcript. `bash`'s own output never
+ * reaches the panel; its ARGUMENTS now do.
+ *
+ * SURROGATES ARE GUARDED AT BOTH ENDS (P2-3). The trailing guard is the obvious
+ * one. The LEADING one is needed because the caller feeds this a rolling tail
+ * built with `String.slice(-n)`, which cuts on a UTF-16 code-unit boundary and
+ * can therefore hand us a lone LOW surrogate at index 0. Either half of a split
+ * pair renders as a replacement character - the same failure `truncateBytes`
+ * guards one layer down (report.ts).
+ */
+export function sanitizeActivity(raw, maxChars) {
+    let src = raw;
+    const head = src.charCodeAt(0);
+    if (head >= 0xdc00 && head <= 0xdfff)
+        src = src.slice(1);
+    const flat = src
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f\x7f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (maxChars <= 0)
+        return '';
+    if (flat.length <= maxChars)
+        return flat;
+    if (maxChars <= 3)
+        return flat.slice(0, maxChars);
+    let cut = maxChars - 3;
+    const code = flat.charCodeAt(cut - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        cut -= 1;
+    return `${flat.slice(0, cut)}...`;
+}
+/** The basename of a path, for the narrow form. Pure string work: no `path`. */
+function basename(p) {
+    const parts = p.split(/[\\/]/);
+    return parts[parts.length - 1] || p;
+}
+/** The program name of a command line, for the narrow form. */
+function program(commandLine) {
+    const first = commandLine.trim().split(/\s+/)[0] ?? '';
+    return basename(first) || commandLine;
+}
+/**
+ * One short phrase describing a tool call.
+ *
+ * `wide` false is the narrow-terminal form (D-4). For a path-valued argument
+ * that is the basename; for `bash` it is the PROGRAM NAME (P1-6). Running the
+ * command line through `basename` is wrong twice over: `basename` splits on `/`,
+ * so `npm test -w cli` comes back whole and `./scripts/build.sh --prod` comes
+ * back as `build.sh --prod`. Neither is shorter and the second is a lie about
+ * what ran.
+ *
+ * Anything not in the table renders as its own name. That is the correct
+ * degradation for `skill_find` and for any tool a later round registers on a
+ * child: a name is always true, and inventing an argument mapping for a tool
+ * this module has not been taught is how a formatter starts lying.
+ */
+export function describeToolActivity(toolName, args, wide) {
+    const a = args ?? {};
+    switch (toolName) {
+        case 'read_file':
+            return detail('read', a.path, wide, basename);
+        case 'write_file':
+            return detail('write', a.path, wide, basename);
+        case 'edit_file':
+            return detail('edit', a.path, wide, basename);
+        case 'list_dir':
+            return detail('list', a.path ?? '.', wide, basename);
+        case 'glob':
+            return detail('glob', a.pattern, wide, basename);
+        case 'grep':
+            return detail('grep', a.pattern, wide, basename);
+        case 'bash':
+            return detail('bash', a.command, wide, program);
+        case 'team_send': {
+            const to = (a.to ?? '').trim();
+            return to ? `messaging ${to}` : 'messaging';
+        }
+        case 'team_wait': {
+            const from = (a.from ?? '').trim();
+            return from ? `waiting for ${from}` : 'waiting for mail';
+        }
+        default:
+            return toolName;
+    }
+}
+function detail(verb, value, wide, narrow) {
+    const v = (value ?? '').trim();
+    if (v.length === 0)
+        return verb;
+    return `${verb}: ${wide ? v : narrow(v)}`;
+}

package/dist/team/bus.d.ts

@@ -0,0 +1,190 @@
+/**
+ * TeamBus — the subagent message channel (team-subagents §3.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * The requirement asks for "lei si ren lei jiao liu de dian hua ji zhi, dan bu
+ * neng tai pin fan" — a real telephone, used sparingly. This module takes both
+ * halves literally: there IS a channel, and it is expensive on purpose. The rate
+ * limits in `TEAM_LIMITS` are the requirement, not a compromise (R-9).
+ *
+ * DELIVERY IS PIGGY-BACKED, NEVER PUSHED (D-4). A message for child B is
+ * appended to B's NEXT TOOL RESULT by `withMailboxTail`. `Agent.steer()` looks
+ * like the natural push channel and is the wrong answer: the core agent loop
+ * treats steering that arrives mid-batch by pushing "Tool execution skipped due
+ * to steering interrupt." for EVERY REMAINING TOOL CALL in that batch, so a
+ * chatty peer would cancel its colleague's work as a side effect of saying
+ * hello. Piggy-backing costs zero extra turns, cannot interfere with the loop,
+ * and is guaranteed to be seen by any child that is doing anything at all.
+ *
+ * EVERY REFUSAL IS A NON-ERROR (D-7). An `errorResult` reads to a model as a
+ * malfunction and invites an immediate retry, which is precisely the "tai pin
+ * fan" behaviour being designed out. The verdicts below carry a `reason` the
+ * caller renders as ordinary text.
+ */
+import type { TeamMessage } from './types.js';
+/** The lead's stable address. Subagents are addressed by their `label`. */
+export declare const LEAD_KEY = "lead";
+/** Broadcast address: every other participant, the lead included. */
+export declare const ALL_KEY = "all";
+export type SendVerdict = {
+    ok: true;
+    delivered: string[];
+    spent: number;
+    remaining: number;
+} | {
+    ok: false;
+    reason: 'unknown_recipient';
+    recipients: string[];
+} | {
+    ok: false;
+    reason: 'agent_quota';
+    used: number;
+    max: number;
+} | {
+    ok: false;
+    reason: 'dispatch_quota';
+    used: number;
+    max: number;
+} | {
+    ok: false;
+    reason: 'too_soon';
+    retryInSeconds: number;
+};
+/** Why `team_wait` was refused before it ever blocked (F-3). */
+export type WaitRefusal = {
+    reason: 'no_peers';
+} | {
+    reason: 'unknown_sender';
+    asked: string;
+    peers: string[];
+} | {
+    reason: 'all_finished';
+    who: string[];
+} | {
+    reason: 'all_blocked';
+    who: string[];
+};
+export interface TeamBusOptions {
+    /** Injectable clock so the interval rule is testable without real waiting. */
+    now?: () => number;
+    /** Called once per delivered message, for the `TeamEvent` stream and the log. */
+    onMessage?: (message: TeamMessage) => void;
+    /**
+     * Whether `label` still has a loop that could call `team_send`.
+     *
+     * Optional and defaulting to `() => true`, so every existing construction site
+     * and every existing test keeps its current behaviour exactly. `TeamRuntime`
+     * supplies the real answer from its live handles, and it is a NEGATIVE
+     * predicate over TERMINAL phases: a `queued` child has not started yet and
+     * will, so "the phase is running" - the obvious implementation - would refuse
+     * a wait on children 4 and 5 of a five-way dispatch at the shipped defaults.
+     */
+    canSend?: (label: string) => boolean;
+}
+export declare class TeamBus {
+    private readonly labels;
+    private readonly mailboxes;
+    private readonly waiters;
+    private readonly sentBy;
+    private readonly lastSentAt;
+    private readonly blocked;
+    private readonly lead;
+    private readonly now;
+    private readonly onMessage?;
+    private readonly canSend;
+    private total;
+    private last?;
+    constructor(labels: string[], options?: TeamBusOptions);
+    /** Every addressable participant, in dispatch order, with the lead last. */
+    participants(): string[];
+    /** Sibling labels for the `<subagent_role>` block. */
+    peersOf(label: string): string[];
+    /** Messages addressed to `lead`, for the report's own section (§3.7). */
+    leadMail(): TeamMessage[];
+    messageCount(): number;
+    lastMessage(): TeamMessage | undefined;
+    sentCount(label: string): number;
+    /**
+     * Canonical label for a model-supplied `from`, or `undefined` (P1-3).
+     *
+     * PUBLIC, because `makeTeamWait` has to hand the SAME string to
+     * `checkWaitable` and to `wait()`. `wait()` and `deliverToWaiter` compare
+     * `m.from === opts.from` EXACTLY, so a caller that gate-checks `"A2"`
+     * case-insensitively and then passes `"A2"` down would wait the full timeout
+     * for a message the delivery filter can never match.
+     */
+    resolveLabel(raw: string): string | undefined;
+    /** `team_wait` calls refused as unanswerable, per label (F-3). */
+    recordBlockedWait(label: string): void;
+    blockedWaitCount(label: string): number;
+    /**
+     * Spend quota and deliver.
+     *
+     * Refusal ORDER is deliberate: the permanent conditions are reported before
+     * the temporary one. Telling a child to "try again in 9s" when its quota is
+     * already spent sends it back for a second refusal it cannot act on.
+     */
+    send(from: string, to: string, subjectRaw: string, bodyRaw: string): SendVerdict;
+    private resolveRecipients;
+    private waiterFor;
+    /**
+     * Decide whether waiting could possibly pay off (F-3).
+     *
+     * TAKES `timeoutMs`, NOT `deadlineAt` (P1-1). The deadline is derived here,
+     * from the one clock this class has, so it is comparable with every registered
+     * `Waiter.deadlineAt`.
+     *
+     * PURE: no counters, no mutation, no waiter registration. `makeTeamWait`
+     * records the refusal, because a predicate with a counter inside it is a
+     * predicate people stop trusting (D-6).
+     *
+     * BIASED TOWARD PERMITTING (D-16). Every branch that cannot be decided returns
+     * `null`. A wait that should have been refused costs the child seconds it can
+     * see; a refusal that should have been a wait destroys a result the child
+     * cannot see was ever possible. The asymmetry is total, so the bias is total.
+     */
+    checkWaitable(key: string, opts: {
+        from?: string;
+        timeoutMs: number;
+    }): WaitRefusal | null;
+    /**
+     * Shrink `cannotAct` to its fixpoint, in place (P0-3).
+     *
+     * Everyone acceptable being stuck is NOT yet a deadlock proof, because a
+     * blocked peer can be released EARLY by a third party: `a` waits on `b`, `b`
+     * waits on `c`, `c` messages `b` at t=10, `b` resumes and messages `a`. A
+     * deadline comparison alone refuses `a` at t=0 and throws that outcome away.
+     *
+     * So a blocked peer stays in the set only while everyone who could wake it is
+     * also in it (or is the caller, who is about to block). If growth stops with
+     * an acceptable peer outside the set, that peer can still be woken and the
+     * wait must be permitted.
+     *
+     * Terminates because each pass either removes at least one member or stops. At
+     * ten participants the worst case is a hundred set lookups, once per
+     * `team_wait`, and `team_wait` is itself rate-limited by the message budget.
+     */
+    private closeCannotAct;
+    /** Take everything queued for `key`. Called by `withMailboxTail` (§3.6). */
+    drain(key: string): TeamMessage[];
+    /**
+     * Block until a matching message arrives, the signal aborts, or the deadline
+     * elapses. Resolves `null` on both non-delivery paths — from the model's point
+     * of view an abandoned wait and an expired one want the same guidance.
+     *
+     * THE CALLER PAUSES THE CHILD'S IDLE WATCHDOG around this (see
+     * `comm-tools.ts`). A deliberate wait is not a wedged agent, and the child
+     * emits nothing while it is here.
+     */
+    wait(key: string, opts: {
+        from?: string;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<TeamMessage | null>;
+    /** Settle every outstanding wait with `null`. Called on abort and dispose. */
+    cancelAllWaits(): void;
+    private deliverToWaiter;
+}
+/** Render queued mail as the `<team_mail>` block appended to a tool result. */
+export declare function renderMailBlock(messages: TeamMessage[]): string;