@nocville/npc 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# @nocville/npc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Put your AI coding sessions and your infrastructure in the [Nocville](https://nocville.com)
+office as live NPCs. Each Claude Code, Codex, Gemini CLI or Cursor session becomes a coworker named after its
+project (`Claude · nocville`, `Codex · gridbreak`) who walks to a desk while working, raises
+a hand when it needs you, dozes when idle, and shows what it's doing on its speech bubble and
+desk sign: `Editing src/GameScene.ts`, `Running pnpm test`, `Searching for 'reconnect'`,
+`Needs your approval`, `Thinking…`. It leaves the office when the session ends.
+
+Requires Node.js 20+. Your team API key is in your Nocville team settings.
+
+## Quick start: AI coworkers
+
+```bash
+npx @nocville/npc setup
+```
+
+Paste your key at the prompt (input is hidden, so the key never lands in your shell history).
+For scripts, pass `--api-key=<your team key>` or set `NOCVILLE_API_KEY` instead. That's it. The command saves your key to `~/.config/nocville/config.json` (mode 0600), then
+hooks up whichever agents you have installed:
+
+- **Claude Code**: adds hooks to `~/.claude/settings.json`. New sessions show up right away;
+  restart sessions that are already running.
+- **Codex**: adds hooks to `~/.codex/hooks.json`. Codex won't run a new hook until you've
+  approved it, so start Codex once and run **`/hooks`** to trust the Nocville hooks.
+
+- **Gemini CLI**: adds eight telemetry hooks to `~/.gemini/settings.json`, preserving your
+  settings and existing hooks. Start a new session after setup. Hooks return only `{}`.
+
+- **Cursor**: adds native hooks to `~/.cursor/hooks.json`. Existing Nocville Claude hooks
+  also detect Cursor when its third-party hook imports are enabled. Both installations share
+  one coworker and deduplicate matching events. No permission decisions or model output are sent.
+
+Self-hosting or developing locally? Add `--api-url=http://localhost:3601`. To send sessions to
+a map other than your team's default, add `--map="Trading Floor"`.
+
+Prefer a global install? Run `npm i -g @nocville/npc`, then `nocville-npc setup --api-key=…`.
+When setup runs through `npx`, it copies itself to `~/.config/nocville/runtime/` so the hooks
+keep working after npm clears its cache.
+
+### Choose which sessions appear
+
+By default every agent session publishes to your office. To keep some out, or to show only
+some, edit `~/.config/nocville/sessions.json` (setup creates an empty one):
+
+```json
+{
+  "allow": { "projects": [], "sessions": [] },
+  "deny": { "projects": ["client-*", "~/work/secret"], "sessions": ["*private*"] }
+}
+```
+
+- **Empty lists** (or no file): every session publishes.
+- **`deny` always wins.** If any `allow` entry is set, **only** matching sessions publish.
+- **`projects`**: a folder name anywhere in the session's working directory (`client-*` also
+  covers `~/work/client-acme/api`), or a path containing `/` (`~/work/secret` covers that folder
+  and everything inside it).
+- **`sessions`**: a Claude Code session name (set with `/rename`). Unnamed sessions never match.
+- Patterns are case-insensitive; `*` matches anything, `?` one character.
+
+The file is read on every update, so edits apply to running sessions without reinstalling: a
+session that becomes filtered out leaves the office on its next update. If the file can't be
+parsed, nothing publishes until it's fixed. `npx @nocville/npc sessions` shows the rules and
+checks the current folder (`--project=<dir>`, `--name=<session name>` to test others).
+
+### Per-agent commands
+
+| Claude Code                          | Codex                                          |
+| ------------------------------------ | ---------------------------------------------- |
+| `nocville-npc claude-code setup`     | `nocville-npc codex setup` (then `/hooks`)     |
+| `nocville-npc claude-code uninstall` | `nocville-npc codex uninstall`                 |
+|                                      | `nocville-npc codex watch` (no-hooks fallback) |
+
+`nocville-npc gemini setup` and `nocville-npc gemini uninstall` manage Gemini alone.
+Gemini uses a 5000 ms hook timeout; pushes and end-of-turn git summaries are detached.
+Its Node process is identified by the Gemini executable path, not an unrelated Node parent.
+
+`nocville-npc cursor setup` and `nocville-npc cursor uninstall` manage native Cursor hooks.
+Native commands use 10-second timeouts. Setup installs only sessionStart/sessionEnd,
+beforeSubmitPrompt, postToolUse/postToolUseFailure, afterFileEdit, stop, subagentStop and
+preCompact; it removes older Nocville permission hooks while preserving other hooks.
+Activity comes from completed tools. Native and imported Cursor invocations return exactly
+`{}` with no decision fields. Payload fields identify imported Cursor; `CURSOR_VERSION`
+alone never reclassifies Claude launched inside its terminal. The launcher suppresses child
+stdout for every agent, including debug logs, and emits only the appropriate neutral response.
+Cursor does not watch the editor process or start a watchdog: an abandoned conversation uses
+the one-hour fallback heartbeat interval (unknown after two hours, despawn ten minutes later).
+Uninstall intentionally leaves `{"version":1}` when no other settings remain.
+
+Cursor's [documented tool names](https://cursor.com/docs/hooks#configuration) include Grep,
+Delete, Task and MCP tools. Their summaries use the shared redaction/path handling; MCP names
+are normalized to the shared MCP format. Real Cursor Shell/Read/Write verification with both
+Claude-imported-only and native hooks is still required before a public support claim.
+
+`nocville-npc uninstall` removes every Nocville hook. `nocville-npc init` only saves
+credentials. Every setup command takes the key from `--api-key`, then `NOCVILLE_API_KEY`, then
+the saved config, and otherwise prompts for it (in a terminal) or exits with an error. `nocville-npc doctor` checks connectivity and sends a test push.
+
+### What you'll see
+
+| Agent state                      | NPC                                   | Desk sign / bubble                             |
+| -------------------------------- | ------------------------------------- | ---------------------------------------------- |
+| Prompt submitted                 | walks to a desk, sits                 | `Thinking…`                                    |
+| Using a tool                     | stays at the desk                     | `Editing apps/web/x.ts`, `Running pnpm test` … |
+| Permission prompt / question     | stands up and raises a hand           | `Needs your approval: Running rm -rf dist`     |
+| Turn finished, or at the prompt  | dozes at the desk                     | `Done — waiting for next task`                 |
+| Session ends (exit, `/clear`, …) | leaves the office (immediate despawn) |                                                |
+
+**Privacy:** prompts, file contents, edit text, and command output are never sent. Commands
+are shortened to their first line, and anything that looks like a secret is redacted first:
+env assignments, `--token=`/`--password` flags, bearer headers, URL credentials, and long
+key-like strings. Paths are shown relative to the project.
+
+**Lifecycle and overhead:** normal hooks run asynchronously, update a locked local state file,
+and hand HTTP delivery to a detached process. Same-phase bursts coalesce at 1.5 seconds.
+SessionEnd stays synchronous with a short timeout to deliver the offline update; failures
+remain pending for retry. Hooks never output instructions or permission decisions.
+
+A watchdog checks a known agent process every 15 seconds and heartbeats once a minute.
+A killed process leaves the office on the next check. If the machine sleeps or loses power,
+the NPC becomes unknown after three minutes and disappears after thirteen. Hosts where
+process liveness cannot be established retain the legacy one-hour heartbeat fallback.
+Claude subagent activity appears below the parent's current activity and disappears when
+the subagent stops (or after ten minutes without activity).
+
+Setup installs a stable `~/.config/nocville/bin/nocville-hook` launcher (respecting
+`XDG_CONFIG_HOME` and `NOCVILLE_CONFIG`) and an immutable runtime copy when needed.
+Re-running setup updates the runtime pointer without changing the hook command or Codex's
+command trust. Old snapshots remain available to running watchdogs. Windows uses the sibling
+`nocville-hook.cmd` launcher, which resolves the saved Node path and runs the same bootstrap.
+Windows setup writes plain commands, never `-EncodedCommand` or an execution-policy override.
+Re-running setup replaces the former encoded commands; uninstall still recognizes them.
+
+| Agent       | Windows command host and verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | Explicit per-hook `shell: "powershell"`; invokes `& '<shim>.cmd' claude-code hook`. Claude selects PowerShell 7 or falls back to 5.1. CI exercises both. [Claude hook shell reference](https://code.claude.com/docs/en/hooks#windows-powershell-tool).                                                                                                                                                                                                                                                   |
+| Gemini      | Its hook runner selects PowerShell 7 or 5.1. The saved `cmd.exe /d /s /c --% ...` preserves cmd quoting, with a terminating newline before Gemini's appended exit check. CI exercises both hosts with that check. [Hook reference](https://geminicli.com/docs/hooks/reference/), [runner](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/hooks/hookRunner.ts), [shell selection](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/shell-utils.ts). |
+| Cursor      | Explicit `cmd.exe /d /s /c` launcher; CI executes the saved string under cmd. The [published hook contract](https://cursor.com/docs/hooks) does not specify the Windows outer shell; real Windows Cursor verification remains required.                                                                                                                                                                                                                                                                  |
+| Codex       | Explicit `cmd.exe /d /s /c` launcher; CI executes the saved string under cmd. The [published hook contract](https://learn.chatgpt.com/docs/hooks) does not identify the Windows outer shell; real Windows Codex verification remains required.                                                                                                                                                                                                                                                           |
+
+PowerShell's [stop-parsing token](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing#the-stop-parsing-token)
+ends at a newline, not a semicolon. Keep Gemini's saved newline: its runner appends PowerShell
+code to the command. No event input is interpolated into shell commands. Windows support remains
+unverified until the Windows CI job and real-agent checks pass; macOS tests cannot establish it.
+**Windows Cursor users:** install native hooks with `nocville-npc cursor setup`; do not rely on
+Cursor importing Claude Code hooks. Claude's saved hook uses PowerShell syntax and an explicit
+`shell` field. If Cursor's import path ignores that field and uses cmd, the imported command can
+fail before the shim runs and produce hook errors. Nocville cannot control Cursor's import path.
+
+Windows real-agent owner checklist (required before support claims):
+
+- Run the native Windows CI job, including PowerShell 5.1/7 and a spaced `O’Neil` profile path.
+- Verify native Cursor Shell/Read/Write events after `nocville-npc cursor setup`.
+- With Claude hooks also installed, check whether Cursor imports them and honors their `shell`
+  field. Record agent versions and any duplicate/error events; verify native Cursor hooks work
+  independently. Do not count an imported Claude hook as proof of native Cursor support.
+- Verify the actual Claude, Gemini and Codex hosts using their installed saved commands.
+
+Claude's single-quoted path doubles straight and curly apostrophes according to
+[PowerShell quoting rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules#including-quote-characters-in-a-string).
+
+Both launchers discard child stdout and preserve stderr; all SDK logger levels use stderr.
+If Node is unavailable, the shim drains stdin and returns neutral `{}` for Cursor/Gemini
+and Claude hooks (which may have been imported by Cursor); Codex stays silent. Session records are local, including terminal
+records that prevent late events from reviving an ended NPC; `cleanup` removes old records.
+
+### How the Codex integration works
+
+Codex supports Claude-style lifecycle hooks (`SessionStart`, `UserPromptSubmit`,
+`PreToolUse`, `PermissionRequest`, `Stop`, `SessionEnd`, …) configured in
+`~/.codex/hooks.json`. Setup merges a Nocville entry into each event, keeps your existing
+hooks, makes a one-time `hooks.json.nocville-backup`, and is safe to run again.
+
+`nocville-npc codex watch` is a deprecated, best-effort fallback for builds without hooks. It
+reads the rollout logs Codex writes to `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. It
+shows one NPC per interactive session (subagent and reviewer threads are skipped; add
+`--include-exec` to include `codex exec` runs). A session leaves the office after 30 minutes
+without log activity (`--idle-timeout=<minutes>`) or when you press Ctrl-C. If hooks are
+installed for a session (any hook state file, including an old terminal record), the watcher
+leaves that session to them. `doctor` warns when both modes are running.
+
+## Monitoring NPCs
+
+Long-running processes that each collect from one source and push status. Their NPC spawns
+on your map automatically and despawns when you press Ctrl-C. Once you've run
+`nocville-npc init`, no `--api-key` is needed.
+
+```bash
+# Common options:
+#   --api-key=<key>          Team API key (or NOCVILLE_API_KEY, or saved via `init`)
+#   --api-url=<url>          Default https://nocville.com (or NOCVILLE_API_URL)
+#   --service-id=<id>        Service ID (or NOCVILLE_SERVICE_ID)
+#   --name=<banner name>     Friendly NPC name (or NOCVILLE_NAME)
+#   --map=<id-or-name>       Target map (or NOCVILLE_MAP). Default: the team's default map
+#   --debug                  Verbose logging
+```
+
+| NPC                     | What it does                                       | Example                                                |
+| ----------------------- | -------------------------------------------------- | ------------------------------------------------------ |
+| `system-monitor`        | CPU / memory / disk / load with sparklines         | `nocville-npc system-monitor --cpu-warn=75`            |
+| `internet-connectivity` | DNS, HTTP and TCP latency checks                   | `nocville-npc internet-connectivity`                   |
+| `process-watcher`       | Watches named processes, calls out deaths          | `nocville-npc process-watcher --processes=nginx,redis` |
+| `log-watcher`           | Error bursts in log files, last lines on a monitor | `nocville-npc log-watcher --files=/var/log/app.log`    |
+| `receptionist`          | Time and weather at the entrance, greets players   | `nocville-npc receptionist --location="Berlin"`        |
+| `github-watcher`        | New commits on a commit board                      | `nocville-npc github-watcher --repo=owner/name`        |
+| `web-page-watcher`      | A web page rendered as a pixel-art TV              | `nocville-npc web-page-watcher --url=https://…`        |
+
+Run `nocville-npc --help` to see every flag. A few notes:
+
+- **log-watcher**: `--error-pattern="ERROR|FATAL" --window=300 --error-warn=5 --error-crit=20`.
+- **receptionist**: weather comes from the keyless open-meteo API. Set the place with
+  `--lat=52.5 --lon=13.4` or `--location=…` (otherwise it uses IP geolocation). Add
+  `--fahrenheit` for °F.
+- **github-watcher**: uses ETag polling. Pass `--token=$GITHUB_TOKEN` for a higher rate limit.
+- **web-page-watcher**: the pixel-art TV needs `npm i puppeteer-core` and a local
+  Chrome/Chromium (`--chrome-path` or `CHROME_PATH`). Without them it falls back to a
+  title/status ticker. Other options: `--mode=auto|screenshot|basic` and `--screen=160x120`.
+
+## Programmatic use
+
+```typescript
+import { SystemMonitorNPC, PollingNPC } from '@nocville/npc';
+import type { CollectedMetrics } from '@nocville/npc';
+
+await new SystemMonitorNPC({
+  apiUrl: 'https://nocville.com',
+  apiKey: 'noc_…',
+  serviceId: 'web-1',
+}).start();
+
+class MyNPC extends PollingNPC {
+  get name() {
+    return 'my-npc';
+  }
+  async collect(): Promise<CollectedMetrics> {
+    return { status: 'healthy', mood: 'happy', message: 'All good', metrics: { qps: 42 } };
+  }
+}
+```
+
+## Developing in the monorepo
+
+```bash
+pnpm install
+pnpm --filter @nocville/npc build
+pnpm --filter @nocville/npc test
+node libs/nocville-npc-library/dist/cli.js --help
+SMOKE_STUB=1 pnpm --filter @nocville/npc smoke   # every payload shape, no server needed
+```
+
+**Watch an AI-coworker NPC without running an agent.** `simulate` plays a scripted session
+(start → prompt → Read → Edit → `pnpm test` → approval wait → idle → end) through the real
+built hook handlers. It works in a throwaway HOME, so your `~/.claude` and `~/.codex` are
+untouched, and the NPC appears as "Claude · demo" (or "Codex · demo"):
+
+```bash
+pnpm --filter @nocville/npc simulate claude --api-key=<key> --api-url=http://localhost:3601
+pnpm --filter @nocville/npc simulate codex --api-key=<key> --project=gridbreak --fast
+#   --hold   stay idle after Stop until Ctrl-C, then end the session
+#   --fast   5x shorter pauses (CI)
+```
+
+**Real hooks against your local checkout.** This writes real hooks into `~/.claude` and
+`~/.codex` that run your working copy's `dist/cli.js`:
+
+```bash
+node libs/nocville-npc-library/dist/cli.js setup --api-key=<key> --api-url=http://localhost:3601
+node libs/nocville-npc-library/dist/cli.js uninstall   # remove them again
+```