@nocville/npc 0.2.1 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Marshall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ a hand when it needs you, dozes when idle, and shows what it's doing on its spee
 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.
+Requires Node.js 20+. Get an agent key in your Nocville office under **Connect AI coworkers**.
 
 ## Quick start: AI coworkers
 
@@ -16,23 +16,23 @@ 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:
+For scripts, pass `--api-key=<your key>` or set `NOCVILLE_API_KEY` instead. That's it. The
+command saves your key to `~/.config/nocville/config.json` (readable only by you), 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 hooks to `~/.gemini/settings.json`, keeping your settings and existing
+  hooks. Start a new session after setup.
+- **Cursor**: adds hooks to `~/.cursor/hooks.json`. Start a new chat after setup.
 
-- **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 `{}`.
+Your existing hooks are left alone, and Nocville's hooks never answer permission prompts or
+change what your agent does; they only report activity.
 
-- **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"`.
+Running your own Nocville server? Add `--api-url=https://your-server`. 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
@@ -71,26 +71,8 @@ checks the current folder (`--project=<dir>`, `--name=<session name>` to test ot
 | `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 gemini setup|uninstall` and `nocville-npc cursor setup|uninstall` manage
+Gemini CLI and Cursor on their own. For Cursor, start a new chat after setup.
 
 `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
@@ -111,58 +93,22 @@ are shortened to their first line, and anything that looks like a secret is reda
 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.
+**Overhead:** hooks return immediately and send updates from a background process, so your
+agent never waits on the network. Rapid bursts of activity are combined into one update.
+
+If an agent is killed, its coworker leaves the office within about 15 seconds. If your machine
+sleeps or goes offline, the coworker greys out after a few minutes and leaves after about
+thirteen. Claude subagent activity appears below the parent's current activity.
+
+### Windows
+
+Setup works the same way on Windows; it writes a small `nocville-hook.cmd` launcher to
+`~/.config/nocville/bin/` and points each agent's hooks at it. **Cursor users on Windows:**
+install Cursor's own hooks with `nocville-npc cursor setup` rather than relying on Cursor
+importing your Claude Code hooks.
+
+Re-running `setup` (for example after upgrading with `npx @nocville/npc@latest setup`) keeps
+your hooks in place and switches them to the new version; running sessions are not interrupted.
 
 ### How the Codex integration works
 
@@ -175,9 +121,8 @@ hooks, makes a one-time `hooks.json.nocville-backup`, and is safe to run again.
 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.
+without log activity (`--idle-timeout=<minutes>`) or when you press Ctrl-C. Sessions that
+hooks already report are left to the hooks.
 
 ## Monitoring NPCs
 
@@ -224,7 +169,7 @@ import type { CollectedMetrics } from '@nocville/npc';
 
 await new SystemMonitorNPC({
   apiUrl: 'https://nocville.com',
-  apiKey: 'noc_…',
+  apiKey: 'nvk_…',
   serviceId: 'web-1',
 }).start();
 
@@ -238,32 +183,7 @@ class MyNPC extends PollingNPC {
 }
 ```
 
-## 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
-```
+## Help
 
-**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
-```
+`nocville-npc --help` lists every command and flag, and `nocville-npc doctor` checks that your
+key and connection work. More at [nocville.com](https://nocville.com).

package/dist/cjs/core/session-filter.js

@@ -113,7 +113,9 @@ function projectMatches(pattern, projectDir) {
         const re = globRegExp(pattern, false);
         return dir.split('/').some((segment) => segment && re.test(segment));
     }
-    const expanded = normalizePath(pattern.startsWith('~') ? (0, node_os_1.homedir)() + pattern.slice(1) : pattern);
+    // A trailing `/*` or `/**` means "this folder and everything in it": subfolders already
+    // match through their ancestors, so drop it and the folder itself matches too.
+    const expanded = normalizePath((pattern.startsWith('~') ? (0, node_os_1.homedir)() + pattern.slice(1) : pattern).replace(/(\/\*{1,2})+$/, ''));
     const re = globRegExp(expanded, true);
     // The directory itself or any ancestor: a rule for a folder covers its subfolders.
     for (let p = dir; p; p = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '') {

package/dist/core/session-filter.d.ts

@@ -8,8 +8,8 @@
  * Patterns are case-insensitive globs (`*` any run of characters, `?` one character).
  * A `projects` pattern without a slash matches any folder name on the session's working
  * directory path (so `client-*` also covers `~/work/client-acme/api`); with a slash (or a
- * leading `~`) it matches that directory or anything inside it (`~/work/secret`,
- * `~/work/*`). A `sessions` pattern matches the agent's session name (Claude Code's
+ * leading `~`) it matches that directory or anything inside it; `~/work/secret`,
+ * `~/work/secret/*` and `~/work/secret/**` are equivalent). A `sessions` pattern matches the agent's session name (Claude Code's
  * session title); sessions without a name never match it.
  *
  * Read on every push, so edits apply to running sessions without reinstalling hooks.

package/dist/core/session-filter.js

@@ -106,7 +106,9 @@ function projectMatches(pattern, projectDir) {
         const re = globRegExp(pattern, false);
         return dir.split('/').some((segment) => segment && re.test(segment));
     }
-    const expanded = normalizePath(pattern.startsWith('~') ? homedir() + pattern.slice(1) : pattern);
+    // A trailing `/*` or `/**` means "this folder and everything in it": subfolders already
+    // match through their ancestors, so drop it and the folder itself matches too.
+    const expanded = normalizePath((pattern.startsWith('~') ? homedir() + pattern.slice(1) : pattern).replace(/(\/\*{1,2})+$/, ''));
     const re = globRegExp(expanded, true);
     // The directory itself or any ancestor: a rule for a folder covers its subfolders.
     for (let p = dir; p; p = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocville/npc",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Put your Claude Code and Codex sessions (and your servers) in the Nocville office as live NPCs",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
   ],
   "dependencies": {
     "pngjs": "^7.0.0",
-    "@nocville/node": "^0.2.1"
+    "@nocville/node": "^0.2.2"
   },
   "peerDependencies": {
     "puppeteer-core": "*"
@@ -59,11 +59,6 @@
   ],
   "license": "MIT",
   "homepage": "https://nocville.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/marshmansf/nocville.git",
-    "directory": "libs/nocville-npc-library"
-  },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))\" && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
     "clean": "rm -rf dist",