@nocville/npc 0.0.0-stage → 0.2.0

package/dist/core/user-config.js

@@ -0,0 +1,85 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Location of the config file. `NOCVILLE_CONFIG` overrides (used by tests);
+ * otherwise `$XDG_CONFIG_HOME/nocville/config.json`, else `~/.config/nocville/config.json`.
+ */
+export function userConfigPath() {
+    const override = process.env['NOCVILLE_CONFIG'];
+    if (override)
+        return override;
+    const xdg = process.env['XDG_CONFIG_HOME'];
+    const base = xdg && xdg.trim() ? xdg : join(homedir(), '.config');
+    return join(base, 'nocville', 'config.json');
+}
+/** Read the user config; missing or unreadable files yield `{}` (never throws). */
+export function loadUserConfig(path = userConfigPath()) {
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        const out = {};
+        if (typeof raw['apiUrl'] === 'string' && raw['apiUrl'])
+            out.apiUrl = raw['apiUrl'];
+        if (typeof raw['apiKey'] === 'string' && raw['apiKey'])
+            out.apiKey = raw['apiKey'];
+        if (typeof raw['map'] === 'string' && raw['map'])
+            out.map = raw['map'];
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge `patch` into the stored config and write it with owner-only perms
+ * (dir 0700, file 0600) via an atomic rename. Undefined fields are left as-is;
+ * an empty string clears a field. Returns the written path.
+ */
+export function saveUserConfig(patch, path = userConfigPath()) {
+    const current = loadUserConfig(path);
+    const next = { ...current };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            continue;
+        if (v === '')
+            delete next[k];
+        else
+            next[k] = v;
+    }
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // best effort (e.g. Windows)
+    }
+    return path;
+}
+/** Mask an API key for display: keep a short prefix/suffix only. */
+export function maskKey(key) {
+    if (!key)
+        return '(none)';
+    if (key.length <= 10)
+        return '****';
+    return `${key.slice(0, 4)}…${key.slice(-4)}`;
+}
+/**
+ * Save credentials (explicit flags win; else migrate any from a legacy hook
+ * command) and return the effective config. Shared by claude-code/codex setup.
+ */
+export function persistCredentials(explicit, legacy = {}) {
+    const saved = loadUserConfig();
+    const patch = {
+        apiUrl: explicit.apiUrl ?? (saved.apiUrl ? undefined : legacy.apiUrl),
+        apiKey: explicit.apiKey ?? (saved.apiKey ? undefined : legacy.apiKey),
+        map: explicit.map,
+    };
+    const path = patch.apiUrl || patch.apiKey || patch.map ? saveUserConfig(patch) : userConfigPath();
+    return { ...loadUserConfig(), path };
+}
+//# sourceMappingURL=user-config.js.map

package/dist/doctor.d.ts

@@ -0,0 +1,8 @@
+import type { NpcConfig } from './core/types.js';
+/**
+ * Diagnose connectivity to the Nocville API: hit `/api/v1/health/ready`, then POST a single
+ * offline status push and report HTTP status, latency, and rate-limit headroom.
+ */
+export declare function runDoctor(config: NpcConfig): Promise<void>;
+export declare function hasCodexHookWatcherOverlap(dir?: string): boolean;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -0,0 +1,126 @@
+import { randomUUID } from 'node:crypto';
+import { readdirSync } from 'node:fs';
+import { isAgentAlive } from './npcs/agent-common/liveness.js';
+import { CODEX_DEFAULTS } from './npcs/codex/defaults.js';
+/**
+ * Diagnose connectivity to the Nocville API: hit `/api/v1/health/ready`, then POST a single
+ * offline status push and report HTTP status, latency, and rate-limit headroom.
+ */
+export async function runDoctor(config) {
+    const apiUrl = config.apiUrl.replace(/\/+$/, '');
+    console.log(`nocville-npc doctor — checking ${apiUrl}`);
+    console.log('');
+    if (hasCodexHookWatcherOverlap())
+        console.warn('  [WARN] Codex hooks and codex watch are both active. Stop the fallback watcher; hooks own these sessions.');
+    // 1) Health check
+    let healthOk = false;
+    {
+        const start = Date.now();
+        const t = withTimeout(5000);
+        try {
+            const res = await fetch(`${apiUrl}/api/v1/health/ready`, { method: 'GET', signal: t.signal });
+            const ms = Date.now() - start;
+            const body = await res.text();
+            healthOk = res.ok;
+            console.log(`  [${res.ok ? 'OK' : 'FAIL'}] GET /api/v1/health/ready -> ${res.status} (${ms}ms)`);
+            if (config.debug)
+                console.log(`         ${body.slice(0, 200)}`);
+        }
+        catch (err) {
+            console.log(`  [FAIL] GET /api/v1/health/ready -> ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            t.done();
+        }
+    }
+    // 2) Test status push
+    let pushOk = false;
+    const hasKey = Boolean(config.apiKey);
+    if (!hasKey) {
+        console.log('  [SKIP] POST /api/v1/status — no --api-key / NOCVILLE_API_KEY set');
+    }
+    else {
+        const start = Date.now();
+        const t = withTimeout(5000);
+        try {
+            const res = await fetch(`${apiUrl}/api/v1/status`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${config.apiKey}`,
+                },
+                signal: t.signal,
+                body: JSON.stringify({
+                    // Unique offline probe: personal-key ownership must not reserve a shared doctor ID.
+                    serviceId: `${(config.serviceId || 'npc').slice(0, 60)}-doctor-${randomUUID().slice(0, 16)}`,
+                    status: 'unknown',
+                    mood: 'idle',
+                    offline: true,
+                    subStatus: 'offline',
+                    ...(config.map ? { map: config.map } : {}),
+                }),
+            });
+            const ms = Date.now() - start;
+            const text = await res.text();
+            pushOk = res.ok;
+            let remaining = res.headers.get('x-ratelimit-remaining') ?? res.headers.get('ratelimit-remaining');
+            if (!remaining) {
+                try {
+                    const parsed = JSON.parse(text);
+                    if (typeof parsed.remaining === 'number')
+                        remaining = String(parsed.remaining);
+                }
+                catch {
+                    // non-JSON body
+                }
+            }
+            console.log(`  [${res.ok ? 'OK' : 'FAIL'}] POST /api/v1/status -> ${res.status} ` +
+                `(${ms}ms, rate-limit remaining: ${remaining ?? 'n/a'})`);
+            if (config.map)
+                console.log(`         target map: ${config.map}`);
+            if (!res.ok)
+                console.log(`         ${text.slice(0, 200)}`);
+        }
+        catch (err) {
+            console.log(`  [FAIL] POST /api/v1/status -> ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            t.done();
+        }
+    }
+    // Verdict
+    console.log('');
+    if (healthOk && pushOk) {
+        console.log('Verdict: OK — API reachable and status push accepted.');
+        console.log('The offline probe does not create a coworker in your office.');
+    }
+    else if (!healthOk) {
+        console.log('Verdict: FAIL — API health check is unreachable. Check --api-url and that the server is running.');
+    }
+    else if (!hasKey) {
+        console.log('Verdict: PARTIAL — API is up, but no API key was provided to test a push.');
+    }
+    else {
+        console.log('Verdict: FAIL — API is up but the push was rejected. Check your API key / team settings.');
+    }
+    process.exitCode = healthOk && (pushOk || !hasKey) ? 0 : 1;
+}
+function withTimeout(timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return { signal: controller.signal, done: () => clearTimeout(timer) };
+}
+export function hasCodexHookWatcherOverlap(dir = CODEX_DEFAULTS.stateDir) {
+    try {
+        const files = readdirSync(dir);
+        return (files.some((file) => /^session-.*\.json$/.test(file)) &&
+            files.some((file) => {
+                const match = file.match(/^watcher-(\d+)\.pid$/);
+                return !!match && isAgentAlive({ pid: Number(match[1]) });
+            }));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=doctor.js.map

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export { BaseNPC } from './core/base-npc.js';
+export { PollingNPC } from './core/polling-npc.js';
+export type { PollingNpcConfig } from './core/polling-npc.js';
+export { EventNPC } from './core/event-npc.js';
+export { Logger } from './core/logger.js';
+export { parseArgs, resolveConfig, stringFlag, boolFlag, numberFlag } from './core/config.js';
+export type { ParsedArgs } from './core/config.js';
+export { evaluateThreshold, worstStatus } from './core/thresholds.js';
+export { truncate } from './core/text.js';
+export { statusColor, pushHistory } from './core/screen.js';
+export type { ScreenColor } from './core/screen.js';
+export type { Status, Mood, NpcConfig, CollectedMetrics, ThresholdConfig, NpcState, LogLevelName, Archetype, BehaviorHints, CompanionSpec, CompanionDecl, ScreenData, ScreenValue, } from './core/types.js';
+export { SystemMonitorNPC } from './npcs/system-monitor/index.js';
+export type { SystemMonitorConfig } from './npcs/system-monitor/index.js';
+export { ClaudeCodeNPC, handleClaudeCodeCommand, handleHookEvent, setupHooks, uninstallHooks, processHookEvent, claudeTransition, } from './npcs/claude-code/index.js';
+export type { ClaudeCodeSubcommandOptions, SetupOptions, SessionState, HookEvent, StatusOutput, SessionMachineState, } from './npcs/claude-code/index.js';
+export { handleCodexCommand, handleCodexHookEvent, codexTransition, setupCodexHooks, uninstallCodexHooks, parseRolloutLine, CodexWatcher, } from './npcs/codex/index.js';
+export type { CodexSetupOptions, CodexWatcherOptions, RolloutSignal } from './npcs/codex/index.js';
+export { describeToolUse, shortCommand, shortPath, redactSecrets, } from './npcs/agent-common/activity.js';
+export { loadUserConfig, saveUserConfig, userConfigPath } from './core/user-config.js';
+export type { UserConfig } from './core/user-config.js';
+export { InternetConnectivityNPC } from './npcs/internet-connectivity/index.js';
+export type { InternetConnectivityConfig } from './npcs/internet-connectivity/index.js';
+export { ProcessWatcherNPC } from './npcs/process-watcher/index.js';
+export type { ProcessWatcherConfig } from './npcs/process-watcher/index.js';
+export { LogWatcherNPC } from './npcs/log-watcher/index.js';
+export type { LogWatcherConfig } from './npcs/log-watcher/index.js';
+export { ReceptionistNPC } from './npcs/receptionist/index.js';
+export type { ReceptionistConfig } from './npcs/receptionist/index.js';
+export { GitHubWatcherNPC } from './npcs/github-watcher/index.js';
+export type { GitHubWatcherConfig } from './npcs/github-watcher/index.js';
+export { WebPageWatcherNPC } from './npcs/web-page-watcher/index.js';
+export type { WebPageWatcherConfig } from './npcs/web-page-watcher/index.js';
+export { GEMINI_DEFAULTS, GEMINI_ADAPTER, geminiTransition, geminiServiceId, handleGeminiHookEvent, setupGeminiHooks, uninstallGeminiHooks, installGeminiHooksInto, GEMINI_HOOK_EVENTS, } from './npcs/gemini/index.js';
+export type { GeminiSetupOptions } from './npcs/gemini/index.js';
+export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
+export type { CursorSetupOptions } from './npcs/cursor/index.js';
+export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+// Core
+export { BaseNPC } from './core/base-npc.js';
+export { PollingNPC } from './core/polling-npc.js';
+export { EventNPC } from './core/event-npc.js';
+export { Logger } from './core/logger.js';
+export { parseArgs, resolveConfig, stringFlag, boolFlag, numberFlag } from './core/config.js';
+export { evaluateThreshold, worstStatus } from './core/thresholds.js';
+export { truncate } from './core/text.js';
+export { statusColor, pushHistory } from './core/screen.js';
+// NPCs
+export { SystemMonitorNPC } from './npcs/system-monitor/index.js';
+export { ClaudeCodeNPC, handleClaudeCodeCommand, handleHookEvent, setupHooks, uninstallHooks, processHookEvent, claudeTransition, } from './npcs/claude-code/index.js';
+export { handleCodexCommand, handleCodexHookEvent, codexTransition, setupCodexHooks, uninstallCodexHooks, parseRolloutLine, CodexWatcher, } from './npcs/codex/index.js';
+export { describeToolUse, shortCommand, shortPath, redactSecrets, } from './npcs/agent-common/activity.js';
+export { loadUserConfig, saveUserConfig, userConfigPath } from './core/user-config.js';
+export { InternetConnectivityNPC } from './npcs/internet-connectivity/index.js';
+export { ProcessWatcherNPC } from './npcs/process-watcher/index.js';
+export { LogWatcherNPC } from './npcs/log-watcher/index.js';
+export { ReceptionistNPC } from './npcs/receptionist/index.js';
+export { GitHubWatcherNPC } from './npcs/github-watcher/index.js';
+export { WebPageWatcherNPC } from './npcs/web-page-watcher/index.js';
+export { GEMINI_DEFAULTS, GEMINI_ADAPTER, geminiTransition, geminiServiceId, handleGeminiHookEvent, setupGeminiHooks, uninstallGeminiHooks, installGeminiHooksInto, GEMINI_HOOK_EVENTS, } from './npcs/gemini/index.js';
+export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
+export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
+//# sourceMappingURL=index.js.map

package/dist/npcs/agent-common/activity.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Human-friendly activity strings for AI coding agents (Claude Code, Codex).
+ *
+ * These end up on the NPC's speech bubble and desk-sign ticker, which teammates
+ * see — so they must be short, readable, and never leak secrets or prompt text.
+ */
+/** Max length of a full activity line ("Running pnpm test", "Editing src/x.ts"). */
+export declare const ACTIVITY_MAX = 60;
+export declare const THINKING = "Thinking\u2026";
+/**
+ * Make a path short and relative: strip the project cwd (or the home dir to
+ * `~`), then keep only the trailing segments if it is still long.
+ */
+export declare function shortPath(p: string, cwd?: string): string;
+/**
+ * Redact anything secret-looking from a shell command: env assignments,
+ * `--token=…`-style flags, bearer headers, URL credentials, and long opaque
+ * strings (API keys, hashes). Conservative by design — false positives are fine.
+ */
+export declare function redactSecrets(cmd: string): string;
+/**
+ * Shorten a shell command for display: first line only, drop a leading
+ * `cd … &&`, drop leading `VAR=value` env assignments (often secrets), unwrap
+ * `bash -lc "…"` wrappers, redact secrets, and truncate.
+ */
+export declare function shortCommand(raw: unknown, max?: number): string;
+/** Files touched by an `apply_patch` envelope ("*** Update File: path"). */
+export declare function patchFiles(patch: string): string[];
+/** "Editing a.ts" / "Editing a.ts +2 more" for a list of files. */
+export declare function editingFiles(files: string[], cwd?: string): string;
+/**
+ * Describe a tool invocation in a few words. Covers Claude Code tool names and
+ * Codex tool names (Bash/shell/exec_command, apply_patch, update_plan, …);
+ * unknown tools fall back to "Using <tool>". Never includes file contents,
+ * edit strings, or prompts.
+ */
+export declare function describeToolUse(toolName: string | undefined, rawInput: unknown, cwd?: string): string;
+/** Tools whose PreToolUse means the agent is now waiting on the human. */
+export declare function isQuestionTool(toolName: string | undefined): boolean;
+/** Short failure label: "A command failed", "Edit failed". */
+export declare function failureText(toolName: string | undefined): string;
+//# sourceMappingURL=activity.d.ts.map

package/dist/npcs/agent-common/activity.js

@@ -0,0 +1,280 @@
+import { homedir } from 'node:os';
+import { truncate } from '../../core/text.js';
+/**
+ * Human-friendly activity strings for AI coding agents (Claude Code, Codex).
+ *
+ * These end up on the NPC's speech bubble and desk-sign ticker, which teammates
+ * see — so they must be short, readable, and never leak secrets or prompt text.
+ */
+/** Max length of a full activity line ("Running pnpm test", "Editing src/x.ts"). */
+export const ACTIVITY_MAX = 60;
+/** Max length of an embedded shell command. */
+const COMMAND_MAX = 44;
+/** Max length of an embedded path. */
+const PATH_MAX = 40;
+/** Max length of an embedded search pattern / query. */
+const PATTERN_MAX = 28;
+export const THINKING = 'Thinking…';
+function str(input, ...keys) {
+    for (const k of keys) {
+        const v = input[k];
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+function asInput(raw) {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        // Some agents pass JSON-encoded arguments.
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // Not JSON — treat as a bare command string.
+        }
+        return { command: raw };
+    }
+    if (Array.isArray(raw))
+        return { command: raw };
+    return {};
+}
+/**
+ * Make a path short and relative: strip the project cwd (or the home dir to
+ * `~`), then keep only the trailing segments if it is still long.
+ */
+export function shortPath(p, cwd) {
+    let out = p.trim().replace(/^file:\/\//, '');
+    const norm = (s) => s.replace(/\\/g, '/').replace(/\/+$/, '');
+    out = norm(out);
+    const base = cwd ? norm(cwd) : '';
+    if (base && (out === base || out.startsWith(base + '/'))) {
+        out = out.slice(base.length + 1) || '.';
+    }
+    else {
+        const home = norm(homedir());
+        if (home && out.startsWith(home + '/'))
+            out = '~' + out.slice(home.length);
+    }
+    if (out.length <= PATH_MAX)
+        return out;
+    const parts = out.split('/');
+    // Keep the last two segments; fall back to truncating the filename.
+    const tail = parts.slice(-2).join('/');
+    if (tail.length + 2 <= PATH_MAX)
+        return '…/' + tail;
+    return truncate(parts[parts.length - 1] ?? out, PATH_MAX);
+}
+const SECRET_FLAG = /(--?[\w-]*(?:token|key|secret|password|passwd|pwd|auth|credential)[\w-]*)(=|\s+)("[^"]*"|'[^']*'|\S+)/gi;
+/**
+ * Redact anything secret-looking from a shell command: env assignments,
+ * `--token=…`-style flags, bearer headers, URL credentials, and long opaque
+ * strings (API keys, hashes). Conservative by design — false positives are fine.
+ */
+export function redactSecrets(cmd) {
+    return (cmd
+        // URL credentials: scheme://user:pass@host
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, '$1***@')
+        // Authorization headers
+        .replace(/(bearer|basic|token)\s+[A-Za-z0-9._~+/=-]{8,}/gi, '$1 ***')
+        // --api-key=…, --password …, -token …
+        .replace(SECRET_FLAG, (_m, flag, sep) => `${flag}${sep}***`)
+        // Well-known key prefixes
+        .replace(/\b(sk|pk|rk)-[A-Za-z0-9_-]{8,}/g, '***')
+        .replace(/\b(ghp|gho|ghs|ghu|github_pat|xox[abprs]|glpat|AKIA)[A-Za-z0-9_-]{8,}/g, '***')
+        // Long opaque tokens (≥32 chars of key-ish alphabet, no path separators)
+        .replace(/\b[A-Za-z0-9_+=-]{32,}\b/g, '***'));
+}
+/**
+ * Shorten a shell command for display: first line only, drop a leading
+ * `cd … &&`, drop leading `VAR=value` env assignments (often secrets), unwrap
+ * `bash -lc "…"` wrappers, redact secrets, and truncate.
+ */
+export function shortCommand(raw, max = COMMAND_MAX) {
+    let cmd;
+    if (Array.isArray(raw)) {
+        const parts = raw.filter((x) => typeof x === 'string');
+        // Unwrap ["bash", "-lc", "<script>"] style argv.
+        const shellIdx = parts.findIndex((p) => p === '-lc' || p === '-c');
+        cmd = shellIdx >= 0 && parts[shellIdx + 1] ? parts[shellIdx + 1] : parts.join(' ');
+    }
+    else if (typeof raw === 'string') {
+        cmd = raw;
+    }
+    else {
+        return '';
+    }
+    cmd = cmd.trim();
+    // Unwrap a string-form shell wrapper: bash -lc 'pnpm test'
+    const wrapped = cmd.match(/^(?:\/\S*\/)?(?:ba|z)?sh\s+-l?c\s+(['"])([\s\S]*)\1$/);
+    if (wrapped)
+        cmd = wrapped[2].trim();
+    cmd = cmd.split('\n')[0].trim();
+    // Drop leading "cd <dir> &&" / "cd <dir>;" hops.
+    cmd = cmd.replace(/^(?:cd\s+("[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*)+/, '');
+    // Drop leading env assignments.
+    cmd = cmd.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=("[^"]*"|'[^']*'|\S*)\s+)+/, '');
+    cmd = redactSecrets(cmd).replace(/\s+/g, ' ').trim();
+    return truncate(cmd, max);
+}
+function quote(s, max = PATTERN_MAX) {
+    return `'${truncate(s.replace(/\s+/g, ' '), max)}'`;
+}
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return truncate(url, PATTERN_MAX);
+    }
+}
+/** Files touched by an `apply_patch` envelope ("*** Update File: path"). */
+export function patchFiles(patch) {
+    const files = [];
+    const re = /^\*\*\* (?:Update|Add|Delete) File:\s*(.+)$/gm;
+    let m;
+    while ((m = re.exec(patch)) !== null) {
+        const f = m[1].trim();
+        if (f && !files.includes(f))
+            files.push(f);
+    }
+    return files;
+}
+/** "Editing a.ts" / "Editing a.ts +2 more" for a list of files. */
+export function editingFiles(files, cwd) {
+    if (files.length === 0)
+        return 'Editing files';
+    const first = shortPath(files[0], cwd);
+    return files.length === 1 ? `Editing ${first}` : `Editing ${first} +${files.length - 1} more`;
+}
+/**
+ * Describe a tool invocation in a few words. Covers Claude Code tool names and
+ * Codex tool names (Bash/shell/exec_command, apply_patch, update_plan, …);
+ * unknown tools fall back to "Using <tool>". Never includes file contents,
+ * edit strings, or prompts.
+ */
+export function describeToolUse(toolName, rawInput, cwd) {
+    const name = (toolName ?? '').trim();
+    const input = asInput(rawInput);
+    const key = name.toLowerCase();
+    // MCP tools: mcp__server__tool → "Using server (tool)"
+    if (key.startsWith('mcp__')) {
+        const [, server = 'mcp', tool = ''] = name.split('__');
+        return truncate(tool ? `Using ${server} (${tool})` : `Using ${server}`, ACTIVITY_MAX);
+    }
+    switch (key) {
+        case 'replace':
+        case 'write_file':
+        case 'edit':
+        case 'multiedit':
+        case 'write':
+        case 'notebookedit': {
+            const file = str(input, 'file_path', 'absolute_path', 'notebook_path', 'path');
+            if (file)
+                return truncate(`Editing ${shortPath(file, cwd)}`, ACTIVITY_MAX);
+            // Codex aliases Edit/Write to apply_patch; fall through to patch parsing.
+            const patch = str(input, 'command', 'input', 'patch');
+            return truncate(editingFiles(patch ? patchFiles(patch) : [], cwd), ACTIVITY_MAX);
+        }
+        case 'delete': {
+            const file = str(input, 'file_path', 'path');
+            return file ? truncate(`Deleting ${shortPath(file, cwd)}`, ACTIVITY_MAX) : 'Deleting a file';
+        }
+        case 'apply_patch':
+        case 'applypatch': {
+            const patch = str(input, 'command', 'input', 'patch') ?? '';
+            return truncate(editingFiles(patchFiles(patch), cwd), ACTIVITY_MAX);
+        }
+        case 'run_shell_command':
+        case 'bash':
+        case 'shell':
+        case 'local_shell':
+        case 'exec_command':
+        case 'container.exec':
+        case 'unified_exec': {
+            const cmd = shortCommand(input['command'] ?? input['cmd']);
+            return cmd ? `Running ${cmd}` : 'Running a command';
+        }
+        case 'bashoutput':
+        case 'write_stdin':
+            return 'Checking a running command';
+        case 'killshell':
+        case 'killbash':
+            return 'Stopping a command';
+        case 'read_file':
+        case 'read':
+        case 'notebookread':
+        case 'view': {
+            const file = str(input, 'file_path', 'absolute_path', 'notebook_path', 'path');
+            return file ? truncate(`Reading ${shortPath(file, cwd)}`, ACTIVITY_MAX) : 'Reading files';
+        }
+        case 'view_image': {
+            const file = str(input, 'path', 'file_path');
+            return file ? truncate(`Viewing ${shortPath(file, cwd)}`, ACTIVITY_MAX) : 'Viewing an image';
+        }
+        case 'ls': {
+            const dir = str(input, 'path');
+            return dir ? truncate(`Listing ${shortPath(dir, cwd)}`, ACTIVITY_MAX) : 'Listing files';
+        }
+        case 'grep': {
+            const pattern = str(input, 'pattern', 'query');
+            return pattern ? `Searching for ${quote(pattern)}` : 'Searching the code';
+        }
+        case 'glob': {
+            const pattern = str(input, 'pattern');
+            return pattern ? `Finding files ${quote(pattern)}` : 'Finding files';
+        }
+        case 'toolsearch':
+            return 'Looking up tools';
+        case 'webfetch': {
+            const url = str(input, 'url');
+            return url ? `Browsing ${hostOf(url)}` : 'Browsing the web';
+        }
+        case 'websearch':
+        case 'web_search':
+        case 'web_search_preview': {
+            const q = str(input, 'query', 'q');
+            return q ? `Searching the web for ${quote(q)}` : 'Searching the web';
+        }
+        case 'task':
+        case 'agent':
+        case 'spawn_agent':
+            return 'Delegating to a subagent';
+        case 'todowrite':
+        case 'update_plan':
+        case 'taskcreate':
+        case 'taskupdate':
+            return 'Planning';
+        case 'exitplanmode':
+            return 'Plan ready for review';
+        case 'askuserquestion':
+        case 'request_user_input':
+            return 'Has a question for you';
+        case 'skill': {
+            const skill = str(input, 'skill', 'name');
+            return skill ? truncate(`Using skill ${skill}`, ACTIVITY_MAX) : 'Using a skill';
+        }
+        case '':
+            return 'Working';
+        default:
+            return truncate(`Using ${name}`, ACTIVITY_MAX);
+    }
+}
+/** Tools whose PreToolUse means the agent is now waiting on the human. */
+export function isQuestionTool(toolName) {
+    const k = (toolName ?? '').toLowerCase();
+    return k === 'askuserquestion' || k === 'exitplanmode' || k === 'request_user_input';
+}
+/** Short failure label: "A command failed", "Edit failed". */
+export function failureText(toolName) {
+    const k = (toolName ?? '').toLowerCase();
+    if (k === 'bash' || k === 'shell' || k === 'exec_command')
+        return 'A command failed';
+    if (!toolName)
+        return 'Hit an error';
+    return truncate(`${toolName} failed`, ACTIVITY_MAX);
+}
+//# sourceMappingURL=activity.js.map

package/dist/npcs/agent-common/git-stats.d.ts

@@ -0,0 +1,11 @@
+import type { AgentStats } from '@nocville/node';
+export type { AgentStats } from '@nocville/node';
+/** Parse NUL-delimited numstat, including binary files and rename path pairs. */
+export declare function parseNumstat(raw: string): Array<{
+    path: string;
+    insertions: number;
+    deletions: number;
+}>;
+/** Both commands share one wall-clock budget; call only from detached flushes. */
+export declare function computeGitStats(cwd: string, timeoutMs?: number): AgentStats | null;
+//# sourceMappingURL=git-stats.d.ts.map