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
@@ -0,0 +1,372 @@
1
+ // The harness manifest, `cocheck-harness.json` (schema "cocheck-harness/1"): everything CoCheck needs to know about an agent harness that is
2
+ // data (names, paths in the payload, tables, rules), in one JSON file. `compileManifest` (src/hosts/compile.ts) turns it into a HostProfile.
3
+ // A manifest holds no code. Behaviour that is not data is first-party code a manifest opts into by name (`extras`, src/hosts/extras.ts).
4
+ // The full field reference is "Harness manifest (v1)" in docs/hooks.md.
5
+ import { validateInstallBlock } from "./install-block.js";
6
+ import { knownExtra, outsiderSafeExtra } from "./extras.js";
7
+ export const MANIFEST_SCHEMA = "cocheck-harness/1";
8
+ export const MANIFEST_FILE = "cocheck-harness.json";
9
+ const KINDS = { "tool-pre": true, "tool-post": true, "tool-failure": true, stop: true, "subagent-stop": true, prompt: true, "file-edit": true, "shell-pre": true, "shell-post": true, "session-start": true, "session-end": true, other: true };
10
+ const CLASSES = { write: true, edit: true, "notebook-edit": true, patch: true, shell: true, launcher: true, wait: true, read: true, "read-only": true, "never-credited": true };
11
+ const CAPS = { failureEvent: true, argvTag: true, helperSessions: true, launchKey: true, readsForeignHooks: true };
12
+ const PATH = /^[A-Za-z_$][\w$-]*(?:\.[A-Za-z_$][\w$-]*|\[\d+\])*$/;
13
+ export const KEY = /^[a-z][a-z0-9-]{0,31}$/;
14
+ /** Install members that are the manifest's own; the rest of `install` is the JSON install block. */
15
+ export const INSTALL_OWN = ["skillRoot", "hostFlag", "projectDirEnv", "folderFromPayloadCwd", "promptContext", "ownsFile", "inBothAlias", "reusesRecord", "timingLabel", "afterInstall", "checkPayload", "editorExtra", "notes"];
16
+ const TOP = ["schema", "key", "displayName", "fullName", "chip", "testedVersions", "events", "eventFrom", "unverifiedEvents", "fields", "toolInputEncoding", "callId", "extraFields", "failure", "refine", "toolNameStrip", "toolClasses", "narration", "sessionFile", "capabilities", "foreignHookFingerprint", "readsConfigsOf", "argvTag", "sessionEnv", "perAction", "hostOwnedFiles", "hostOwnedWhat", "install", "extras", "shape"];
17
+ /** The longest pattern a manifest may hold, and the most text a compiled pattern is ever run against (see compile.ts). */
18
+ export const PATTERN_MAX = 200;
19
+ export const MATCH_INPUT_MAX = 4096;
20
+ /** A counted repeat `{n,m}` with `m` up to this is a bounded repeat. */
21
+ const BOUNDED_REPEAT_MAX = 4;
22
+ /**
23
+ * Why a manifest pattern is refused, or undefined. A structural rule, not a list: too long, a backreference or lookaround, or a group that is repeated
24
+ * and itself holds a repeat or an alternation (`(a+)+`, `(a|a)*`), which is where a regular expression can take exponential time.
25
+ */
26
+ export function patternProblem(p, trusted = false) {
27
+ if (p.length > PATTERN_MAX)
28
+ return `pattern longer than ${PATTERN_MAX} characters`;
29
+ const stack = [];
30
+ let unbounded = 0;
31
+ let topAlt = false;
32
+ for (let i = 0; i < p.length; i++) {
33
+ const c = p[i];
34
+ if (c === "\\") {
35
+ if (/[1-9k]/.test(p[i + 1] ?? ""))
36
+ return "backreference not allowed";
37
+ i++;
38
+ }
39
+ else if (c === "[") {
40
+ for (i++; i < p.length && p[i] !== "]"; i++)
41
+ if (p[i] === "\\")
42
+ i++;
43
+ }
44
+ else if (c === "(") {
45
+ if (p[i + 1] === "?" && p[i + 2] !== ":")
46
+ return "lookaround and named groups not allowed";
47
+ stack.push({ repeats: false, alt: false });
48
+ }
49
+ else if (c === "|") {
50
+ if (stack.length > 0)
51
+ stack[stack.length - 1].alt = true;
52
+ else
53
+ topAlt = true;
54
+ }
55
+ else if (c === ")") {
56
+ const g = stack.pop();
57
+ const next = p[i + 1];
58
+ const repeated = next === "*" || next === "+" || next === "{";
59
+ if (g !== undefined && repeated && (g.repeats || g.alt))
60
+ return "nested repetition not allowed";
61
+ if (g !== undefined && stack.length > 0 && (repeated || next === "?" || g.repeats))
62
+ stack[stack.length - 1].repeats = true;
63
+ }
64
+ else if ((c === "*" || c === "+" || c === "?" || c === "{") && stack.length > 0) {
65
+ stack[stack.length - 1].repeats = true;
66
+ }
67
+ if (c === "*" || c === "+")
68
+ unbounded++;
69
+ else if (c === "{") {
70
+ // A counted repeat is unbounded for this rule when it has no upper bound or one above BOUNDED_REPEAT_MAX.
71
+ const q = /^\{(\d+)(?:(,)(\d*))?\}/.exec(p.slice(i));
72
+ if (q !== null && (Number(q[3] === undefined || q[3] === "" ? (q[2] === undefined ? q[1] : Infinity) : q[3]) > BOUNDED_REPEAT_MAX))
73
+ unbounded++;
74
+ }
75
+ }
76
+ // The cost claim: run on at most MATCH_INPUT_MAX characters, a pattern with this many unbounded repeats takes about n^2 steps at worst (n starting
77
+ // places times one scan; a pattern that starts with ^ has one starting place, so a second scan costs n^2 as well). More repeats nest and cost n^3 and up.
78
+ const limit = p.startsWith("^") && !topAlt ? 2 : 1;
79
+ // A manifest that ships with CoCheck is reviewed code and is exempt from this count (its patterns run on whole inputs, as they always did).
80
+ if (!trusted && unbounded > limit)
81
+ return `too many unbounded repeats (at most ${limit} here; ${limit === 1 ? "start the pattern with ^ for 2" : "a counted repeat with an upper bound of 4 or less does not count"})`;
82
+ return undefined;
83
+ }
84
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
85
+ /** Checks a parsed manifest. `label` names the file in every error (`myagent/cocheck-harness.json`). Throws an Error naming the field. */
86
+ export function validateManifest(v, label, opts = {}) {
87
+ const bad = (field, what) => {
88
+ throw new Error(`${label}: ${field}: ${what}`);
89
+ };
90
+ const obj = (x, field) => (isObject(x) ? x : bad(field, "expected an object"));
91
+ const str = (x, field) => (typeof x === "string" && x !== "" ? x : bad(field, "expected a non-empty string"));
92
+ const strs = (x, field) => (Array.isArray(x) && x.every((s) => typeof s === "string") ? x : bad(field, "expected a list of strings"));
93
+ const path = (x, field) => {
94
+ const s = str(x, field);
95
+ return PATH.test(s) ? s : bad(field, `not a payload path: ${JSON.stringify(s)} (write a.b or a[0].b)`);
96
+ };
97
+ const regex = (x, field) => {
98
+ const s = str(x, field);
99
+ try {
100
+ new RegExp(s);
101
+ }
102
+ catch {
103
+ bad(field, `not a regular expression: ${JSON.stringify(s)}`);
104
+ }
105
+ const why = patternProblem(s, opts.builtIn === true);
106
+ if (why !== undefined)
107
+ bad(field, `${why}: ${JSON.stringify(s)}`);
108
+ return s;
109
+ };
110
+ const kind = (x, field) => (typeof x === "string" && Object.hasOwn(KINDS, x) ? x : bad(field, `unknown kind ${JSON.stringify(x)}`));
111
+ const only = (o, allowed, field) => {
112
+ for (const k of Object.keys(o))
113
+ if (!allowed.includes(k))
114
+ bad(field === "" ? k : `${field}.${k}`, "unknown field");
115
+ };
116
+ const bool = (x, field) => (typeof x === "boolean" ? x : bad(field, "expected true or false"));
117
+ const m = obj(v, "(manifest)");
118
+ only(m, TOP, "");
119
+ if (m.schema !== MANIFEST_SCHEMA)
120
+ bad("schema", `expected ${JSON.stringify(MANIFEST_SCHEMA)}, got ${JSON.stringify(m.schema)}`);
121
+ const key = str(m.key, "key");
122
+ if (!KEY.test(key))
123
+ bad("key", `${JSON.stringify(key)} is not a lowercase key (letters, digits and dashes, at most 32)`);
124
+ str(m.displayName, "displayName");
125
+ if (m.fullName !== undefined)
126
+ str(m.fullName, "fullName");
127
+ str(m.chip, "chip");
128
+ if (m.testedVersions !== undefined)
129
+ strs(m.testedVersions, "testedVersions");
130
+ const events = obj(m.events, "events");
131
+ if (Object.keys(events).length === 0)
132
+ bad("events", "expected at least one event");
133
+ for (const [name, k] of Object.entries(events))
134
+ kind(k, `events.${name}`);
135
+ const from = obj(m.eventFrom, "eventFrom");
136
+ if ("payload" in from)
137
+ path(from.payload, "eventFrom.payload");
138
+ else if (from.arg !== "--event")
139
+ bad("eventFrom", 'expected {"payload": <path>} or {"arg": "--event"}');
140
+ if (m.unverifiedEvents !== undefined)
141
+ strs(m.unverifiedEvents, "unverifiedEvents");
142
+ const fields = obj(m.fields, "fields");
143
+ only(fields, ["session", "eventName", "cwd", "toolName", "toolInput", "toolResponse", "agentId", "agentType", "transcriptPath", "lastAssistantMessage", "prompt", "parentSession", "callReason"], "fields");
144
+ path(fields.session, "fields.session");
145
+ for (const [k, x] of Object.entries(fields))
146
+ if (k !== "session" && k !== "callReason")
147
+ path(x, `fields.${k}`);
148
+ if (fields.callReason !== undefined)
149
+ str(fields.callReason, "fields.callReason");
150
+ if (m.toolInputEncoding !== undefined && m.toolInputEncoding !== "object" && m.toolInputEncoding !== "json-text")
151
+ bad("toolInputEncoding", 'expected "object" or "json-text"');
152
+ if (m.callId !== undefined) {
153
+ const c = obj(m.callId, "callId");
154
+ only(c, ["payload", "synthesized"], "callId");
155
+ if (c.payload !== undefined)
156
+ path(c.payload, "callId.payload");
157
+ if (c.synthesized !== undefined && c.synthesized !== true)
158
+ bad("callId.synthesized", "expected true");
159
+ if (c.payload === undefined && c.synthesized === undefined)
160
+ bad("callId", 'expected {"payload": <path>}, {"synthesized": true} or both (the host\'s id when it sends one, else made up)');
161
+ }
162
+ if (m.extraFields !== undefined) {
163
+ const e = obj(m.extraFields, "extraFields");
164
+ only(e, ["turnId", "permissionMode", "model", "stopHookActive"], "extraFields");
165
+ for (const [k, x] of Object.entries(e))
166
+ path(x, `extraFields.${k}`);
167
+ }
168
+ if (m.failure !== undefined) {
169
+ const f = obj(m.failure, "failure");
170
+ only(f, ["tool-failure", "tool-post"], "failure");
171
+ for (const [k, rule] of Object.entries(f)) {
172
+ const r = obj(rule, `failure.${k}`);
173
+ only(r, ["flags", "text", "nonEmpty", "flaggedText", "interrupt", "exitCode", "inferred"], `failure.${k}`);
174
+ for (const list of ["flags", "text"])
175
+ if (r[list] !== undefined)
176
+ (Array.isArray(r[list]) ? r[list] : bad(`failure.${k}.${list}`, "expected a list of paths")).forEach((p, i) => path(p, `failure.${k}.${list}[${i}]`));
177
+ if (r.flaggedText !== undefined) {
178
+ (Array.isArray(r.flaggedText) ? r.flaggedText : bad(`failure.${k}.flaggedText`, "expected a list")).forEach((e, i) => {
179
+ if (typeof e === "string")
180
+ path(e, `failure.${k}.flaggedText[${i}]`);
181
+ else {
182
+ const o = obj(e, `failure.${k}.flaggedText[${i}]`);
183
+ only(o, ["path", "blocks"], `failure.${k}.flaggedText[${i}]`);
184
+ path(o.path, `failure.${k}.flaggedText[${i}].path`);
185
+ if (o.blocks !== undefined && o.blocks !== true)
186
+ bad(`failure.${k}.flaggedText[${i}].blocks`, "expected true");
187
+ }
188
+ });
189
+ }
190
+ if (r.interrupt !== undefined)
191
+ path(r.interrupt, `failure.${k}.interrupt`);
192
+ if (r.exitCode !== undefined) {
193
+ const x = obj(r.exitCode, `failure.${k}.exitCode`);
194
+ path(x.from, `failure.${k}.exitCode.from`);
195
+ regex(x.pattern, `failure.${k}.exitCode.pattern`);
196
+ }
197
+ if (r.inferred !== undefined && r.inferred !== true)
198
+ bad(`failure.${k}.inferred`, "expected true");
199
+ if (r.nonEmpty !== undefined) {
200
+ if (r.nonEmpty !== true)
201
+ bad(`failure.${k}.nonEmpty`, "expected true");
202
+ if (k !== "tool-post")
203
+ bad(`failure.${k}.nonEmpty`, "only a tool-post rule decides whether a call failed (a tool-failure event is a failure already)");
204
+ if (!Array.isArray(r.text) || r.text.length === 0)
205
+ bad(`failure.${k}.nonEmpty`, "needs text: the paths whose words mean the call failed");
206
+ }
207
+ }
208
+ }
209
+ if (m.refine !== undefined) {
210
+ (Array.isArray(m.refine) ? m.refine : bad("refine", "expected a list")).forEach((rule, i) => {
211
+ const r = obj(rule, `refine[${i}]`);
212
+ only(r, ["kinds", "becomes", "whenPresent", "whenMatches"], `refine[${i}]`);
213
+ (Array.isArray(r.kinds) && r.kinds.length > 0 ? r.kinds : bad(`refine[${i}].kinds`, "expected a list of kinds")).forEach((k, j) => kind(k, `refine[${i}].kinds[${j}]`));
214
+ kind(r.becomes, `refine[${i}].becomes`);
215
+ if (r.whenPresent === undefined && r.whenMatches === undefined)
216
+ bad(`refine[${i}]`, "needs whenPresent or whenMatches");
217
+ if (r.whenPresent !== undefined)
218
+ path(r.whenPresent, `refine[${i}].whenPresent`);
219
+ if (r.whenMatches !== undefined) {
220
+ const w = obj(r.whenMatches, `refine[${i}].whenMatches`);
221
+ path(w.path, `refine[${i}].whenMatches.path`);
222
+ regex(w.pattern, `refine[${i}].whenMatches.pattern`);
223
+ }
224
+ });
225
+ }
226
+ if (m.toolNameStrip !== undefined)
227
+ regex(obj(m.toolNameStrip, "toolNameStrip").prefix, "toolNameStrip.prefix");
228
+ const classes = obj(m.toolClasses, "toolClasses");
229
+ for (const [tool, entry] of Object.entries(classes)) {
230
+ const e = obj(entry, `toolClasses.${tool}`);
231
+ only(e, ["class", "dialect", "waitFlag", "anyCase", "pathFields", "pathChecked", "fileInput", "backgroundFlag", "resumesHelper", "backgroundable"], `toolClasses.${tool}`);
232
+ if (typeof e.class !== "string" || !Object.hasOwn(CLASSES, e.class))
233
+ bad(`toolClasses.${tool}.class`, `unknown class ${JSON.stringify(e.class)}`);
234
+ if (e.dialect !== undefined && e.dialect !== "bash" && e.dialect !== "powershell")
235
+ bad(`toolClasses.${tool}.dialect`, 'expected "bash" or "powershell"');
236
+ if (e.waitFlag !== undefined)
237
+ str(e.waitFlag, `toolClasses.${tool}.waitFlag`);
238
+ if (e.pathFields !== undefined)
239
+ strs(e.pathFields, `toolClasses.${tool}.pathFields`);
240
+ for (const flag of ["anyCase", "pathChecked", "fileInput", "backgroundFlag", "resumesHelper", "backgroundable"])
241
+ if (e[flag] !== undefined && e[flag] !== true)
242
+ bad(`toolClasses.${tool}.${flag}`, "expected true");
243
+ }
244
+ if (m.narration !== undefined) {
245
+ const n = obj(m.narration, "narration");
246
+ only(n, ["sources", "closingWaitMs"], "narration");
247
+ if (n.sources !== undefined) {
248
+ (Array.isArray(n.sources) ? n.sources : bad("narration.sources", "expected a list")).forEach((s, i) => {
249
+ const o = obj(s, `narration.sources[${i}]`);
250
+ only(o, ["kind", "readableAt", "reason"], `narration.sources[${i}]`);
251
+ if (o.kind !== "text-before-call" && o.kind !== "commentary-before-call" && o.kind !== "closing-message")
252
+ bad(`narration.sources[${i}].kind`, `unknown source ${JSON.stringify(o.kind)}`);
253
+ if (o.readableAt !== "pre" && o.readableAt !== "post")
254
+ bad(`narration.sources[${i}].readableAt`, 'expected "pre" or "post"');
255
+ if (o.reason !== undefined && o.reason !== true)
256
+ bad(`narration.sources[${i}].reason`, "expected true");
257
+ });
258
+ }
259
+ if (n.closingWaitMs !== undefined && (typeof n.closingWaitMs !== "number" || !(n.closingWaitMs >= 0)))
260
+ bad("narration.closingWaitMs", "expected a number of ms");
261
+ }
262
+ if (m.sessionFile !== undefined) {
263
+ const s = obj(m.sessionFile, "sessionFile");
264
+ only(s, ["bySessionId", "defaultRoot", "file"], "sessionFile");
265
+ if (s.bySessionId !== undefined)
266
+ bool(s.bySessionId, "sessionFile.bySessionId");
267
+ if (s.defaultRoot !== undefined)
268
+ str(s.defaultRoot, "sessionFile.defaultRoot");
269
+ if (s.file !== undefined)
270
+ str(s.file, "sessionFile.file");
271
+ if (s.bySessionId === true && s.file === undefined)
272
+ bad("sessionFile.file", "needed when bySessionId is true");
273
+ }
274
+ if (m.capabilities !== undefined) {
275
+ const c = obj(m.capabilities, "capabilities");
276
+ for (const [k, x] of Object.entries(c)) {
277
+ if (!Object.hasOwn(CAPS, k))
278
+ bad(`capabilities.${k}`, "unknown capability");
279
+ bool(x, `capabilities.${k}`);
280
+ }
281
+ }
282
+ if (m.foreignHookFingerprint !== undefined) {
283
+ const f = obj(m.foreignHookFingerprint, "foreignHookFingerprint");
284
+ only(f, ["present", "strings", "absent"], "foreignHookFingerprint");
285
+ for (const k of ["present", "strings", "absent"])
286
+ strs(f[k], `foreignHookFingerprint.${k}`);
287
+ }
288
+ if (m.readsConfigsOf !== undefined)
289
+ strs(m.readsConfigsOf, "readsConfigsOf");
290
+ if (m.argvTag !== undefined) {
291
+ const a = obj(m.argvTag, "argvTag");
292
+ only(a, ["tool", "preOutput", "envFileVar", "shellEnv", "sessionStartEvent"], "argvTag");
293
+ for (const k of ["tool", "envFileVar", "shellEnv", "sessionStartEvent"])
294
+ str(a[k], `argvTag.${k}`);
295
+ if (a.preOutput === undefined)
296
+ bad("argvTag.preOutput", "missing");
297
+ }
298
+ if (m.sessionEnv !== undefined)
299
+ str(m.sessionEnv, "sessionEnv");
300
+ if (m.perAction !== undefined) {
301
+ const p = obj(m.perAction, "perAction");
302
+ only(p, ["fileEditTool", "shellTool", "fields"], "perAction");
303
+ str(p.fileEditTool, "perAction.fileEditTool");
304
+ str(p.shellTool, "perAction.shellTool");
305
+ const f = obj(p.fields, "perAction.fields");
306
+ only(f, ["editPath", "editList", "editContent", "command", "exitCode", "output"], "perAction.fields");
307
+ str(f.editPath, "perAction.fields.editPath");
308
+ str(f.command, "perAction.fields.command");
309
+ for (const k of ["editList", "editContent", "exitCode", "output"])
310
+ if (f[k] !== undefined)
311
+ str(f[k], `perAction.fields.${k}`);
312
+ for (const tool of [p.fileEditTool, p.shellTool])
313
+ if (!Object.hasOwn(classes, tool))
314
+ bad("perAction", `the tool ${JSON.stringify(tool)} is not in toolClasses`);
315
+ }
316
+ if (m.hostOwnedFiles !== undefined)
317
+ strs(m.hostOwnedFiles, "hostOwnedFiles");
318
+ if (m.hostOwnedWhat !== undefined)
319
+ str(m.hostOwnedWhat, "hostOwnedWhat");
320
+ if (m.install !== undefined) {
321
+ const inst = obj(m.install, "install");
322
+ str(inst.skillRoot, "install.skillRoot");
323
+ str(inst.hostFlag, "install.hostFlag");
324
+ for (const k of ["projectDirEnv", "timingLabel", "afterInstall", "editorExtra", "notes"])
325
+ if (inst[k] !== undefined)
326
+ str(inst[k], `install.${k}`);
327
+ for (const k of ["folderFromPayloadCwd"])
328
+ if (inst[k] !== undefined)
329
+ bool(inst[k], `install.${k}`);
330
+ if (inst.promptContext !== undefined && inst.promptContext !== false)
331
+ bad("install.promptContext", "expected false");
332
+ for (const k of ["ownsFile", "inBothAlias", "reusesRecord"])
333
+ if (inst[k] !== undefined && inst[k] !== true)
334
+ bad(`install.${k}`, "expected true");
335
+ const check = obj(inst.checkPayload, "install.checkPayload");
336
+ obj(check.payload, "install.checkPayload.payload");
337
+ if (check.event !== undefined)
338
+ str(check.event, "install.checkPayload.event");
339
+ if (inst.editorExtra !== undefined) {
340
+ if (!knownExtra(inst.editorExtra))
341
+ bad("install.editorExtra", `unknown extra ${JSON.stringify(inst.editorExtra)}`);
342
+ if (opts.outsider === true && !outsiderSafeExtra(inst.editorExtra))
343
+ bad("install.editorExtra", `the extra ${JSON.stringify(inst.editorExtra)} is first-party code for built-in manifests; a manifest in your own folder cannot name it`);
344
+ strs(inst.events, "install.events");
345
+ }
346
+ else {
347
+ const block = Object.fromEntries(Object.entries(inst).filter(([k]) => !INSTALL_OWN.includes(k)));
348
+ try {
349
+ validateInstallBlock(block, "install");
350
+ }
351
+ catch (error) {
352
+ throw new Error(`${label}: ${error instanceof Error ? error.message : String(error)}`);
353
+ }
354
+ }
355
+ }
356
+ if (m.extras !== undefined) {
357
+ strs(m.extras, "extras").forEach((name, i) => {
358
+ if (!knownExtra(name))
359
+ bad(`extras[${i}]`, `unknown extra ${JSON.stringify(name)} (extras are first-party code; see docs/hooks.md)`);
360
+ if (opts.outsider === true && !outsiderSafeExtra(name))
361
+ bad(`extras[${i}]`, `the extra ${JSON.stringify(name)} is first-party code for built-in manifests; a manifest in your own folder cannot name it`);
362
+ });
363
+ }
364
+ if (m.shape !== undefined)
365
+ for (const [k, x] of Object.entries(obj(m.shape, "shape")))
366
+ strs(x, `shape.${k}`);
367
+ // A per-action kind needs perAction to read it.
368
+ const perKinds = Object.entries(events).filter(([, k]) => k === "file-edit" || k === "shell-pre" || k === "shell-post");
369
+ if (perKinds.length > 0 && m.perAction === undefined)
370
+ bad(`events.${perKinds[0][0]}`, `kind ${JSON.stringify(perKinds[0][1])} needs "perAction"`);
371
+ return m;
372
+ }
@@ -1,3 +1,13 @@
1
+ // What Claude Code and Codex share and a new host need not: their payload keys for a failed call and for the fields CoCheck keeps but does not act on.
2
+ // Moved out of normalize.ts so that file names no payload key of any host.
3
+ import { createHash } from "node:crypto";
4
+ /** True when the payload is an object that has every `present` key, carries every `strings` key as text, and has none of the `absent` keys. */
5
+ export function matchesFingerprint(fp, payload) {
6
+ if (payload === null || typeof payload !== "object")
7
+ return false;
8
+ const p = payload;
9
+ return fp.present.every((k) => p[k] !== undefined) && fp.strings.every((k) => typeof p[k] === "string") && fp.absent.every((k) => p[k] === undefined);
10
+ }
1
11
  /** The failure a post-like event reports in the Claude/Codex payload shape: a failure event, or a post whose `tool_response` carries `is_error` / `isError`. */
2
12
  export function claudeShapeFailure(kind, p) {
3
13
  const resp = p.tool_response;
@@ -29,3 +39,14 @@ export function claudeShapeExtra(p) {
29
39
  extra.stopHookActive = p.stop_hook_active;
30
40
  return extra;
31
41
  }
42
+ /** The arguments with keys sorted at every level, so equal arguments make equal text whatever order a host listed them in. */
43
+ function stable(value) {
44
+ if (Array.isArray(value))
45
+ return value.map(stable);
46
+ if (value !== null && typeof value === "object") {
47
+ return Object.fromEntries(Object.keys(value).sort().map((k) => [k, stable(value[k])]));
48
+ }
49
+ return value;
50
+ }
51
+ /** The text two calls with equal arguments share: how a host that sends no call id is matched to its own session file's request. */
52
+ export const argsKey = (toolInput) => createHash("sha256").update(JSON.stringify(stable(toolInput ?? null))).digest("hex").slice(0, 16);
@@ -0,0 +1,6 @@
1
+ // What each tool a host reports is, to CoCheck: a class, not a name. Every host declares its own table (`HostProfile.toolClasses`), so one
2
+ // host's `edit` and another's `Edit` never share a meaning. The core asks the registry (`toolEntryOf`, src/hosts/index.ts) and reads the class.
3
+ /** One class and the same extras for several names. */
4
+ export function toolGroup(cls, names, extra = {}) {
5
+ return Object.fromEntries(names.map((n) => [n, { class: cls, ...extra }]));
6
+ }
@@ -23,4 +23,5 @@ export const SHARED_FIELDS = {
23
23
  transcriptPath: "transcript_path",
24
24
  lastAssistantMessage: "last_assistant_message",
25
25
  prompt: "prompt",
26
+ callReason: "description",
26
27
  };