cocheck 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +17 -3
  2. package/dist/agent-transcripts.js +15 -12
  3. package/dist/attribution/evidence.js +2 -1
  4. package/dist/attribution/reconstruct.js +19 -0
  5. package/dist/attribution/tag.js +3 -3
  6. package/dist/build-info.json +1 -1
  7. package/dist/cli.js +31 -11
  8. package/dist/connector/export-view.js +1 -1
  9. package/dist/coverage.js +5 -3
  10. package/dist/credit-guard.js +59 -54
  11. package/dist/harness-cmd/create.js +76 -0
  12. package/dist/harness-cmd/index.js +19 -0
  13. package/dist/harness-cmd/record.js +327 -0
  14. package/dist/harness-cmd/scrub.js +25 -0
  15. package/dist/harness-cmd/test.js +318 -0
  16. package/dist/harnesses/README.md +5 -0
  17. package/dist/harnesses/claude/cocheck-harness.json +344 -0
  18. package/dist/harnesses/codex/cocheck-harness.json +212 -0
  19. package/dist/harnesses/copilot/cocheck-harness.json +296 -0
  20. package/dist/{copilot-helpers.js → helper-linker.js} +43 -32
  21. package/dist/hook-adapter.js +287 -63
  22. package/dist/hook-cli.js +73 -36
  23. package/dist/hook-journal.js +40 -12
  24. package/dist/hosts/claude.js +23 -159
  25. package/dist/hosts/codex.js +41 -81
  26. package/dist/hosts/compile.js +275 -0
  27. package/dist/hosts/copilot.js +7 -162
  28. package/dist/hosts/extras.js +55 -0
  29. package/dist/hosts/harnesses.js +66 -0
  30. package/dist/hosts/index.js +176 -8
  31. package/dist/hosts/install-block.js +332 -0
  32. package/dist/hosts/manifest.js +372 -0
  33. package/dist/hosts/shared.js +21 -0
  34. package/dist/hosts/tool-classes.js +6 -0
  35. package/dist/hosts/types.js +1 -0
  36. package/dist/install.js +69 -22
  37. package/dist/ledger.js +11 -0
  38. package/dist/normalize.js +33 -9
  39. package/dist/open-pick.js +5 -3
  40. package/dist/patch-secrets.js +11 -11
  41. package/dist/review-server.js +2 -2
  42. package/dist/timeline/attribution.js +2 -2
  43. package/dist/timeline/describe.js +20 -17
  44. package/dist/timeline/load.js +2 -2
  45. package/dist/timeline/rail/assets/review.js +1 -1
  46. package/dist/timeline/rail/model.js +8 -8
  47. package/dist/timeline/read-signal.js +4 -4
  48. package/dist/timeline/render/view-v1.js +2 -13
  49. package/dist/timeline/runs.js +9 -9
  50. package/dist/timeline/timeline.js +8 -8
  51. package/dist/timeline/write-signal.js +4 -3
  52. package/package.json +2 -2
  53. package/public-kit/harness/GUIDE.md +81 -0
  54. package/public-kit/harness/README.md +10 -0
  55. package/public-kit/harness/cases/claude/shell-writes-file.json +120 -0
  56. package/public-kit/harness/cases/codex/apply-patch-writes-files.json +177 -0
  57. package/public-kit/harness/cases/codex/helper-writes-file.json +160 -0
  58. package/public-kit/harness/cases/codex/shell-writes-and-fails.json +110 -0
  59. package/public-kit/harness/cases/copilot/camel-case-patch-and-failure.json +126 -0
  60. package/public-kit/harness/cases/copilot/helper-writes-file.json +209 -0
  61. package/public-kit/harness/cases/copilot/vscode-helper-writes-file.json +236 -0
  62. package/public-kit/harness/examples/toyagent/cases/write-notes.json +142 -0
  63. package/public-kit/harness/examples/toyagent/cocheck-harness.json +47 -0
  64. package/public-kit/harness/examples/toyagent/recordings/payloads.jsonl +8 -0
  65. package/public-kit/harness/harnesses/antigravity/README.md +32 -0
  66. package/public-kit/harness/harnesses/antigravity/cases/failed-edit.json +99 -0
  67. package/public-kit/harness/harnesses/antigravity/cases/helper-writes-file.json +270 -0
  68. package/public-kit/harness/harnesses/antigravity/cases/shell-ok-fail-and-denied.json +211 -0
  69. package/public-kit/harness/harnesses/antigravity/cases/write-then-edit.json +191 -0
  70. package/public-kit/harness/harnesses/antigravity/cocheck-harness.json +62 -0
  71. package/public-kit/harness/harnesses/antigravity/recordings/payloads.jsonl +63 -0
  72. package/public-kit/harness/harnesses/cursor/README.md +40 -0
  73. package/public-kit/harness/harnesses/cursor/cases/editor-write-edit-shell-helper.json +359 -0
  74. package/public-kit/harness/harnesses/cursor/cases/read-then-write-one-call-id.json +159 -0
  75. package/public-kit/harness/harnesses/cursor/cocheck-harness.json +67 -0
  76. package/public-kit/harness/harnesses/cursor/recordings/payloads.jsonl +28 -0
  77. package/public-kit/harness/scaffold/README.md +42 -0
  78. package/public-kit/harness/scaffold/cocheck-harness.json +72 -0
  79. package/public-kit/harness/scaffold/recordings/.gitkeep +0 -0
  80. package/public-kit/harness/spec/v1.md +286 -0
  81. package/scripts/hook-launch.sh +1 -1
package/README.md CHANGED
@@ -34,7 +34,7 @@ CoCheck runs on a Mac, and on Windows with Claude Code; other platforms are plan
34
34
 
35
35
  ## What it does
36
36
 
37
- CoCheck hooks into the coding agents you already use and records their work as they do it. It supports Claude Code, Codex and Copilot. The agent needs no special tools.
37
+ CoCheck hooks into the coding agents you already use and records their work as they do it. It supports Claude Code, Codex, Copilot, Cursor and Antigravity CLI (see Supported agents below). The agent needs no special tools.
38
38
 
39
39
  You start tracking per session, in plain words: tell the agent "start tracking". Every session starts untracked, and an untracked session records nothing. "Stop tracking" ends it, and what was recorded stays.
40
40
 
@@ -58,7 +58,20 @@ None of these is available yet.
58
58
 
59
59
  - Stronger attribution: tying each change to the exact process that wrote it, not only to the agent calls open at the time.
60
60
  - Better Excel pictures: Excel's charts shown beside the cells they draw from.
61
- - A standard for adding agent harnesses: a published format so anyone can connect a new agent harness to CoCheck, the way the connector standard does for apps.
61
+
62
+ ## Supported agents
63
+
64
+ CoCheck reads each agent through a harness manifest, a data file that says how the agent's hooks look. The table below is generated from the manifests by `scripts/readme-agents.ts`. Built-in harnesses ship with CoCheck. Harnesses from the kit are not built in: copy the folder to `<data home>/harnesses/<key>/` to use one, and `cocheck install --for <key>` then prints the hook entries to add. Their changes are credited to the agent's call by what changed while the call was open ("inferred"). To add an agent, see [public-kit/harness/GUIDE.md](public-kit/harness/GUIDE.md) and [docs/hooks.md](docs/hooks.md).
65
+
66
+ <!-- supported-agents:start (generated by scripts/readme-agents.ts; do not edit by hand) -->
67
+ | Agent | Tested versions | How it is supported |
68
+ | --- | --- | --- |
69
+ | Claude Code | not listed | built in |
70
+ | Codex | 0.162.0-alpha.2, 0.164.0-alpha.11.1 | built in |
71
+ | Copilot | 1.0.93, 1.0.98, 1.140.0 | built in |
72
+ | Antigravity CLI | 1.5.14 | harness kit (loaded from your data folder) |
73
+ | Cursor | 3.31.15 | harness kit (loaded from your data folder) |
74
+ <!-- supported-agents:end -->
62
75
 
63
76
  ## Install and use
64
77
 
@@ -82,12 +95,13 @@ Run `cocheck install` from the folder you want CoCheck to watch, or pass `--fold
82
95
 
83
96
  ## Platforms
84
97
 
85
- CoCheck runs on a Mac, or on Windows with Claude Code (Node 22.18 or newer; see the Windows section of [docs/install.md](docs/install.md)). Codex and Copilot are documented for Mac only. The hook capture is written so other operating systems and other agents can follow. [platforms/README.md](platforms/README.md) holds the sourced record of what each agent platform lets CoCheck do (Claude Code, Codex, Copilot CLI, Copilot in VS Code, ChatGPT Work, Claude Cowork).
98
+ CoCheck runs on a Mac, or on Windows with Claude Code (Node 22.18 or newer; see the Windows section of [docs/install.md](docs/install.md)). Codex and Copilot are documented for Mac only, and Cursor and Antigravity CLI were recorded on a Mac. The hook capture is written so other operating systems and other agents can follow. [platforms/README.md](platforms/README.md) holds the sourced record of what each agent platform lets CoCheck do (Claude Code, Codex, Copilot CLI, Copilot in VS Code, Cursor, Antigravity CLI, ChatGPT Work, Claude Cowork).
86
99
 
87
100
  ## Docs
88
101
 
89
102
  - [docs/install.md](docs/install.md): install, start and stop tracking, the review page, uninstall, troubleshooting.
90
103
  - [public-kit/GUIDE.md](public-kit/GUIDE.md): build a connector for another file type or app.
104
+ - [public-kit/harness/GUIDE.md](public-kit/harness/GUIDE.md): add another agent (a harness).
91
105
  - [docs/hooks.md](docs/hooks.md): how the hook adapter records and attributes changes.
92
106
  - [docs/attribution-tag.md](docs/attribution-tag.md): how a change is tied to the call that made it.
93
107
  - [docs/timeline.md](docs/timeline.md): how the review page's timeline is built.
@@ -2,7 +2,10 @@
2
2
  // (the launching call's `toolUseId`) and `agent-<agent_id>.jsonl` (the agent's own transcript). Only ids are read from them, never words.
3
3
  import { closeSync, constants, lstatSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
4
4
  import path from "node:path";
5
- import { defaultProfile } from "./hosts/index.js";
5
+ import { profileWithExtra, toolEntryOf } from "./hosts/index.js";
6
+ /** The host whose helpers keep transcripts and meta files beside the session's, read by this module. */
7
+ const helperHost = () => profileWithExtra("transcript-helpers");
8
+ import { isBackgroundableShell } from "./credit-guard.js";
6
9
  import { classifyToolResult, neverRan, resultRunsOn } from "./credit-guard.js";
7
10
  /**
8
11
  * A host-sent identifier kept only when it is a short plain string that starts with a letter, digit, underscore, colon or hyphen (so it
@@ -27,7 +30,7 @@ const CHUNK = 1024 * 1024;
27
30
  function readMeta(subagentsDir, agentId) {
28
31
  const none = { launcher: undefined, background: false };
29
32
  try {
30
- const file = path.join(subagentsDir, defaultProfile().helpers.metaFile(agentId));
33
+ const file = path.join(subagentsDir, helperHost().helpers.metaFile(agentId));
31
34
  const st = lstatSync(file);
32
35
  if (!st.isFile() || st.size > AGENT_META_MAX_BYTES)
33
36
  return none;
@@ -53,7 +56,7 @@ export function readLauncher(subagentsDir, agentId) {
53
56
  * (`NODE_TEST_CONTEXT` is set in every test process) the `~/.claude` default is refused, so a test cannot read the real transcripts.
54
57
  */
55
58
  export function defaultTranscriptsRoot() {
56
- return defaultProfile().helpers.projectsRoot();
59
+ return helperHost().helpers.projectsRoot();
57
60
  }
58
61
  const isRealDir = (p) => {
59
62
  try {
@@ -77,13 +80,13 @@ function realDirUnder(root, ...parts) {
77
80
  /** The `subagents` folder of one session under the transcripts root: the task folder's project dir first, then any project dir that holds the session. */
78
81
  function subagentsDirOf(root, folder, session) {
79
82
  if (folder !== null) {
80
- const direct = realDirUnder(root, folder.replace(/[^A-Za-z0-9]/g, "-"), session, defaultProfile().helpers.folderName);
83
+ const direct = realDirUnder(root, folder.replace(/[^A-Za-z0-9]/g, "-"), session, helperHost().helpers.folderName);
81
84
  if (direct !== null)
82
85
  return direct;
83
86
  }
84
87
  try {
85
88
  for (const name of readdirSync(root).slice(0, MAX_PROJECT_DIRS)) {
86
- const candidate = realDirUnder(root, name, session, defaultProfile().helpers.folderName);
89
+ const candidate = realDirUnder(root, name, session, helperHost().helpers.folderName);
87
90
  if (candidate !== null)
88
91
  return candidate;
89
92
  }
@@ -238,7 +241,7 @@ function markBackgroundLaunchers(ops, source) {
238
241
  const tool = typeof a?.tool_name === "string" ? a.tool_name : op.tool;
239
242
  if (a === null || typeof a !== "object" || session === undefined || typeof a.tool_use_id !== "string" || a.background === true)
240
243
  return;
241
- if (tool !== "Agent" && tool !== "Task")
244
+ if (toolEntryOf(typeof a.host === "string" ? a.host : null, tool)?.backgroundFlag !== true)
242
245
  return;
243
246
  wanted.set(session, [...(wanted.get(session) ?? []), { at, id: a.tool_use_id, a }]);
244
247
  }
@@ -255,14 +258,14 @@ function markBackgroundLaunchers(ops, source) {
255
258
  continue;
256
259
  let names;
257
260
  try {
258
- names = readdirSync(dir).filter((n) => defaultProfile().helpers.metaName.test(n)).sort().slice(0, MAX_AGENT_FILES);
261
+ names = readdirSync(dir).filter((n) => helperHost().helpers.metaName.test(n)).sort().slice(0, MAX_AGENT_FILES);
259
262
  }
260
263
  catch {
261
264
  continue;
262
265
  }
263
266
  const background = new Set();
264
267
  for (const name of names) {
265
- const agentId = cleanId(defaultProfile().helpers.idOfMeta(name));
268
+ const agentId = cleanId(helperHost().helpers.idOfMeta(name));
266
269
  if (agentId === undefined)
267
270
  continue;
268
271
  const m = readMeta(dir, agentId);
@@ -304,7 +307,7 @@ function backfillAgentIds(ops, source) {
304
307
  continue;
305
308
  let names;
306
309
  try {
307
- names = readdirSync(dir).filter((n) => defaultProfile().helpers.transcriptName.test(n)).sort().slice(0, MAX_AGENT_FILES);
310
+ names = readdirSync(dir).filter((n) => helperHost().helpers.transcriptName.test(n)).sort().slice(0, MAX_AGENT_FILES);
308
311
  }
309
312
  catch {
310
313
  continue;
@@ -312,7 +315,7 @@ function backfillAgentIds(ops, source) {
312
315
  const owner = new Map();
313
316
  const budget = { left: MAX_SESSION_BYTES };
314
317
  for (const name of names) {
315
- const agentId = cleanId(defaultProfile().helpers.idOfTranscript(name));
318
+ const agentId = cleanId(helperHost().helpers.idOfTranscript(name));
316
319
  if (agentId === undefined)
317
320
  continue;
318
321
  for (const id of toolUseIds(path.join(dir, name), session, budget) ?? [])
@@ -369,7 +372,7 @@ export class EvidenceCollector {
369
372
  if (id === undefined || this.#uses.has(id))
370
373
  continue;
371
374
  const input = (b.input ?? {});
372
- this.#uses.set(id, { msg, at, lane, background: b.name === "Bash" && input?.run_in_background === true });
375
+ this.#uses.set(id, { msg, at, lane, background: isBackgroundableShell(typeof b.name === "string" ? b.name : null, helperHost().key) && input?.run_in_background === true });
373
376
  }
374
377
  return;
375
378
  }
@@ -529,7 +532,7 @@ export function callEvidenceOf(ops, source) {
529
532
  continue;
530
533
  let names;
531
534
  try {
532
- names = readdirSync(dir).filter((n) => defaultProfile().helpers.transcriptName.test(n)).sort().slice(0, MAX_AGENT_FILES);
535
+ names = readdirSync(dir).filter((n) => helperHost().helpers.transcriptName.test(n)).sort().slice(0, MAX_AGENT_FILES);
533
536
  }
534
537
  catch {
535
538
  continue;
@@ -4,6 +4,7 @@
4
4
  // windows (hook-adapter.ts, `#proven`); with no record for a path, or a record it cannot trust, the open-call rule is unchanged.
5
5
  import { closeSync, openSync, readdirSync, readSync, rmSync, statSync } from "node:fs";
6
6
  import path from "node:path";
7
+ import { isBackgroundableShell } from "../credit-guard.js";
7
8
  import { evidenceDir } from "./tag.js";
8
9
  const LOG_NAME = /^writes-(\d{4}-\d{2}-\d{2})\.jsonl$/;
9
10
  const ID = /^[A-Za-z0-9_-]{1,128}$/;
@@ -265,7 +266,7 @@ export function strictWriters(file, candidates, writers, factsOf, unobserved) {
265
266
  return undefined;
266
267
  if (!c.mayWrite)
267
268
  continue;
268
- if (c.tool !== "Bash" || !c.tagged || !c.hooked || !observedOnly(c.command) || c.command.toLowerCase().includes(base) || unobserved.has(id))
269
+ if (!isBackgroundableShell(c.tool, c.host) || !c.tagged || !c.hooked || !observedOnly(c.command) || c.command.toLowerCase().includes(base) || unobserved.has(id))
269
270
  return undefined;
270
271
  }
271
272
  return [...writers].sort();
@@ -19,6 +19,25 @@ function applyEdits(text, edits) {
19
19
  }
20
20
  return text;
21
21
  }
22
+ /**
23
+ * The text before `edits` were applied, from the text after them: each edit undone in reverse order, its new text found exactly once and put
24
+ * back as its old text. Only single replacements undo (an `all` edit or an empty new text cannot be placed), and the result must give `text`
25
+ * again when the edits are replayed on it; anything else gives `undefined`. The result is built from the edit itself, so it can never prove that edit.
26
+ */
27
+ export function revertEdits(text, edits) {
28
+ if (edits.length === 0)
29
+ return undefined;
30
+ let before = text;
31
+ for (const e of [...edits].reverse()) {
32
+ if (typeof e.old !== "string" || typeof e.new !== "string" || e.new === "")
33
+ return undefined;
34
+ const first = before.indexOf(e.new);
35
+ if (first < 0 || before.indexOf(e.new, first + 1) >= 0)
36
+ return undefined;
37
+ before = before.slice(0, first) + e.old + before.slice(first + e.new.length);
38
+ }
39
+ return applyEdits(before, edits.map((e) => ({ old: e.old, new: e.new, all: false }))) === text ? before : undefined;
40
+ }
22
41
  /** Applies patch sections to `text` (LF text only): each hunk's context and removed lines must be found, in order, from where the last one ended. */
23
42
  function applySections(text, sections) {
24
43
  for (const sec of sections) {
@@ -48,9 +48,9 @@ export function tagsInMode(setting, permissionMode) {
48
48
  return true;
49
49
  return permissionMode === "bypassPermissions";
50
50
  }
51
- /** The shell Claude Code runs Bash calls in: `CLAUDE_CODE_SHELL`, else `SHELL`; only bash and zsh are tagged. */
52
- export function callShell(env) {
53
- for (const s of [env.CLAUDE_CODE_SHELL, env.SHELL]) {
51
+ /** The shell the host runs its shell calls in (`shellEnv` names the variable it sets), else `SHELL`; only bash and zsh are tagged. */
52
+ export function callShell(env, shellEnv) {
53
+ for (const s of [shellEnv === undefined ? undefined : env[shellEnv], env.SHELL]) {
54
54
  if (!s || !path.isAbsolute(s))
55
55
  continue;
56
56
  const base = path.basename(s);
@@ -1 +1 @@
1
- {"builtAt":1795214294273}
1
+ {"builtAt":1795388563672}
package/dist/cli.js CHANGED
@@ -16,10 +16,9 @@ import { readFileSync } from "node:fs";
16
16
  import path from "node:path";
17
17
  import { homedir } from "node:os";
18
18
  import { installStatus, readInstallRecord, runInstall } from "./install.js";
19
- import { allProfiles } from "./hosts/index.js";
20
- import { readCodexHooksList } from "./hosts/codex-trust.js";
19
+ import { allProfiles, installableKeys } from "./hosts/index.js";
21
20
  import { listTracked } from "./tracking.js";
22
- const USAGE = `usage:
21
+ const usage = () => `usage:
23
22
  cocheck open [task]
24
23
  cocheck status
25
24
  cocheck track start|stop|status
@@ -27,11 +26,15 @@ const USAGE = `usage:
27
26
  cocheck connector test <dir> --cases [<casesDir>]
28
27
  cocheck connector auth <id> --name <credential> [--delete]
29
28
  cocheck connector create <dir> --id <id>
29
+ cocheck harness create <key> [--dir <path>]
30
+ cocheck harness record <key> --manifest <path> --out <dir> [--timeout <seconds>] [-- <harness command...>]
31
+ cocheck harness record --stop <scratch>
32
+ cocheck harness test --cases <dir> [--manifest <path>]
30
33
  cocheck connector doctor [<id>]
31
34
  cocheck connector list
32
35
  cocheck connector enable|disable <id> <file ending>
33
- cocheck install --home <dir> [--folder <dir>] [--for claude|codex|copilot|both|all|none, or a comma list]
34
- cocheck uninstall [--for claude|codex|copilot|both|all, or a comma list]
36
+ cocheck install --home <dir> [--folder <dir>] [--for ${installableKeys().join("|")}|both|all|none, or a comma list]
37
+ cocheck uninstall [--for ${installableKeys().join("|")}|both|all, or a comma list]
35
38
  cocheck --help
36
39
  cocheck --version`;
37
40
  /** The settle before `cocheck open` re-checks the review process: past the orphan guard's first tick, so a process that dies right after its first answer is caught. */
@@ -48,8 +51,8 @@ export async function settledHealthy(home, url, settleMs = OPEN_SETTLE_MS) {
48
51
  /** `cocheck open`: names "not recording" with its reason first, then opens the page. A page that cannot open is still an error. */
49
52
  export async function runOpen(run, task) {
50
53
  if (task !== undefined && !/^[1-9][0-9]*$/.test(task))
51
- return { exitCode: 1, stdout: "", stderr: `task must be a plain decimal id (e.g. 12), got ${JSON.stringify(task)}\n${USAGE}\n` };
52
- const status = installStatus(run.env, run.userHome, readCodexHooksList);
54
+ return { exitCode: 1, stdout: "", stderr: `task must be a plain decimal id (e.g. 12), got ${JSON.stringify(task)}\n${usage()}\n` };
55
+ const status = installStatus(run.env, run.userHome, "live");
53
56
  if (status.record === undefined)
54
57
  return { exitCode: 1, stdout: "", stderr: status.text };
55
58
  const notice = status.recording && (status.hostProblems ?? []).length === 0 ? "" : status.text;
@@ -141,13 +144,13 @@ export async function connectorHome(userHome, env = process.env) {
141
144
  export async function main(argv) {
142
145
  const [command, ...rest] = argv;
143
146
  if (command === "--help" || command === "-h" || command === "help")
144
- return { exitCode: 0, stdout: `${USAGE}\n`, stderr: "" };
147
+ return { exitCode: 0, stdout: `${usage()}\n`, stderr: "" };
145
148
  if (command === "--version" || command === "-v" || command === "version")
146
149
  return { exitCode: 0, stdout: versionText(), stderr: "" };
147
150
  const userHome = process.env.HOME || homedir();
148
151
  if (command === "open") {
149
152
  if (rest.length > 1)
150
- return { exitCode: 1, stdout: "", stderr: `open takes at most one task\n${USAGE}\n` };
153
+ return { exitCode: 1, stdout: "", stderr: `open takes at most one task\n${usage()}\n` };
151
154
  const { pickOpenChoice, reviewIndexUrl, openReviewUrl } = await import("./review-server.js");
152
155
  return runOpen({
153
156
  env: process.env,
@@ -160,11 +163,28 @@ export async function main(argv) {
160
163
  }, rest[0]);
161
164
  }
162
165
  if (command === "status") {
163
- const status = installStatus(process.env, userHome, readCodexHooksList);
166
+ const status = installStatus(process.env, userHome, "live");
164
167
  return { exitCode: status.recording && (status.hostProblems ?? []).length === 0 ? 0 : 1, stdout: status.text, stderr: "" };
165
168
  }
166
169
  if (command === "track")
167
170
  return runTrack(rest, userHome, process.stdin.isTTY === true && process.stdout.isTTY === true);
171
+ if (command === "harness") {
172
+ const { runHarnessCommand } = await import("./harness-cmd/index.js");
173
+ const out = [];
174
+ const err = [];
175
+ const abort = new AbortController();
176
+ const onSignal = () => abort.abort();
177
+ process.on("SIGINT", onSignal);
178
+ process.on("SIGTERM", onSignal);
179
+ try {
180
+ const exitCode = await runHarnessCommand(rest, { out: (l) => out.push(l), err: (l) => err.push(l), env: process.env, cwd: process.cwd(), signal: abort.signal });
181
+ return { exitCode: exitCode === 0 ? 0 : 1, stdout: out.map((l) => `${l}\n`).join(""), stderr: err.map((l) => `${l}\n`).join("") };
182
+ }
183
+ finally {
184
+ process.off("SIGINT", onSignal);
185
+ process.off("SIGTERM", onSignal);
186
+ }
187
+ }
168
188
  if (command === "connector" && rest[0] === "test") {
169
189
  const { runConnectorTest } = await import("./connector-test-cli.js");
170
190
  return runConnectorTest(rest.slice(1), { home: await connectorHome(userHome) });
@@ -189,5 +209,5 @@ export async function main(argv) {
189
209
  if (command === "install" || command === "uninstall") {
190
210
  return runInstall({ argv: ["node", "install.ts", ...(command === "uninstall" ? ["--uninstall"] : []), ...rest], env: process.env, cwd: process.cwd() });
191
211
  }
192
- return { exitCode: 1, stdout: "", stderr: `${USAGE}\n` };
212
+ return { exitCode: 1, stdout: "", stderr: `${usage()}\n` };
193
213
  }
@@ -8,6 +8,6 @@ export function exportDocOf(connector, subject, before, after) {
8
8
  const view = renderer.view(before === null ? null : Buffer.from(before, "utf8"), after === null ? null : Buffer.from(after, "utf8"), { id: "export", file: subject.split(/[\\/]/).pop() || subject, kind });
9
9
  if (view instanceof Promise)
10
10
  throw new Error("the text renderer is synchronous");
11
- const doc = viewToV1(view, { cards: [], rowNotes: [] });
11
+ const doc = viewToV1(view, { rowNotes: [] });
12
12
  return { ...doc, source: { by: "cocheck", name: connector, level: doc.source?.level ?? 3 } };
13
13
  }
package/dist/coverage.js CHANGED
@@ -13,7 +13,9 @@
13
13
  import { closeSync, constants, fstatSync, lstatSync, openSync, readdirSync, readFileSync, statSync } from "node:fs";
14
14
  import path from "node:path";
15
15
  import { AGENT_TRANSCRIPT_MAX_BYTES, cleanId } from "./agent-transcripts.js";
16
- import { defaultProfile, findProfile } from "./hosts/index.js";
16
+ import { findProfile, profileWithExtra } from "./hosts/index.js";
17
+ /** The host whose transcripts hold the helper files read here. */
18
+ const helperHost = () => profileWithExtra("transcript-coverage");
17
19
  import { journalDegraded, journalSessionKey, readJournalSession } from "./hook-journal.js";
18
20
  const MAX_AGENT_FILES = 200;
19
21
  const NAMES_MAX = 30;
@@ -96,10 +98,10 @@ export function readClaudeCalls(transcriptPath, sessionId) {
96
98
  idsOfFile(transcriptPath, ids, rejected, files);
97
99
  const sid = cleanId(sessionId);
98
100
  if (sid !== undefined) {
99
- const dir = defaultProfile().helpers.dirOf(transcriptPath, sid);
101
+ const dir = helperHost().helpers.dirOf(transcriptPath, sid);
100
102
  let names = [];
101
103
  try {
102
- names = readdirSync(dir).filter((n) => defaultProfile().helpers.transcriptName.test(n));
104
+ names = readdirSync(dir).filter((n) => helperHost().helpers.transcriptName.test(n));
103
105
  }
104
106
  catch {
105
107
  // no subagents
@@ -22,6 +22,7 @@ import { realpathSync } from "node:fs";
22
22
  import path from "node:path";
23
23
  import { createPathKit } from "./paths.js";
24
24
  import { platform, platformFor } from "./platform/index.js";
25
+ import { toolEntryOf } from "./hosts/index.js";
25
26
  /**
26
27
  * The path kit the credit guards compare with. Windows folds case; a Mac volume compares exactly in `PathKit`, but the credit
27
28
  * guards have always folded case on the Mac (APFS is case-insensitive by default, and a wrong "different file" would drop a real credit), so
@@ -77,21 +78,8 @@ function foldPath(p, real, kit) {
77
78
  export function isInternalAgentCall(call) {
78
79
  return call.agentId != null && call.agentType == null && call.launchId == null;
79
80
  }
80
- /**
81
- * Tools that cannot write a file in the folder. The guard adds the launcher (an Agent or Task call: its agent's own calls carry its work), the web
82
- * tools (they write only the host's own tool-results cache), the host's bookkeeping tools, and reads of a background shell.
83
- */
84
- const NO_CREDIT_TOOLS = new Set([
85
- "Read", "Glob", "Grep", "SendMessage", "LS", "NotebookRead",
86
- "WebFetch", "WebSearch", "ToolSearch", "Skill", "TodoWrite", "TodoRead",
87
- "TaskCreate", "TaskUpdate", "TaskList", "TaskGet", "TaskOutput", "BashOutput", "AskUserQuestion", "ExitPlanMode", "EnterPlanMode",
88
- "ListMcpResourcesTool", "ReadMcpResourceTool",
89
- // Copilot's read-only tools, as named in the recorded 1.0.103 run (platforms/copilot-cli/versions/1.0.103/hook-calls.jsonl)
90
- "glob", "rg", "view",
91
- // Codex's helper bookkeeping, by the tools' own names (the Codex profile takes its namespace off): a message to a helper, the helper list.
92
- "send_message", "list_agents",
93
- ]);
94
- const FILE_TOOLS = new Set(["Write", "Edit", "MultiEdit"]);
81
+ // Which tools cannot write a file in the folder, write one by path, run a shell, launch a helper or wait is each host's own table
82
+ // (`HostProfile.toolClasses`); every rule here asks it through the call's host. A record with no host reads the built-in tables together.
95
83
  /** An MCP tool's own name (`mcp__<server>__<tool>`) that only reads: a read verb first, and no write verb anywhere in it. */
96
84
  const MCP_READ_VERB = /^(get|list|search|read|query|fetch|find|describe|count|aggregate|view|show|lookup|inspect|check|validate|preview|export)(_|-|$)/i;
97
85
  const MCP_WRITE_WORD = /(^|_|-)(create|update|write|set|delete|remove|save|put|post|upload|apply|insert|edit|move|rename|copy|send|run|exec|execute|import|add|patch|replace|modify|append|trash|merge|publish|deploy|download)(_|-|$)/i;
@@ -103,34 +91,51 @@ export function isReadOnlyMcpTool(tool) {
103
91
  return own !== "" && MCP_READ_VERB.test(own) && !MCP_WRITE_WORD.test(own);
104
92
  }
105
93
  /** A tool that can never write a file: never credited with any change. */
106
- export function toolNeverWrites(tool) {
107
- return tool != null && (NO_CREDIT_TOOLS.has(tool) || isReadOnlyMcpTool(tool));
94
+ export function toolNeverWrites(tool, host) {
95
+ if (tool == null)
96
+ return false;
97
+ const c = toolEntryOf(host, tool)?.class;
98
+ return c === "read" || c === "read-only" || c === "never-credited" || isReadOnlyMcpTool(tool);
108
99
  }
109
100
  /**
110
101
  * Whether the call's own tool allows it to be credited with a change to `file`. `filePath` is the call's file_path input, when known;
111
102
  * `same` compares two paths; `kit` says what an absolute path is on this platform. A file tool with no usable path (absent, relative, masked) stays creditable: unknown is the safe direction.
112
103
  */
113
- export function toolMayCredit(tool, filePath, file, same, kit = guardKit()) {
114
- if (toolNeverWrites(tool))
104
+ export function toolMayCredit(tool, filePath, file, same, kit = guardKit(), host) {
105
+ if (toolNeverWrites(tool, host))
115
106
  return false;
116
- if (tool != null && FILE_TOOLS.has(tool) && typeof filePath === "string" && kit.isAbs(filePath) && kit.isAbs(file))
107
+ if (tool != null && toolEntryOf(host, tool)?.pathChecked === true && typeof filePath === "string" && kit.isAbs(filePath) && kit.isAbs(file))
117
108
  return same(filePath, file);
118
109
  return true;
119
110
  }
120
- /** The host tool names that run a shell command (Claude Code and Codex `Bash`, Copilot `bash`, Claude Code `PowerShell`, Copilot `powershell`, `pwsh`). The one set hook-cli, src/timeline/describe.ts and `isShellTool` all read. */
121
- export const SHELL_TOOLS = /^(bash|shell|sh|zsh|exec|exec_command|local_shell|container\.exec|run_shell_command|terminal|powershell|pwsh)$/i;
122
- export const isShellTool = (tool) => tool != null && SHELL_TOOLS.test(tool);
123
- /** Tools whose own input names the file they write, by the field that holds it: Claude Write/Edit/MultiEdit, Copilot create/edit (`path`). */
124
- const WRITE_PATH_FIELD = { write: ["file_path", "path"], edit: ["file_path", "path"], multiedit: ["file_path"], create: ["path", "file_path"], notebookedit: ["notebook_path"] };
111
+ /** Whether the tool runs a shell command, by the host's own table (in any letter case). The one predicate hook-cli, src/timeline/describe.ts and the adapter read. */
112
+ export const isShellTool = (tool, host) => toolEntryOf(host, tool, true)?.class === "shell";
113
+ /** The dialect a shell tool's command is written in, when the host's table names one. */
114
+ export const shellDialectOf = (tool, host) => {
115
+ const e = toolEntryOf(host, tool, true);
116
+ return e?.class === "shell" ? e.dialect : undefined;
117
+ };
118
+ /** A shell tool whose command can leave a process running past its result (the host's main shell tool). */
119
+ export const isBackgroundableShell = (tool, host) => toolEntryOf(host, tool)?.backgroundable === true;
120
+ /** A tool whose class is read: it names the file it looked at in its own input. */
121
+ export const isReadTool = (tool, host) => toolEntryOf(host, tool)?.class === "read";
122
+ /** A tool that carries a patch, by the host's table (any letter case). */
123
+ export const isPatchClass = (tool, host) => toolEntryOf(host, tool, true)?.class === "patch";
124
+ /** A tool whose input has the file-tool shape (`file_path` plus content, old or new strings): the timeline's write and read signals read these. */
125
+ export const hasFileInput = (tool, host) => toolEntryOf(host, tool)?.fileInput === true;
126
+ /** The input fields that name the file a write, edit or notebook-edit tool changes, in order (any letter case). */
127
+ const pathFieldsOf = (tool, host) => toolEntryOf(host, tool, true)?.pathFields;
125
128
  /**
126
129
  * The absolute paths a host file-edit call's own input reports (unresolved), or undefined when the tool is not one that names its file
127
130
  * (a shell call, anything unlisted) or any target is not absolute (a relative path proves nothing). `isAbs` is the path kit's.
128
131
  */
129
- export function editTargetsOf(tool, input, isAbs, resolveRel) {
130
- if (tool == null || !(tool.toLowerCase() in WRITE_PATH_FIELD) && !FILE_TOOLS.has(tool) && !/^(apply_patch|patch)$/i.test(tool))
132
+ export function editTargetsOf(tool, input, isAbs, resolveRel, host) {
133
+ if (tool == null)
134
+ return undefined;
135
+ const isPatch = isPatchClass(tool, host);
136
+ if (pathFieldsOf(tool, host) === undefined && !isPatch)
131
137
  return undefined;
132
- const isPatch = /^(apply_patch|patch)$/i.test(tool);
133
- const targets = writeTargetsOf(tool, input).map((p) => (isPatch && resolveRel !== undefined && !isAbs(p) && !p.startsWith("~") ? resolveRel(p) : p));
138
+ const targets = writeTargetsOf(tool, input, host).map((p) => (isPatch && resolveRel !== undefined && !isAbs(p) && !p.startsWith("~") ? resolveRel(p) : p));
134
139
  return targets.length > 0 && targets.every(isAbs) ? targets : undefined;
135
140
  }
136
141
  const EDIT_CAP = 64 * 1024;
@@ -140,14 +145,13 @@ const EDIT_CAP = 64 * 1024;
140
145
  * A file the input does not describe exactly (a field missing, a move, a delete, a relative path), or a call whose strings pass the size cap,
141
146
  * gets nothing: it stays inferred. A relative apply_patch header is resolved with `resolveRel` (the host's cwd) when given. Bound: read from the input only.
142
147
  */
143
- export function reportedEditsOf(tool, input, isAbs, sha256, resolveRel) {
148
+ export function reportedEditsOf(tool, input, isAbs, sha256, resolveRel, host) {
144
149
  if (tool == null || input == null)
145
150
  return [];
146
- const t = tool.toLowerCase();
147
151
  const rec = typeof input === "object" ? input : undefined;
148
152
  const str = (v) => (typeof v === "string" ? v : undefined);
149
153
  const out = [];
150
- if (t === "apply_patch" || t === "patch") {
154
+ if (isPatchClass(tool, host)) {
151
155
  const text = typeof input === "string" ? input : rec === undefined ? "" : ["input", "patch", "command", "diff"].map((k) => rec[k]).find((v) => typeof v === "string") ?? "";
152
156
  let cur;
153
157
  let section;
@@ -185,7 +189,7 @@ export function reportedEditsOf(tool, input, isAbs, sha256, resolveRel) {
185
189
  }
186
190
  if (rec === undefined)
187
191
  return [];
188
- const target = writeTargetsOf(tool, input)[0];
192
+ const target = writeTargetsOf(tool, input, host)[0];
189
193
  if (target === undefined || !isAbs(target))
190
194
  return [];
191
195
  const content = str(rec.content) ?? str(rec.file_text);
@@ -214,12 +218,11 @@ const PATCH_HEADER = /^\*\*\* (?:Add File|Update File|Delete File|Move to):[ \t]
214
218
  * whether the input is the patch text itself (Copilot) or an object holding it. Bound: read from the call's input only, never from a shell
215
219
  * command; a tool or shape not listed names nothing.
216
220
  */
217
- export function writeTargetsOf(tool, input) {
221
+ export function writeTargetsOf(tool, input, host) {
218
222
  if (tool == null)
219
223
  return [];
220
- const t = tool.toLowerCase();
221
224
  const out = [];
222
- const fields = WRITE_PATH_FIELD[t];
225
+ const fields = pathFieldsOf(tool, host);
223
226
  if (fields !== undefined && typeof input === "object" && input !== null) {
224
227
  for (const f of fields) {
225
228
  const v = input[f];
@@ -229,7 +232,7 @@ export function writeTargetsOf(tool, input) {
229
232
  }
230
233
  }
231
234
  }
232
- if (t === "apply_patch" || t === "patch") {
235
+ if (isPatchClass(tool, host)) {
233
236
  const texts = typeof input === "string" ? [input] : typeof input === "object" && input !== null ? ["input", "patch", "command", "diff"].map((k) => input[k]).filter((v) => typeof v === "string") : [];
234
237
  for (const text of texts)
235
238
  for (const m of text.matchAll(PATCH_HEADER))
@@ -238,40 +241,42 @@ export function writeTargetsOf(tool, input) {
238
241
  return out;
239
242
  }
240
243
  /**
241
- * The one launcher predicate, by the tool's own name (a host's namespace is taken off at ingest and on read, `HostProfile.toolName`): Claude
242
- * Code's `Agent` and `Task`, Copilot's `task`, Codex's `spawn_agent`. A name that merely contains "task" or "agent" (`TaskCreate`, `TodoWrite`,
243
- * `read_agent`, `wait_agent`) is not a launch.
244
+ * The one launcher predicate, by the tool's own name in the host's table (a host's namespace is taken off at ingest and on read,
245
+ * `HostProfile.toolName`). A name that merely contains "task" or "agent" (`TaskCreate`, `TodoWrite`, `read_agent`, `wait_agent`) is not a launch.
244
246
  */
245
- export const isLauncherTool = (tool) => tool === "Agent" || tool === "Task" || tool === "task" || tool === "spawn_agent";
246
- /** Codex's `wait_agent`, by its own name: a call whose only work is waiting on helpers. */
247
- export const isWaitTool = (tool) => tool === "wait_agent";
247
+ export const isLauncherTool = (tool, host) => toolEntryOf(host, tool)?.class === "launcher";
248
+ /** A tool that waits on helpers whatever its input says: a call whose only work is waiting. */
249
+ export const isWaitTool = (tool, host) => {
250
+ const e = toolEntryOf(host, tool);
251
+ return e?.class === "wait" && e.waitFlag === undefined;
252
+ };
248
253
  /**
249
- * Whether a call waits on helpers and so writes nothing: Codex `wait_agent`, or Copilot's `read_agent` called with `wait: true`
250
- * (`read_agent` without it is a status read, which keeps today's credit). The adapter records the answer on the call (`waits`) because the
251
- * timeline's tool label keeps field names, never values.
254
+ * Whether a call waits on helpers and so writes nothing: a wait tool, or one that waits only with its flag set (a status read without it,
255
+ * which keeps today's credit). The adapter records the answer on the call (`waits`) because the timeline's tool label keeps field names, never values.
252
256
  */
253
- export function waitsOnHelpers(tool, input) {
254
- if (isWaitTool(tool))
255
- return true;
256
- return tool === "read_agent" && typeof input === "object" && input !== null && input.wait === true;
257
+ export function waitsOnHelpers(tool, input, host) {
258
+ const e = toolEntryOf(host, tool);
259
+ if (e?.class !== "wait")
260
+ return false;
261
+ return e.waitFlag === undefined || (typeof input === "object" && input !== null && input[e.waitFlag] === true);
257
262
  }
258
263
  /**
259
264
  * An Agent or Task launch is not credited at a sweep where a call of the agent it launched is open (`helperOpen`): that call carries
260
265
  * the agent's work and is the suspect. With none of its helper's calls open (between them, or a helper whose hooks never fired) the launch
261
266
  * stays a suspect, so a change found then is never narrowed to someone else alone.
262
267
  */
263
- export function launcherMayCredit(tool, helperOpen) {
264
- return !(isLauncherTool(tool) && helperOpen);
268
+ export function launcherMayCredit(tool, helperOpen, host) {
269
+ return !(isLauncherTool(tool, host) && helperOpen);
265
270
  }
266
271
  /**
267
272
  * A call whose work can go on after its tool_result: a background flag, a shell command that detaches (`&` at a command's end, nohup,
268
273
  * setsid, disown), an osascript or `open` (the app it drives keeps going), or a result saying the host moved it to the background. Such a
269
274
  * call is never closed on transcript evidence. When unsure, it runs on.
270
275
  */
271
- export function runsOnAfterResult(call) {
276
+ export function runsOnAfterResult(call, host) {
272
277
  if (call.background)
273
278
  return true;
274
- if (call.tool !== "Bash")
279
+ if (!isBackgroundableShell(call.tool, host))
275
280
  return false;
276
281
  const cmd = call.command ?? "";
277
282
  if (/(^|[^&|>])&\s*($|[;\n)]|\bdone\b|\bfi\b)/.test(cmd.replace(/&&|\|&|&>|>&\d?|\d>&\d/g, " ")))
@@ -0,0 +1,76 @@
1
+ // `cocheck harness create <key> [--dir <path>]`: copies the kit's starter harness folder to <dir>/<key>/ and fills the key in.
2
+ // Structural rule: it writes only a new folder <dir>/<key>; an existing path of that name is refused, and every check runs before the first write.
3
+ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
4
+ import path from "node:path";
5
+ import { allProfiles } from "../hosts/index.js";
6
+ import { RESERVED_KEYS } from "../hosts/harnesses.js";
7
+ import { KEY, MANIFEST_FILE, validateManifest } from "../hosts/manifest.js";
8
+ const SCAFFOLD = path.resolve(import.meta.dirname, "../../public-kit/harness/scaffold");
9
+ const PLACEHOLDER = "myagent";
10
+ export const CREATE_USAGE = "usage: cocheck harness create <key> [--dir <path>]";
11
+ export function runHarnessCreate(argv, io, opts = {}) {
12
+ const scaffold = opts.scaffold ?? SCAFFOLD;
13
+ const fail = (m) => (io.err(m), 1);
14
+ let key;
15
+ let dir;
16
+ for (let i = 0; i < argv.length; i++) {
17
+ const a = argv[i];
18
+ if (a === "--dir") {
19
+ dir = argv[++i];
20
+ if (dir === undefined)
21
+ return fail("--dir needs a value");
22
+ }
23
+ else if (a.startsWith("--"))
24
+ return fail(`unknown option ${a}`);
25
+ else if (key === undefined)
26
+ key = a;
27
+ else
28
+ return fail(CREATE_USAGE);
29
+ }
30
+ if (key === undefined)
31
+ return fail(CREATE_USAGE);
32
+ if (!KEY.test(key))
33
+ return fail(`"${key}" is not a valid key: lowercase letters, digits and dashes, starting with a letter, at most 32.`);
34
+ if (RESERVED_KEYS.includes(key) || allProfiles().some((p) => p.key === key))
35
+ return fail(`"${key}" is already a host in CoCheck; pick another key.`);
36
+ const parent = path.resolve(io.cwd ?? process.cwd(), dir ?? ".");
37
+ const target = path.join(parent, key);
38
+ if (existsSync(target))
39
+ return fail(`${target} already exists. Nothing was written. Pick another key or --dir.`);
40
+ if (!existsSync(scaffold) || !statSync(scaffold).isDirectory())
41
+ return fail(`The harness starter folder ${scaffold} is missing from this CoCheck install, so nothing was written.`);
42
+ // Read the whole starter and check the result before the first write.
43
+ const files = [];
44
+ const walk = (rel) => {
45
+ for (const e of readdirSync(path.join(scaffold, rel), { withFileTypes: true })) {
46
+ const r = path.join(rel, e.name);
47
+ if (e.isDirectory())
48
+ walk(r);
49
+ else if (e.name !== ".gitkeep")
50
+ files.push({ rel: r, body: readFileSync(path.join(scaffold, r), "utf8").split(PLACEHOLDER).join(key).split(PLACEHOLDER.toUpperCase()).join(key.toUpperCase().replace(/-/g, "_")) });
51
+ }
52
+ };
53
+ walk("");
54
+ const manifest = files.find((f) => f.rel === MANIFEST_FILE);
55
+ if (!manifest)
56
+ return fail(`the starter is missing ${MANIFEST_FILE}. Nothing was written.`);
57
+ try {
58
+ validateManifest(JSON.parse(manifest.body), `${key}/${MANIFEST_FILE}`, { outsider: true });
59
+ }
60
+ catch (error) {
61
+ return fail(`the starter does not validate: ${error instanceof Error ? error.message : String(error)}. Nothing was written.`);
62
+ }
63
+ mkdirSync(path.join(target, "recordings"), { recursive: true });
64
+ for (const f of files) {
65
+ mkdirSync(path.dirname(path.join(target, f.rel)), { recursive: true });
66
+ writeFileSync(path.join(target, f.rel), f.body);
67
+ }
68
+ const q = (p) => (/\s/.test(p) ? JSON.stringify(p) : p);
69
+ io.out(`Created harness "${key}" in ${target}.\nNext:\n` +
70
+ ` 1. cocheck harness record ${key} --manifest ${q(path.join(target, MANIFEST_FILE))} --out ${q(path.join(target, "recordings"))} -- <your harness command>\n` +
71
+ ` 2. Edit ${q(path.join(target, MANIFEST_FILE))} until the recordings read right (README.md there explains each part).\n` +
72
+ ` 3. cocheck harness test --cases <cases folder> --manifest ${q(path.join(target, MANIFEST_FILE))}\n` +
73
+ `To try it: copy the folder to <CoCheck data home>/harnesses/${key}/ (or into the folder $COCHECK_HARNESS_DIR names), then run cocheck status.\n` +
74
+ `To ship it with CoCheck: open a pull request that adds it under harnesses/${key}/ (data only, no code).`);
75
+ return 0;
76
+ }