@nocville/npc 0.0.0-stage → 0.2.1

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

package/dist/npcs/agent-common/git-stats.js

@@ -0,0 +1,67 @@
+import { spawnSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { performance } from 'node:perf_hooks';
+/** Parse NUL-delimited numstat, including binary files and rename path pairs. */
+export function parseNumstat(raw) {
+    const fields = raw.split('\0'), files = [];
+    for (let i = 0; i < fields.length; i++) {
+        const record = fields[i];
+        if (!record)
+            continue;
+        const match = /^(\d+|-)\t(\d+|-)\t([\s\S]*)$/.exec(record);
+        if (!match)
+            continue;
+        let path = match[3];
+        if (!path) {
+            i++;
+            path = fields[++i] ?? '';
+        }
+        if (path)
+            files.push({
+                path,
+                insertions: match[1] === '-' ? 0 : Number(match[1]),
+                deletions: match[2] === '-' ? 0 : Number(match[2]),
+            });
+    }
+    return files;
+}
+/** Both commands share one wall-clock budget; call only from detached flushes. */
+export function computeGitStats(cwd, timeoutMs = 1500) {
+    const deadline = performance.now() + Math.max(1, Math.min(1500, timeoutMs));
+    const git = (args) => {
+        const remaining = Math.floor(deadline - performance.now());
+        if (remaining <= 0)
+            return null;
+        const result = spawnSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-C', cwd, ...args], {
+            encoding: 'utf8',
+            timeout: remaining,
+            killSignal: 'SIGKILL',
+            maxBuffer: 1 << 20,
+            windowsHide: true,
+        });
+        return result.status === 0 && !result.error ? result.stdout : null;
+    };
+    const diff = git(['diff', '--no-ext-diff', '--no-textconv', '--numstat', '-z', 'HEAD', '--']);
+    if (diff === null)
+        return null;
+    const untracked = git(['ls-files', '--others', '--exclude-standard', '-z']);
+    if (untracked === null)
+        return null;
+    const files = parseNumstat(diff);
+    for (const path of untracked.split('\0'))
+        if (path)
+            files.push({ path, insertions: 0, deletions: 0 });
+    if (files.length > 100_000)
+        return null;
+    files.sort((a, b) => b.insertions + b.deletions - (a.insertions + a.deletions) || a.path.localeCompare(b.path));
+    return {
+        filesChanged: files.length,
+        insertions: files.reduce((n, file) => n + file.insertions, 0),
+        deletions: files.reduce((n, file) => n + file.deletions, 0),
+        lastFiles: files.slice(0, 5).map((file) => basename(file.path)
+            // eslint-disable-next-line no-control-regex -- Strip display controls from Git filenames.
+            .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '')
+            .slice(0, 120)),
+    };
+}
+//# sourceMappingURL=git-stats.js.map

package/dist/npcs/agent-common/hook-runner.d.ts

@@ -0,0 +1,62 @@
+import type { StatusUpdate } from '@nocville/node';
+import type { NpcConfig } from '../../core/types.js';
+import { computeGitStats } from './git-stats.js';
+import type { AgentAdapter, AgentSessionState, AgentTransition } from './session.js';
+/** A raw hook payload (Claude Code and Codex share the same envelope shape). */
+export interface AgentHookEvent {
+    session_id?: string;
+    hook_event_name?: string;
+    /** Legacy alias accepted by older callers/tests. */
+    event?: string;
+    cwd?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    [key: string]: unknown;
+}
+export declare function hookEventName(event: AgentHookEvent): string;
+/** Everything that differs between agents. */
+export interface AgentHookSpec {
+    adapter: AgentAdapter;
+    /** Required neutral response for hosts whose hook protocol always expects JSON. */
+    stdoutOnSuccess?: string;
+    statsEvents?: readonly string[];
+    /** Cross-source pairs (native and imported hooks), deduplicated under the state lock. */
+    deliveryIdentity?(event: AgentHookEvent): {
+        key: string;
+        source: string;
+    };
+    serviceIdFor(sessionId: string, cwd: string): string;
+    transition(event: AgentHookEvent, prev: AgentSessionState | null): AgentTransition;
+    /** Optional user-facing session name (e.g. Claude Code session title). */
+    resolveName?(event: AgentHookEvent, prev: AgentSessionState | null): string | undefined;
+}
+export interface HookRunOptions {
+    /**
+     * 'inline' awaits the push in-process (library use, tests). 'detach' (the CLI
+     * default) hands pushes to a background process so the hook exits at once.
+     */
+    mode?: 'inline' | 'detach';
+    minPushGapMs?: number;
+    now?: () => number;
+    /** Inline-mode push override (tests). */
+    push?: (serviceId: string, payload: StatusUpdate) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Override how deferred flushes are scheduled (tests). */
+    scheduleFlush?: (sessionId: string, delayMs: number) => void;
+    /** cli.js path for detached flushes (default: process.argv[1]). */
+    cliPath?: string;
+}
+/** Read all of stdin synchronously; '' on error. */
+export declare function readStdin(): string;
+/**
+ * Process one hook invocation. Never throws. Only a configured neutral JSON response
+ * reaches stdout; other hosts receive no output.
+ */
+export declare function runAgentHook(spec: AgentHookSpec, config: NpcConfig, rawInput: string | AgentHookEvent, opts?: HookRunOptions): Promise<void>;
+/** `<agent> flush <session> --delay=ms`: the detached half of a hook push. */
+export declare function runFlushCommand(adapter: AgentAdapter, config: NpcConfig, sessionId: string | undefined, delayMs: number | undefined, stats?: boolean): Promise<void>;
+/** Git runs outside the state lock, and a newer turn can invalidate its result. */
+export declare function collectSessionGitStats(adapter: AgentAdapter, sessionId: string, compute?: typeof computeGitStats): Promise<void>;
+//# sourceMappingURL=hook-runner.d.ts.map