pikiloom 0.4.26 → 0.4.28

package/dist/agent/acp-client.js

@@ -1,37 +1,7 @@
-/**
- * Minimal Agent Client Protocol (ACP) client.
- *
- * ACP is a JSON-RPC 2.0 protocol over stdio that standardises how clients
- * (editors, orchestrators) talk to AI coding agents. Reference impls:
- * Hermes (`hermes acp`), Gemini CLI (`gemini --acp`), OpenCode, Claude Code
- * via `@zed-industries/claude-code-acp` adapter.
- *
- * This is a deliberately small implementation — it parses line-delimited
- * JSON-RPC messages, dispatches results/notifications, and lets callers
- * `request()` and consume an async stream of `sessionUpdate` notifications.
- *
- * Spec: https://agentclientprotocol.com — methods we use:
- *   client → agent:  initialize, session/new, session/load, session/prompt,
- *                    session/set_model, session/set_session_mode, session/cancel
- *   agent  → client: session/update (streaming notifications)
- *                    session/request_permission (we deny by default)
- *                    fs/read_text_file, fs/write_text_file (we say "no")
- */
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { EventEmitter } from 'node:events';
 import { agentLog, agentWarn } from './utils.js';
-/**
- * Translate a Claude-style MCP server map (keyed by name with
- * `{type?, command|url, args?, env?, headers?}`) into ACP wire format:
- *   stdio: { name, command, args, env: [{name, value}, ...] }
- *   http:  { type: "http", name, url, headers: [{name, value}, ...] }
- *   sse:   { type: "sse",  name, url, headers: [{name, value}, ...] }
- *
- * The ACP schema requires `name` plus a list-of-records `env` for stdio
- * servers — sending an object map for env, or omitting name, results in
- * a JSON-RPC -32602 (Invalid params) response.
- */
 export function toAcpMcpServers(servers) {
     if (!servers)
         return [];
@@ -57,14 +27,6 @@ export function toAcpMcpServers(servers) {
     }
     return out;
 }
-/**
- * AcpClient — encapsulates a single ACP child process.
- *
- * Events:
- *   - 'sessionUpdate' (params)   → agent → client streaming events
- *   - 'request' ({method, id, params}) → agent → client requests we must answer
- *   - 'exit' (code)              → process closed
- */
 export class AcpClient extends EventEmitter {
     opts;
     proc = null;
@@ -88,7 +50,6 @@ export class AcpClient extends EventEmitter {
         rl.on('line', line => this.handleLine(line));
         this.proc.stderr.on('data', (chunk) => {
             const text = chunk.toString();
-            // ACP stderr is reserved for human-readable diagnostics.
             for (const ln of text.split('\n')) {
                 const t = ln.trim();
                 if (t)
@@ -109,7 +70,6 @@ export class AcpClient extends EventEmitter {
     isAlive() {
         return !!this.proc && !this.exited;
     }
-    /** Send a JSON-RPC request and resolve when the agent responds. */
     async request(method, params, timeoutMs = 60_000) {
         if (!this.proc || this.exited)
             throw new Error('ACP process not running');
@@ -127,12 +87,6 @@ export class AcpClient extends EventEmitter {
             this.write({ jsonrpc: '2.0', id, method, params });
         });
     }
-    /**
-     * Best-effort request — resolves with `null` on any error or non-existent
-     * method, instead of throwing. Useful for optional methods like
-     * `session/set_session_mode` that may or may not be implemented by the
-     * agent. The error is logged but does not propagate.
-     */
     async tryRequest(method, params, timeoutMs = 15_000) {
         try {
             return await this.request(method, params, timeoutMs);
@@ -142,24 +96,17 @@ export class AcpClient extends EventEmitter {
             return null;
         }
     }
-    /** Send a notification (no response expected). */
     notify(method, params) {
         if (!this.proc || this.exited)
             return;
         this.write({ jsonrpc: '2.0', method, params });
     }
-    /** Send a JSON-RPC response back to the agent (when it asks us something). */
     respond(id, result) {
         this.write({ jsonrpc: '2.0', id, result });
     }
     respondError(id, code, message) {
         this.write({ jsonrpc: '2.0', id, error: { code, message } });
     }
-    /**
-     * Wait for the session/update event stream to go quiet for `quietMs`
-     * milliseconds, or until `maxMs` elapses. Used to drain replay events
-     * after `session/load`. Returns the number of events observed.
-     */
     async waitForQuiet(quietMs = 150, maxMs = 3_000) {
         let events = 0;
         let lastEventAt = Date.now();
@@ -179,7 +126,6 @@ export class AcpClient extends EventEmitter {
             this.off('sessionUpdate', onUpdate);
         }
     }
-    /** Gracefully shut down. */
     async close() {
         if (!this.proc || this.exited)
             return;
@@ -198,7 +144,6 @@ export class AcpClient extends EventEmitter {
             this.proc?.on('close', () => { clearTimeout(timer); resolve(); });
         });
     }
-    // ------------------------------------------------------------------------
     write(msg) {
         if (!this.proc || this.exited)
             return;
@@ -218,11 +163,9 @@ export class AcpClient extends EventEmitter {
             msg = JSON.parse(trimmed);
         }
         catch {
-            // ACP sometimes prefixes diagnostic logs to stdout; ignore non-JSON
             agentLog(`[acp:stdout-noise] ${trimmed.slice(0, 200)}`);
             return;
         }
-        // Response (has id and result/error)
         if ('id' in msg && (('result' in msg) || ('error' in msg))) {
             const resp = msg;
             const pending = this.pending.get(resp.id);
@@ -235,7 +178,6 @@ export class AcpClient extends EventEmitter {
                 pending.resolve(resp.result);
             return;
         }
-        // Notification (no id) — agent → client streaming event
         if (!('id' in msg) && 'method' in msg) {
             const n = msg;
             if (n.method === 'session/update') {
@@ -246,7 +188,6 @@ export class AcpClient extends EventEmitter {
             }
             return;
         }
-        // Request (has id and method) — agent → client RPC
         if ('id' in msg && 'method' in msg) {
             const r = msg;
             this.emit('request', { id: r.id, method: r.method, params: r.params });

package/dist/agent/artifacts.js

@@ -1,19 +1,3 @@
-/**
- * artifacts.ts — delivered-artifact manifest (the single source of truth for
- * "files the agent handed to the user during a session").
- *
- * When the agent calls `im_send_file`, the bot materializes the file into the
- * session attachments dir and appends a record here. IM channels additionally
- * push the bytes to their chat; the dashboard serves the materialized copy over
- * HTTP and renders it. Recording is terminal-agnostic, so a session watched
- * from BOTH a chat and the dashboard shows the same deliveries on either side,
- * and they survive a page reload / workspace cleanup.
- *
- * The manifest lives next to the MCP-buffered image attachments
- * (`sessionAttachmentsDir`), which is already an allowlist root for the
- * dashboard attachment endpoint — so materialized artifacts are servable with
- * no new trust boundary.
- */
 import fs from 'node:fs';
 import path from 'node:path';
 import { sessionAttachmentsDir } from './images.js';
@@ -28,7 +12,6 @@ const MIME_BY_EXT = {
     '.tar': 'application/x-tar', '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
     '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.log': 'text/plain; charset=utf-8',
 };
-/** Best-effort MIME for a delivered artifact; `application/octet-stream` when unknown. */
 export function mimeForArtifact(filePath) {
     return MIME_BY_EXT[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
 }
@@ -41,13 +24,6 @@ function deliveredDir(agent, sessionId) {
 function sanitizeName(name) {
     return (name || 'file').replace(/[/\\\0]+/g, '_').replace(/^\.+/, '').slice(0, 200) || 'file';
 }
-/**
- * Materialize `srcPath` into the session's delivered-artifacts dir so it is
- * (a) servable by the dashboard attachment endpoint (the dir is an allowlist
- * root) and (b) durable across workspace cleanup. Hardlinks when possible,
- * falling back to a copy across filesystems. The on-disk name is stamped to
- * avoid collisions; the pristine basename travels in the manifest.
- */
 export function stageDeliveredArtifact(agent, sessionId, srcPath) {
     const fileName = sanitizeName(path.basename(srcPath));
     const stat = fs.statSync(srcPath);
@@ -63,7 +39,6 @@ export function stageDeliveredArtifact(agent, sessionId, srcPath) {
     }
     return { path: dest, fileName, fileSize: stat.size, fileMime: mimeForArtifact(fileName) };
 }
-/** Append a record to the session's delivered-artifact manifest. */
 export function recordDeliveredArtifact(agent, sessionId, entry) {
     try {
         const file = manifestPath(agent, sessionId);
@@ -74,11 +49,6 @@ export function recordDeliveredArtifact(agent, sessionId, entry) {
         agentWarn(`[artifacts] record failed: ${e?.message || e}`);
     }
 }
-/**
- * Materialize + record a delivered artifact in one step. Best-effort: returns
- * the stored record (with the materialized path), or null on failure — delivery
- * must never crash the stream.
- */
 export function deliverArtifact(agent, sessionId, srcPath, opts) {
     try {
         const staged = stageDeliveredArtifact(agent, sessionId, srcPath);
@@ -100,7 +70,6 @@ export function deliverArtifact(agent, sessionId, srcPath, opts) {
         return null;
     }
 }
-/** Read the delivered-artifact manifest for a session (tolerant of partial lines). */
 export function readDeliveredArtifacts(agent, sessionId) {
     const file = manifestPath(agent, sessionId);
     let raw;
@@ -120,16 +89,10 @@ export function readDeliveredArtifacts(agent, sessionId) {
             if (rec && typeof rec.path === 'string' && rec.fileName)
                 out.push(rec);
         }
-        catch { /* skip malformed line */ }
+        catch { }
     }
     return out;
 }
-/**
- * Project the delivered-artifact manifest into pre-transport MessageBlocks
- * (content = `file://<abs>`). The dashboard read path rewrites these to
- * attachment HTTP URLs via `rewriteAttachmentBlocksForTransport`. Records whose
- * file no longer exists on disk are dropped.
- */
 export function deliveredArtifactBlocks(agent, sessionId) {
     const blocks = [];
     for (const a of readDeliveredArtifacts(agent, sessionId)) {

package/dist/agent/auto-update.js

@@ -1,6 +1,3 @@
-/**
- * Background agent CLI version checking and update prompts.
- */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -17,39 +14,18 @@ function setUpdateState(agent, patch) {
     const current = updateStates.get(agent) || emptyState();
     updateStates.set(agent, { ...current, ...patch });
 }
-/** Returns the cached update state for a specific agent (or null). */
 export function getAgentUpdateState(agent) {
     return updateStates.get(agent) || null;
 }
-/** Returns all cached update states. */
 export function getAllAgentUpdateStates() {
     const result = {};
     for (const [key, value] of updateStates)
         result[key] = value;
     return result;
 }
-// ---------------------------------------------------------------------------
-// Spawn coordination
-//
-// A CLI reinstall (`npm install -g` / `brew upgrade`) briefly tears down and
-// rewrites the bin symlink, so an agent spawn that races it execs into
-// "/bin/sh: <cli>: command not found" (exit 127). The updating process drops a
-// per-agent marker file for the duration of the destructive step; the spawn
-// path waits while it's held. The marker is cross-process (this worker AND the
-// `npx pikiloom@latest` self-bootstrap both update + spawn), and carries the
-// updater's pid so a marker orphaned by a crashed updater is detected via
-// liveness and cleaned up — a spawn never hangs on a stale marker, and a
-// genuinely-missing CLI (no marker) fails fast instead of waiting.
-// ---------------------------------------------------------------------------
-/** Path of the in-flight-reinstall marker for `agent` (one file per agent). */
 export function agentUpdateMarkerPath(agent) {
     return path.join(os.homedir(), STATE_DIR_NAME, `agent-update-${agent}.installing`);
 }
-/**
- * True when a live updater is mid-reinstall of `agent`. Reads the marker's pid
- * and probes liveness with `kill(pid, 0)`; an orphaned marker (writer gone) is
- * removed and reported idle so spawns don't hang on a crashed updater.
- */
 function agentReinstallInFlight(agent) {
     const marker = agentUpdateMarkerPath(agent);
     let raw;
@@ -57,12 +33,12 @@ function agentReinstallInFlight(agent) {
         raw = fs.readFileSync(marker, 'utf8');
     }
     catch {
-        return false; // no marker — nothing updating
+        return false;
     }
     const pid = Number.parseInt(raw.trim(), 10);
     if (Number.isInteger(pid) && pid > 0) {
         try {
-            process.kill(pid, 0); // throws ESRCH if the updater is gone
+            process.kill(pid, 0);
             return true;
         }
         catch {
@@ -73,7 +49,6 @@ function agentReinstallInFlight(agent) {
             return false;
         }
     }
-    // Unreadable pid — fall back to mtime so a corrupt marker still ages out.
     try {
         return Date.now() - fs.statSync(marker).mtimeMs <= AGENT_UPDATE_COMMAND_TIMEOUT_MS;
     }
@@ -81,11 +56,6 @@ function agentReinstallInFlight(agent) {
         return false;
     }
 }
-/**
- * Marks `agent` as mid-reinstall (cross-process) for the duration of
- * `install()` so concurrent spawns can wait it out. Always clears the marker,
- * even when the install throws.
- */
 export async function withAgentUpdateGate(agent, install) {
     const id = String(agent || '').trim();
     if (!id)
@@ -106,11 +76,6 @@ export async function withAgentUpdateGate(agent, install) {
         catch { }
     }
 }
-/**
- * Resolves once no live reinstall of `agent` is in flight, or after
- * `timeoutMs`. No-op (returns immediately) when nothing is updating. Called
- * from the spawn path so we never exec a half-swapped CLI binary.
- */
 export async function awaitAgentUpdateIdle(agent, timeoutMs) {
     const id = String(agent || '').trim();
     if (!id)
@@ -179,10 +144,6 @@ function isNpmPackageOwnedBinary(binPath, pkg, npmRoot) {
         return true;
     return isPathInside(realPackageDir, binPath);
 }
-/**
- * Check if a binary was installed via Homebrew by resolving its real path.
- * Homebrew cask binaries typically symlink through Caskroom or Cellar.
- */
 function isBrewInstalledBinary(binPath) {
     const realPath = realPathOrNull(binPath);
     const target = realPath || binPath;
@@ -196,14 +157,12 @@ export function resolveAgentUpdateStrategy(agent, npmPrefix, npmRoot = null) {
     const binPath = String(agent.path || '').trim();
     if (!binPath)
         return { kind: 'skip', reason: 'no binary path' };
-    // Check for Homebrew install first (binary resolves to Caskroom/Cellar).
     if (isBrewInstalledBinary(binPath)) {
         const cask = getAgentBrewCask(id);
         if (cask)
             return { kind: 'brew', cask };
         return { kind: 'skip', reason: 'brew-installed but no known cask' };
     }
-    // Check for npm global install.
     const npmBinDir = npmPrefix ? path.join(path.resolve(npmPrefix), 'bin') : null;
     const npmManaged = !!(npmBinDir && isPathInside(npmBinDir, binPath));
     if (!npmManaged)
@@ -223,14 +182,6 @@ async function runCommand(cmd, args, opts = {}) {
         let finished = false;
         const child = spawn(cmd, args, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            // HOMEBREW_NO_AUTO_UPDATE=1 skips brew's implicit `brew update` before
-            // each command — we already resolve the latest version via the
-            // formulae.brew.sh API, so the refresh is redundant. NOTE: this does NOT
-            // prevent brew's vendor-install-ruby step, which contends with concurrent
-            // brew processes (Homebrew's launchd autoupdate, a manual brew run, etc.)
-            // on the `vendor-install-ruby` lockf and surfaces as "Failed to upgrade
-            // Homebrew Portable Ruby". Those transient collisions are handled by
-            // `isBrewBusyError` below, which downgrades the failure to a soft skip.
             env: { ...process.env, npm_config_yes: 'true', HOMEBREW_NO_AUTO_UPDATE: '1' },
         });
         const timeoutMs = Math.max(500, opts.timeoutMs ?? AGENT_UPDATE_COMMAND_TIMEOUT_MS);
@@ -274,9 +225,6 @@ async function getNpmGlobalRoot() {
     return result.ok ? result.stdout.trim().split('\n')[0] || null : null;
 }
 async function getLatestPackageVersion(pkg) {
-    // `--prefer-online` bypasses the local npm metadata cache so we always see
-    // the registry's current `latest` tag. Without it, `npm view` can serve a
-    // stale version for several minutes after a release.
     const result = await runCommand('npm', ['view', pkg, 'version', '--json', '--prefer-online'], { timeoutMs: AGENT_UPDATE_TIMEOUTS.npmView });
     if (!result.ok)
         return null;
@@ -322,28 +270,11 @@ async function updateViaNpm(pkg) {
     const result = await runCommand('npm', ['install', '-g', `${pkg}@latest`]);
     return { ok: result.ok, detail: result.ok ? result.stdout.trim() || null : result.error };
 }
-/**
- * Detects the transient brew contention surfaced when another brew process is
- * already running its `vendor-install ruby` step (Homebrew's launchd
- * autoupdate, a manual `brew upgrade`, etc.). We treat these as soft skips
- * rather than failures so the dashboard doesn't shout an error at the user for
- * what is really "try again in a minute".
- */
 function isBrewBusyError(text) {
     if (!text)
         return false;
     return /vendor-install ruby|already locked|Failed to upgrade Homebrew Portable Ruby|is already running/i.test(text);
 }
-// ---------------------------------------------------------------------------
-// Homebrew helpers
-// ---------------------------------------------------------------------------
-/** Get latest available version for a Homebrew cask.
- *
- * Queries Homebrew's public formulae API rather than `brew info`, because the
- * local cask metadata is only refreshed by `brew update` — without it, a
- * just-published cask version can stay invisible for hours/days. The HTTPS API
- * always returns the current cask manifest. Falls back to local `brew info`
- * if the network call fails. */
 async function getLatestBrewCaskVersion(cask) {
     const apiVersion = await fetchBrewCaskVersionFromApi(cask);
     if (apiVersion)
@@ -413,7 +344,6 @@ export function startAgentAutoUpdate(opts) {
                     setUpdateState(id, { status: 'skipped', detail: strategy.reason, checkedAt: Date.now() });
                     continue;
                 }
-                // Use brew version check for brew installs, npm for npm installs.
                 const latestVersion = strategy.kind === 'brew'
                     ? await getLatestBrewCaskVersion(strategy.cask)
                     : await getLatestPackageVersion(pkg);
@@ -456,10 +386,6 @@ export function startAgentAutoUpdate(opts) {
         }
     })();
 }
-// ---------------------------------------------------------------------------
-// On-demand version check (called from dashboard)
-// ---------------------------------------------------------------------------
-/** Check latest version for a single agent. Uses brew or npm depending on install method. */
 export async function checkAgentLatestVersion(agent) {
     const id = String(agent.agent || '').trim();
     const pkg = getAgentPackage(id);
@@ -467,7 +393,6 @@ export async function checkAgentLatestVersion(agent) {
         return { ...emptyState(), status: 'skipped', detail: 'unsupported agent', checkedAt: Date.now() };
     const currentVersion = extractAgentSemver(agent.version);
     setUpdateState(id, { currentVersion, status: 'checking' });
-    // Detect brew install and use brew version check.
     const binPath = String(agent.path || '').trim();
     const brewCask = binPath && isBrewInstalledBinary(binPath) ? getAgentBrewCask(id) : null;
     const latestVersion = brewCask
@@ -490,7 +415,6 @@ export async function checkAgentLatestVersion(agent) {
     setUpdateState(id, state);
     return state;
 }
-/** Manually trigger an update for a specific agent (auto-detects brew vs npm). */
 export async function manualAgentUpdate(agent, log) {
     const id = String(agent.agent || '').trim();
     const pkg = getAgentPackage(id);

package/dist/agent/await-resume.js

@@ -1,22 +1,3 @@
-/**
- * await-resume.ts — "waiting for background work" session marker.
- *
- *   <sessionRoot>/awaiting.json — persisted marker
- *
- * A turn runs as a one-shot `claude -p` process that exits at its `result`
- * event. When the agent launches truly detached work (a daemon outliving the
- * harness, e.g. an install that must survive a restart) and ends the turn
- * intending to report back, the process exits and the session reads as plainly
- * "completed" — there is no live process for the background task to wake. This
- * marker lets the agent declare that intent (via the `await_background` MCP
- * tool, which writes the file directly) so the dashboard can show a distinct
- * "waiting" state instead of "completed".
- *
- * The MCP tool (child process) writes the file; the parent only reads and
- * clears it — the same split used by goal.ts / tools/goal.ts. The marker is
- * cleared the next time the session runs (clearAwaitResume in stream.ts), so a
- * resumed turn naturally drops back out of the "waiting" state.
- */
 import fs from 'node:fs';
 import path from 'node:path';
 const AWAIT_FILE = 'awaiting.json';
@@ -45,6 +26,5 @@ export function clearAwaitResume(workdir, agent, sessionId) {
         fs.rmSync(sessionAwaitPath(workdir, agent, sessionId), { force: true });
     }
     catch {
-        /* best-effort */
     }
 }

package/dist/agent/cli/auth.js

@@ -1,19 +1,3 @@
-/**
- * CLI auth + install runner.
- *
- * Two flows share a single streaming-child-session core:
- *
- *   - oauth-web: spawn `loginArgv`, stream stdout/stderr to the UI, poll
- *     `statusArgv` in the background, and settle when the CLI reports ready.
- *     Used by CLIs that print a device code / one-time-code non-interactively
- *     (gh, wrangler, supabase, …). CLIs whose sign-in needs a real TTY use
- *     `manualLoginCommands` instead and never reach this runner.
- *   - install: spawn the `npm install -g <pkg>` argv, stream output, re-detect
- *     once the child exits.
- *
- * Token CLIs (aws, mocli) skip this entirely — credentials come in via a plain
- * POST and are applied synchronously by `applyCliToken`.
- */
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
@@ -24,9 +8,6 @@ const MAX_SESSION_AGE_MS = 15 * 60 * 1000;
 const POLL_INTERVAL_MS = 2_000;
 const POLL_TIMEOUT_MS = 10 * 60 * 1000;
 const BACKLOG_LINES = 200;
-// ---------------------------------------------------------------------------
-// Session lifecycle
-// ---------------------------------------------------------------------------
 function reapExpiredSessions() {
     const now = Date.now();
     for (const [id, s] of SESSIONS) {
@@ -49,7 +30,6 @@ function startStreamingSession(opts) {
     const { cli, argv, env, shell, pollUntilReady, computeOk } = opts;
     const sessionId = randomUUID();
     const events = new EventEmitter();
-    // Unlimited listeners — SSE clients may resubscribe multiple times.
     events.setMaxListeners(0);
     const session = {
         sessionId,
@@ -95,7 +75,7 @@ function startStreamingSession(opts) {
         try {
             finalStatus = await detectCli(cli);
         }
-        catch { /* best-effort */ }
+        catch { }
         if (finalStatus) {
             events.emit('event', { type: 'status', status: finalStatus });
         }
@@ -124,15 +104,12 @@ function startStreamingSession(opts) {
                     void settle(child.exitCode);
                 }
             }
-            catch { /* ignore polling errors */ }
+            catch { }
         }, POLL_INTERVAL_MS);
     }
     child.on('close', (code) => { void settle(code); });
     return { ok: true, sessionId };
 }
-// ---------------------------------------------------------------------------
-// oauth-web login
-// ---------------------------------------------------------------------------
 export async function startCliAuthSession(cliId) {
     const cli = getRecommendedCli(cliId);
     if (!cli)
@@ -140,8 +117,6 @@ export async function startCliAuthSession(cliId) {
     if (cli.auth.type !== 'oauth-web' || !cli.auth.loginArgv) {
         return { ok: false, error: `cli ${cliId} does not support oauth-web sign-in` };
     }
-    // CLIs configured for manual login should never spawn here — guard so a
-    // misbehaving client can't end-run the documented terminal flow.
     if (cli.auth.manualLoginCommands && cli.auth.manualLoginCommands.length > 0) {
         return { ok: false, error: `cli ${cliId} uses manual sign-in (run the commands in your own terminal)` };
     }
@@ -155,12 +130,6 @@ export async function startCliAuthSession(cliId) {
 }
 const NPM_GLOBAL_INSTALL_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(\S.*)$/;
 const SHELL_METACHAR_RE = /[|;&`$()<>]/;
-/**
- * Inspect a CLI's install spec for the current platform and return a single
- * argv that's safe to spawn without user-side approvals. Returns null when no
- * such command exists (brew/apt/dnf/winget/scoop/curl-pipe-sh entries are all
- * rejected on purpose — those require sudo or interactive confirmation).
- */
 export function resolveAutoInstallSpec(cli, platform) {
     const commands = cli.install[platform] || [];
     for (const c of commands) {
@@ -190,24 +159,14 @@ export async function startCliInstallSession(cliId) {
         cli,
         argv: spec.argv,
         env: { ...process.env, NO_COLOR: '1', TERM: 'dumb', CI: '1' },
-        // npm on Windows is npm.cmd — needs shell resolution. spawn() args are
-        // still passed argv-style; we don't concat into a shell string.
         shell: process.platform === 'win32',
         pollUntilReady: false,
         computeOk: (exit, status) => exit === 0 && (status ? status.state !== 'not_installed' : true),
     });
 }
-// ---------------------------------------------------------------------------
-// Token auth — apply-credentials flow
-// ---------------------------------------------------------------------------
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-/**
- * Apply a set of credentials for a `token`-auth CLI and verify. Each CLI gets a
- * tailored write path because there's no universal convention — we only do this
- * for CLIs we explicitly support.
- */
 export async function applyCliToken(cliId, values) {
     const cli = getRecommendedCli(cliId);
     if (!cli)
@@ -232,8 +191,6 @@ export async function applyCliToken(cliId, values) {
             }
         }
         else if (cli.id === 'mocli') {
-            // mocli stores its key via `mocli auth init --apik <KEY>` — let the CLI
-            // own its storage path so future schema changes upstream don't break us.
             const key = (values.MOWEN_API_KEY || '').trim();
             if (!key)
                 return { ok: false, error: 'Mowen API Key is required' };
@@ -262,16 +219,12 @@ export async function applyCliToken(cliId, values) {
         return { ok: false, error: e?.message || 'failed to apply token' };
     }
 }
-/**
- * Merge a `[section]` block into an INI-style file, replacing any existing
- * block with the same name. Idempotent; preserves other sections and comments.
- */
 function mergeIniSection(filePath, section, block) {
     let current = '';
     try {
         current = fs.readFileSync(filePath, 'utf-8');
     }
-    catch { /* new file */ }
+    catch { }
     const header = `[${section}]`;
     const lines = current.split(/\r?\n/);
     const out = [];
@@ -287,7 +240,6 @@ function mergeIniSection(filePath, section, block) {
                 inTarget = false;
                 out.push(line);
             }
-            // else: drop old line
         }
         else {
             out.push(line);

package/dist/agent/cli/catalog.js

@@ -1,6 +1,3 @@
-/**
- * CLI catalog — merges the recommended registry with live detection status.
- */
 import { getRecommendedClis } from './registry.js';
 import { detectCli, getCachedCliStatus, currentPlatform } from './detector.js';
 import { resolveAutoInstallSpec } from './auth.js';