@aragon-agent/cli 0.5.2 → 0.5.3

package/dist/config/store.js

@@ -14,7 +14,7 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampSkillsConfig, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampSkillsConfig, clampTeamConfig, stripLegacyStateKeys, } from './schema.js';
 // Re-exported so the many existing importers of `store.js` keep working; the
 // definitions live in `app-paths.ts` because they are pure path arithmetic.
 export { getConfigPath, getSessionsDir };
@@ -82,19 +82,24 @@ export function writeConfigFile(config) {
  * Unlike `readConfigFile`, this always returns a complete `PersistedConfig`.
  */
 export function loadPersistedConfig() {
-    const partial = readConfigFile().config ?? {};
+    // STRIP BEFORE THE SPREAD, not after. `partial` is the raw file, so any
+    // `promptHistory` / `submitCount` / `mouseNoticeSeen` / `recentModels` left
+    // on disk would otherwise ride the spread into `merged` and be written back
+    // out by `updatePersistedConfig` — the "I deleted it and it grew back" bug
+    // that `stripLegacyStateKeys` exists to make impossible (§4.5).
+    const partial = stripLegacyStateKeys(readConfigFile().config ?? {});
     return {
         ...DEFAULT_CONFIG,
         ...partial,
         version: CONFIG_VERSION,
         apiKeys: { ...DEFAULT_CONFIG.apiKeys, ...(partial.apiKeys ?? {}) },
-        recentModels: partial.recentModels ?? [],
-        promptHistory: partial.promptHistory ?? [],
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
         skills: clampSkillsConfig({ ...DEFAULT_CONFIG.skills, ...(partial.skills ?? {}) }),
         // `log` is the third. Same one-level rule, same merge.
         log: clampLogConfig({ ...DEFAULT_CONFIG.log, ...(partial.log ?? {}) }),
+        // `team` is the fourth. Same one-level rule, same merge.
+        team: clampTeamConfig({ ...DEFAULT_CONFIG.team, ...(partial.team ?? {}) }),
     };
 }
 /**
@@ -132,6 +137,10 @@ export function updatePersistedConfig(patch) {
         // replace the whole section and quietly revert `maxFiles`, `previewChars`
         // and — worst of all — `redactSecrets`.
         log: clampLogConfig({ ...current.log, ...(patch.log ?? {}) }),
+        // The fourth section, and it needs the merge for the same reason: `/team max
+        // 4` sends `{ team: { maxSubagents: 4 } }`, which a shallow spread would
+        // turn into "changing the fan-out width silently reverted every timeout".
+        team: clampTeamConfig({ ...current.team, ...(patch.team ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/config/ui-state.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `<home>/state.json` — UI bookkeeping (config-state-separation §4.4).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT MAY LIVE HERE: UI bookkeeping SCALARS. Counters, and "has this one-shot
+ * notice been shown" flags. NOTHING ELSE.
+ *
+ * Anything carrying user content, and anything that grows with usage, opens its
+ * own file. This rule is not a preference — it is the entire reason this module
+ * exists. `config.json` became a place where a prompt-by-prompt transcript sat
+ * next to the API key precisely because nobody had written a rule like this
+ * down, and a file called `state.json` is the most inviting drawer in the
+ * codebase (Q-4 / RV-8).
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Nothing here is a preference: none of these fields has a flag, an env var or
+ * a `config set` key, and none of them should ever get one. Losing the file
+ * costs a composer hint reappearing once.
+ *
+ * FAILURE POLICY (C2): never throws, exactly like `prompt-history.ts` and
+ * `skills/usage.ts`. Writes are immediate rather than debounced (D-7) — the
+ * file is one small object, and a debounce would add a flush-on-exit obligation
+ * whose failure mode is the counter silently not sticking.
+ *
+ * NOT the same thing as `migrate-legacy-state.ts`, despite the shared word:
+ * that one is the 0.4.x legacy-to-current brand migration and has nothing to do
+ * with this file.
+ */
+export declare const UI_STATE_FILENAME = "state.json";
+export declare const UI_STATE_SCHEMA = 1;
+export interface UiState {
+    schema: number;
+    /** Lifetime submit count; drives the composer hint fade (`HINT_FADE_AFTER`). */
+    submitCount: number;
+    /** Whether the one-shot "hold Shift to select text" notice has been shown. */
+    mouseNoticeSeen: boolean;
+}
+/** Read the state, caching it for the life of the process. Never throws. */
+export declare function loadUiState(): UiState;
+export declare function readSubmitCount(): number;
+/** Increment, persist, and return the new value. */
+export declare function bumpSubmitCount(): number;
+export declare function getMouseNoticeSeen(): boolean;
+export declare function setMouseNoticeSeen(seen: boolean): void;
+/**
+ * Migration-only: fill in fields that are still at their default, and never
+ * overwrite a value already here. A second import — after a half-finished
+ * migration retries — must not walk the counter backwards.
+ */
+export declare function importLegacyUiState(patch: Partial<Pick<UiState, 'submitCount' | 'mouseNoticeSeen'>>): void;
+/** Test-only: forget the cached state. */
+export declare function resetUiStateForTests(): void;

package/dist/config/ui-state.js

@@ -0,0 +1,149 @@
+/**
+ * `<home>/state.json` — UI bookkeeping (config-state-separation §4.4).
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * WHAT MAY LIVE HERE: UI bookkeeping SCALARS. Counters, and "has this one-shot
+ * notice been shown" flags. NOTHING ELSE.
+ *
+ * Anything carrying user content, and anything that grows with usage, opens its
+ * own file. This rule is not a preference — it is the entire reason this module
+ * exists. `config.json` became a place where a prompt-by-prompt transcript sat
+ * next to the API key precisely because nobody had written a rule like this
+ * down, and a file called `state.json` is the most inviting drawer in the
+ * codebase (Q-4 / RV-8).
+ * ══════════════════════════════════════════════════════════════════════════
+ *
+ * Nothing here is a preference: none of these fields has a flag, an env var or
+ * a `config set` key, and none of them should ever get one. Losing the file
+ * costs a composer hint reappearing once.
+ *
+ * FAILURE POLICY (C2): never throws, exactly like `prompt-history.ts` and
+ * `skills/usage.ts`. Writes are immediate rather than debounced (D-7) — the
+ * file is one small object, and a debounce would add a flush-on-exit obligation
+ * whose failure mode is the counter silently not sticking.
+ *
+ * NOT the same thing as `migrate-legacy-state.ts`, despite the shared word:
+ * that one is the 0.4.x legacy-to-current brand migration and has nothing to do
+ * with this file.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import process from 'node:process';
+import { getHomeRoot, getUiStatePath } from './app-paths.js';
+export const UI_STATE_FILENAME = 'state.json';
+export const UI_STATE_SCHEMA = 1;
+const DEFAULT_UI_STATE = {
+    schema: UI_STATE_SCHEMA,
+    submitCount: 0,
+    mouseNoticeSeen: false,
+};
+let memory = null;
+function coerceCount(value) {
+    const n = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_UI_STATE.submitCount;
+    return Math.floor(n);
+}
+/**
+ * Per-field tolerance: one nonsense value must not take the other field with
+ * it. A wrong SCHEMA is different — the shape is no longer known, so the whole
+ * object falls back (the rule `skills/usage.ts` already follows).
+ */
+function readFromDisk() {
+    const path = getUiStatePath();
+    if (!existsSync(path))
+        return { ...DEFAULT_UI_STATE };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return { ...DEFAULT_UI_STATE };
+        if (parsed.schema !== UI_STATE_SCHEMA)
+            return { ...DEFAULT_UI_STATE };
+        return {
+            schema: UI_STATE_SCHEMA,
+            submitCount: coerceCount(parsed.submitCount),
+            mouseNoticeSeen: typeof parsed.mouseNoticeSeen === 'boolean'
+                ? parsed.mouseNoticeSeen
+                : DEFAULT_UI_STATE.mouseNoticeSeen,
+        };
+    }
+    catch {
+        return { ...DEFAULT_UI_STATE };
+    }
+}
+/** Read the state, caching it for the life of the process. Never throws. */
+export function loadUiState() {
+    if (memory === null)
+        memory = readFromDisk();
+    return memory;
+}
+/**
+ * Atomic write: temp file, rename, re-chmod.
+ *
+ * `mkdirSync` first for the reason spelled out in `prompt-history.ts`: `<home>`
+ * is not guaranteed to exist, and without it the counter would silently never
+ * persist on a fresh install that also turned file logging off (RV-2).
+ * The `chmodSync` matches `store.ts` — rename does not preserve mode on every
+ * platform (RV-6).
+ */
+function writeToDisk(state) {
+    const path = getUiStatePath();
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        if (process.platform !== 'win32')
+            chmodSync(path, 0o600);
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the value simply stays in memory (C2).
+        }
+    }
+}
+function update(patch) {
+    const next = { ...loadUiState(), ...patch, schema: UI_STATE_SCHEMA };
+    memory = next;
+    writeToDisk(next);
+    return next;
+}
+export function readSubmitCount() {
+    return loadUiState().submitCount;
+}
+/** Increment, persist, and return the new value. */
+export function bumpSubmitCount() {
+    return update({ submitCount: readSubmitCount() + 1 }).submitCount;
+}
+export function getMouseNoticeSeen() {
+    return loadUiState().mouseNoticeSeen;
+}
+export function setMouseNoticeSeen(seen) {
+    update({ mouseNoticeSeen: seen });
+}
+/**
+ * Migration-only: fill in fields that are still at their default, and never
+ * overwrite a value already here. A second import — after a half-finished
+ * migration retries — must not walk the counter backwards.
+ */
+export function importLegacyUiState(patch) {
+    const current = loadUiState();
+    const next = {};
+    if (patch.submitCount !== undefined &&
+        current.submitCount === DEFAULT_UI_STATE.submitCount) {
+        next.submitCount = coerceCount(patch.submitCount);
+    }
+    if (patch.mouseNoticeSeen !== undefined &&
+        current.mouseNoticeSeen === DEFAULT_UI_STATE.mouseNoticeSeen) {
+        next.mouseNoticeSeen = patch.mouseNoticeSeen === true;
+    }
+    if (Object.keys(next).length === 0)
+        return;
+    update(next);
+}
+/** Test-only: forget the cached state. */
+export function resetUiStateForTests() {
+    memory = null;
+}

package/dist/logging/install.d.ts

@@ -161,3 +161,88 @@ export type AgentLogEvent = {
  * (or a future second controller) read another's clock.
  */
 export declare function attachAgentEvents(logger: Logger, controller: AgentEventSource): () => void;
+/**
+ * What `attachTeamEvents` needs from a controller. Structural for the same
+ * reason `AgentEventSource` is, and OPTIONAL on the method: a controller built
+ * with team mode off has no runtime and therefore no events.
+ */
+export interface TeamEventSource {
+    subscribeTeam?(listener: (event: TeamLogEvent) => void): () => void;
+}
+/** The five members of the CLI-local `TeamEvent` union, as this module reads them. */
+export type TeamLogEvent = {
+    type: 'dispatch_start';
+    dispatchId: string;
+    requested: number;
+    specs?: Array<{
+        label?: string;
+        description?: string;
+        prompt?: string;
+    }>;
+} | {
+    type: 'agent_update';
+    dispatchId: string;
+    run?: {
+        label?: string;
+        phase?: string;
+        lastTool?: string;
+    };
+} | {
+    type: 'usage';
+    dispatchId: string;
+    label?: string;
+    usage?: unknown;
+} | {
+    type: 'message';
+    dispatchId: string;
+    message?: {
+        from?: string;
+        to?: string;
+        subject?: string;
+        body?: string;
+    };
+} | {
+    type: 'dispatch_end';
+    dispatchId: string;
+    outcome?: {
+        startedAt?: number;
+        endedAt?: number;
+        aborted?: boolean;
+        runs?: Array<{
+            phase?: string;
+            error?: string;
+            filesTouched?: string[];
+        }>;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+        };
+    };
+};
+/**
+ * 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 declare function attachTeamEvents(logger: Logger, controller: TeamEventSource): () => void;

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;