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.
- package/README.md +17 -3
- package/dist/agent-transcripts.js +15 -12
- package/dist/attribution/evidence.js +2 -1
- package/dist/attribution/reconstruct.js +19 -0
- package/dist/attribution/tag.js +3 -3
- package/dist/build-info.json +1 -1
- package/dist/cli.js +31 -11
- package/dist/connector/export-view.js +1 -1
- package/dist/coverage.js +5 -3
- package/dist/credit-guard.js +59 -54
- package/dist/harness-cmd/create.js +76 -0
- package/dist/harness-cmd/index.js +19 -0
- package/dist/harness-cmd/record.js +327 -0
- package/dist/harness-cmd/scrub.js +25 -0
- package/dist/harness-cmd/test.js +318 -0
- package/dist/harnesses/README.md +5 -0
- package/dist/harnesses/claude/cocheck-harness.json +344 -0
- package/dist/harnesses/codex/cocheck-harness.json +212 -0
- package/dist/harnesses/copilot/cocheck-harness.json +296 -0
- package/dist/{copilot-helpers.js → helper-linker.js} +43 -32
- package/dist/hook-adapter.js +287 -63
- package/dist/hook-cli.js +73 -36
- package/dist/hook-journal.js +40 -12
- package/dist/hosts/claude.js +23 -159
- package/dist/hosts/codex.js +41 -81
- package/dist/hosts/compile.js +275 -0
- package/dist/hosts/copilot.js +7 -162
- package/dist/hosts/extras.js +55 -0
- package/dist/hosts/harnesses.js +66 -0
- package/dist/hosts/index.js +176 -8
- package/dist/hosts/install-block.js +332 -0
- package/dist/hosts/manifest.js +372 -0
- package/dist/hosts/shared.js +21 -0
- package/dist/hosts/tool-classes.js +6 -0
- package/dist/hosts/types.js +1 -0
- package/dist/install.js +69 -22
- package/dist/ledger.js +11 -0
- package/dist/normalize.js +33 -9
- package/dist/open-pick.js +5 -3
- package/dist/patch-secrets.js +11 -11
- package/dist/review-server.js +2 -2
- package/dist/timeline/attribution.js +2 -2
- package/dist/timeline/describe.js +20 -17
- package/dist/timeline/load.js +2 -2
- package/dist/timeline/rail/assets/review.js +1 -1
- package/dist/timeline/rail/model.js +8 -8
- package/dist/timeline/read-signal.js +4 -4
- package/dist/timeline/render/view-v1.js +2 -13
- package/dist/timeline/runs.js +9 -9
- package/dist/timeline/timeline.js +8 -8
- package/dist/timeline/write-signal.js +4 -3
- package/package.json +2 -2
- package/public-kit/harness/GUIDE.md +81 -0
- package/public-kit/harness/README.md +10 -0
- package/public-kit/harness/cases/claude/shell-writes-file.json +120 -0
- package/public-kit/harness/cases/codex/apply-patch-writes-files.json +177 -0
- package/public-kit/harness/cases/codex/helper-writes-file.json +160 -0
- package/public-kit/harness/cases/codex/shell-writes-and-fails.json +110 -0
- package/public-kit/harness/cases/copilot/camel-case-patch-and-failure.json +126 -0
- package/public-kit/harness/cases/copilot/helper-writes-file.json +209 -0
- package/public-kit/harness/cases/copilot/vscode-helper-writes-file.json +236 -0
- package/public-kit/harness/examples/toyagent/cases/write-notes.json +142 -0
- package/public-kit/harness/examples/toyagent/cocheck-harness.json +47 -0
- package/public-kit/harness/examples/toyagent/recordings/payloads.jsonl +8 -0
- package/public-kit/harness/harnesses/antigravity/README.md +32 -0
- package/public-kit/harness/harnesses/antigravity/cases/failed-edit.json +99 -0
- package/public-kit/harness/harnesses/antigravity/cases/helper-writes-file.json +270 -0
- package/public-kit/harness/harnesses/antigravity/cases/shell-ok-fail-and-denied.json +211 -0
- package/public-kit/harness/harnesses/antigravity/cases/write-then-edit.json +191 -0
- package/public-kit/harness/harnesses/antigravity/cocheck-harness.json +62 -0
- package/public-kit/harness/harnesses/antigravity/recordings/payloads.jsonl +63 -0
- package/public-kit/harness/harnesses/cursor/README.md +40 -0
- package/public-kit/harness/harnesses/cursor/cases/editor-write-edit-shell-helper.json +359 -0
- package/public-kit/harness/harnesses/cursor/cases/read-then-write-one-call-id.json +159 -0
- package/public-kit/harness/harnesses/cursor/cocheck-harness.json +67 -0
- package/public-kit/harness/harnesses/cursor/recordings/payloads.jsonl +28 -0
- package/public-kit/harness/scaffold/README.md +42 -0
- package/public-kit/harness/scaffold/cocheck-harness.json +72 -0
- package/public-kit/harness/scaffold/recordings/.gitkeep +0 -0
- package/public-kit/harness/spec/v1.md +286 -0
- package/scripts/hook-launch.sh +1 -1
package/dist/hosts/copilot.js
CHANGED
|
@@ -1,35 +1,15 @@
|
|
|
1
|
-
// GitHub Copilot
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
// arguments, and a commentary `assistant.message` holds the words before the call; one CoCheck-owned file in `$COPILOT_HOME/hooks/`.
|
|
5
|
-
import { createHash } from "node:crypto";
|
|
1
|
+
// GitHub Copilot's first-party code that is not data: the reader of a session's events.jsonl (the words before a call, the closing message, where the file is).
|
|
2
|
+
// The rest of the host is the manifest, harnesses/copilot/cocheck-harness.json. Facts (platforms/copilot-cli/, platforms/copilot-vscode/): the hook stdin
|
|
3
|
+
// carries no call id, but the session's events.jsonl lists each tool request with its id, name and arguments, and a commentary `assistant.message` holds the words before the call.
|
|
6
4
|
import { homedir } from "node:os";
|
|
7
5
|
import path from "node:path";
|
|
8
6
|
import { CLOSING_MAX, NARRATION_MAX, cut, remember } from "../narration.js";
|
|
9
|
-
import {
|
|
10
|
-
|
|
11
|
-
import { SHARED_FIELDS } from "./types.js";
|
|
7
|
+
import { argsKey } from "./shared.js";
|
|
8
|
+
export { argsKey };
|
|
12
9
|
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
13
10
|
const MESSAGE_LINE = /"type"\s*:\s*"(?:assistant|user)\.message"/;
|
|
14
|
-
/**
|
|
15
|
-
* A prompt that is the host's own system notice, not the person's words ("Agent x has finished processing and is now idle").
|
|
16
|
-
* Bound (a heuristic): the whole trimmed prompt is exactly one `<system_notification>...</system_notification>` element. The match is on the
|
|
17
|
-
* wrapper only, never on the English inside. Anything else, including a prompt that quotes or contains such text, is a user prompt.
|
|
18
|
-
*/
|
|
19
|
-
const SYSTEM_NOTIFICATION = /^<system_notification>(?:(?!<\/?system_notification>)[\s\S])*<\/system_notification>$/;
|
|
20
|
-
const isSystemNotification = (prompt) => typeof prompt === "string" && SYSTEM_NOTIFICATION.test(prompt.trim());
|
|
21
|
-
/** The arguments with keys sorted at every level, so equal arguments make equal text whatever order a host listed them in. */
|
|
22
|
-
function stable(value) {
|
|
23
|
-
if (Array.isArray(value))
|
|
24
|
-
return value.map(stable);
|
|
25
|
-
if (value !== null && typeof value === "object") {
|
|
26
|
-
return Object.fromEntries(Object.keys(value).sort().map((k) => [k, stable(value[k])]));
|
|
27
|
-
}
|
|
28
|
-
return value;
|
|
29
|
-
}
|
|
30
|
-
const argsKey = (toolInput) => createHash("sha256").update(JSON.stringify(stable(toolInput ?? null))).digest("hex").slice(0, 16);
|
|
31
11
|
/** One line of a session's events.jsonl. Only assistant and user messages are parsed. */
|
|
32
|
-
function copilotLine(cur, line) {
|
|
12
|
+
export function copilotLine(cur, line) {
|
|
33
13
|
if (!MESSAGE_LINE.test(line))
|
|
34
14
|
return;
|
|
35
15
|
let d;
|
|
@@ -90,7 +70,7 @@ function parseArgs(value) {
|
|
|
90
70
|
}
|
|
91
71
|
}
|
|
92
72
|
/** `<root>/<session>/events.jsonl`; `root` defaults to `$COPILOT_HOME/session-state`. Only a full uuid names a session folder. */
|
|
93
|
-
function locateEvents(session, _now, root) {
|
|
73
|
+
export function locateEvents(session, _now, root) {
|
|
94
74
|
if (!UUID.test(session))
|
|
95
75
|
return undefined;
|
|
96
76
|
if (root === undefined && !process.env.COPILOT_HOME && process.env.NODE_TEST_CONTEXT) {
|
|
@@ -99,138 +79,3 @@ function locateEvents(session, _now, root) {
|
|
|
99
79
|
const base = root ?? path.join(process.env.COPILOT_HOME || path.join(homedir(), ".copilot"), "session-state");
|
|
100
80
|
return path.join(base, session, "events.jsonl");
|
|
101
81
|
}
|
|
102
|
-
/** `<shellId: N completed with exit code K>`, the only place a failed shell command shows (it arrives as postToolUse success). The last marker wins. */
|
|
103
|
-
const SHELL_EXIT = /<shellId:\s*[^>]*?completed with exit code (-?\d+)>/g;
|
|
104
|
-
/** The failure a postToolUse reports through its text: a shell exit code other than 0. No marker (or a marker of 0) is not a failure read; a missing marker is unknown, never success. */
|
|
105
|
-
function shellFailure(p) {
|
|
106
|
-
const result = p.toolResult;
|
|
107
|
-
const text = result !== null && typeof result === "object" && typeof result.textResultForLlm === "string" ? result.textResultForLlm : "";
|
|
108
|
-
const codes = [...text.matchAll(SHELL_EXIT)];
|
|
109
|
-
const code = codes.length === 0 ? undefined : Number(codes[codes.length - 1][1]);
|
|
110
|
-
return code === undefined || code === 0 ? undefined : { raw: text, interrupted: false };
|
|
111
|
-
}
|
|
112
|
-
/**
|
|
113
|
-
* True when a hook run carries a Copilot payload under a registration meant for another host: Copilot loads a repo's
|
|
114
|
-
* `.claude/settings.json` hooks too (platforms/discrepancies.json copilot-reads-claude-repo-settings), and sends them its own
|
|
115
|
-
* snake_case payload (an ISO `timestamp`, never Claude Code's `permission_mode` or `tool_use_id`, nor Codex's `turn_id`). Such a run would
|
|
116
|
-
* record each Copilot call a second time under another host, so the hook records nothing for it; the copilot entry records.
|
|
117
|
-
* The payload's shape alone decides. The environment never does: Copilot exports its variables to every child, so a real
|
|
118
|
-
* Claude Code or Codex run started from a Copilot-launched shell carries them too.
|
|
119
|
-
*/
|
|
120
|
-
export function copilotRunsOtherHostsHook(payload) {
|
|
121
|
-
if (payload === null || typeof payload !== "object")
|
|
122
|
-
return false;
|
|
123
|
-
const p = payload;
|
|
124
|
-
return p.timestamp !== undefined && typeof p.hook_event_name === "string" && p.permission_mode === undefined && p.tool_use_id === undefined && p.turn_id === undefined;
|
|
125
|
-
}
|
|
126
|
-
const copilotEvents = ["userPromptSubmitted", "preToolUse", "postToolUse", "postToolUseFailure", "agentStop", "subagentStop"];
|
|
127
|
-
/** preToolUse is the one event where a non-zero exit blocks the person's tool call (recorded in capabilities.json), so its entry always exits 0. */
|
|
128
|
-
const failOpen = (event) => (event === "preToolUse" ? " || true" : "");
|
|
129
|
-
function parse(text) {
|
|
130
|
-
try {
|
|
131
|
-
const v = JSON.parse(text);
|
|
132
|
-
return v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined;
|
|
133
|
-
}
|
|
134
|
-
catch {
|
|
135
|
-
return undefined;
|
|
136
|
-
}
|
|
137
|
-
}
|
|
138
|
-
// Windows entries are in `powershell`, macOS entries in `bash`; either field counts, so an uninstall finds both shapes.
|
|
139
|
-
const entryIsOurs = (e, plat) => [e?.bash, e?.powershell].some((c) => typeof c === "string" && (plat.hookCommand.isMarked(c) || platform().hookCommand.isMarked(c)));
|
|
140
|
-
const eventsWithOurs = (text, plat) => {
|
|
141
|
-
const hooks = parse(text)?.hooks;
|
|
142
|
-
if (hooks === undefined || hooks === null || typeof hooks !== "object")
|
|
143
|
-
return [];
|
|
144
|
-
return Object.entries(hooks).filter(([, list]) => Array.isArray(list) && list.some((e) => entryIsOurs(e, plat))).map(([event]) => event);
|
|
145
|
-
};
|
|
146
|
-
export const copilot = {
|
|
147
|
-
key: "copilot",
|
|
148
|
-
displayName: "Copilot",
|
|
149
|
-
chip: "P",
|
|
150
|
-
testedVersions: ["1.0.93", "1.0.98", "1.140.0"],
|
|
151
|
-
eventFromArg: true,
|
|
152
|
-
eventKinds: {
|
|
153
|
-
userPromptSubmitted: "prompt",
|
|
154
|
-
// Seen in the recording; nothing to record from them.
|
|
155
|
-
sessionStart: "other",
|
|
156
|
-
sessionEnd: "other",
|
|
157
|
-
preToolUse: "tool-pre",
|
|
158
|
-
postToolUse: "tool-post",
|
|
159
|
-
postToolUseFailure: "tool-failure",
|
|
160
|
-
agentStop: "stop",
|
|
161
|
-
// A helper's finish (1.0.98 and 1.140.0 both send it, with agentId and agentType, in the main session's id). subagentStart carries
|
|
162
|
-
// nothing the helper's first call does not (VS Code sends it no id at all), so it is seen and not installed.
|
|
163
|
-
subagentStart: "other",
|
|
164
|
-
subagentStop: "subagent-stop",
|
|
165
|
-
userPromptTransformed: "other",
|
|
166
|
-
permissionRequest: "other",
|
|
167
|
-
notification: "other",
|
|
168
|
-
},
|
|
169
|
-
// Documented, never seen in a recording: not mapped, not installed.
|
|
170
|
-
unverifiedEvents: ["errorOccurred", "preCompact"],
|
|
171
|
-
// postToolUseFailure is documented, not recorded: a call that closes with no failure event is not assumed to have succeeded.
|
|
172
|
-
capabilities: { failureEvent: false, argvTag: false, helperSessions: true, launchKey: true, readsForeignHooks: true },
|
|
173
|
-
// The CLI marks every call inside a helper with agentId, agentType and parentAgentId (the main session); the helper's own sessionId
|
|
174
|
-
// is its agentId, so the event belongs to the parent. VS Code sends none of the three (src/copilot-helpers.ts links those).
|
|
175
|
-
fields: { ...SHARED_FIELDS, eventName: "hook_event_name", session: "sessionId", parentSession: "parentAgentId", toolName: "toolName", toolInput: "toolArgs", toolResponse: "toolResult", toolUseId: "toolCallId", agentId: "agentId", agentType: "agentType", transcriptPath: "transcriptPath", lastAssistantMessage: "response" },
|
|
176
|
-
// A helper's own prompt (the task's prompt text) and its own agentStop are not the person's request nor the main agent's stop: the helper's
|
|
177
|
-
// finish is the subagentStop. Only an event that names an agent is changed.
|
|
178
|
-
// Nor is a host system notification a request (see isSystemNotification).
|
|
179
|
-
refineKind: (kind, p) => ((kind === "prompt" || kind === "stop") && typeof p.agentId === "string" && p.agentId !== "" ? "other" : kind === "prompt" && isSystemNotification(p.prompt) ? "other" : kind),
|
|
180
|
-
failureOf: (kind, p) => (kind === "tool-failure" ? { raw: typeof p.error === "string" ? p.error : "", interrupted: false } : kind === "tool-post" ? shellFailure(p) : undefined),
|
|
181
|
-
extraOf: (p) => (typeof p.stop_hook_active === "boolean" ? { stopHookActive: p.stop_hook_active } : {}),
|
|
182
|
-
parseToolInput: parseArgs,
|
|
183
|
-
calls: { argsKey, syntheticId: (session, n) => `copilot-${session}-${n}` },
|
|
184
|
-
narration: {
|
|
185
|
-
// The commentary reaches events.jsonl a few ms before the Pre (recorded); whether it is flushed before the Pre command runs is untested, so a Post reads again.
|
|
186
|
-
sources: [
|
|
187
|
-
{ kind: "commentary-before-call", readableAt: "pre", reason: true },
|
|
188
|
-
{ kind: "closing-message", readableAt: "post" },
|
|
189
|
-
],
|
|
190
|
-
foldLine: copilotLine,
|
|
191
|
-
closing: (cur) => cur?.closing ?? "",
|
|
192
|
-
// Live 1.0.93: the final_answer line carries a timestamp 2 ms before agentStop but was not in the file when the hook ran.
|
|
193
|
-
closingWaitMs: 1000,
|
|
194
|
-
},
|
|
195
|
-
sessionTitle: copilotSessionTitle,
|
|
196
|
-
sessionFile: { bySessionId: true, locate: locateEvents },
|
|
197
|
-
install: {
|
|
198
|
-
skillRoot: path.join(".copilot", "skills"),
|
|
199
|
-
hostFlag: "copilot",
|
|
200
|
-
folderFromPayloadCwd: true,
|
|
201
|
-
ownsFile: true,
|
|
202
|
-
// Copilot's hook output is JSON for some events and userPromptSubmitted has no output channel for context (platforms/copilot-cli/capabilities.json):
|
|
203
|
-
// print nothing. The "save in the folder" words reach Copilot through the cocheck skill, which `cocheck install` writes to ~/.copilot/skills.
|
|
204
|
-
promptContext: false,
|
|
205
|
-
events: copilotEvents,
|
|
206
|
-
configFile: (env, userHome) => path.join(env.COPILOT_HOME || path.join(userHome, ".copilot"), "hooks", "cocheck.json"),
|
|
207
|
-
addHooks: (_text, _file, spec, plat = platform()) => {
|
|
208
|
-
const command = spec === undefined ? "" : plat.hookCommand.build(spec);
|
|
209
|
-
const hooks = {};
|
|
210
|
-
// Choice: on Windows only `powershell` is written, not `bash` as well: Copilot runs `powershell` there, and a `bash` twin would
|
|
211
|
-
// fire the hook twice for a Git Bash setup that reads both. PowerShell 5.1 has no `||`, so the fail-open is `; exit 0`.
|
|
212
|
-
const windows = plat.shellDialect.kind === "cmd";
|
|
213
|
-
for (const event of copilotEvents) {
|
|
214
|
-
const line = `${command} --event ${event}${windows ? (event === "preToolUse" ? "; exit 0" : "") : failOpen(event)}`;
|
|
215
|
-
hooks[event] = [windows ? { type: "command", powershell: line, timeoutSec: 30 } : { type: "command", bash: line, timeoutSec: 30 }];
|
|
216
|
-
}
|
|
217
|
-
return JSON.stringify({ version: 1, hooks }, null, 2) + "\n";
|
|
218
|
-
},
|
|
219
|
-
// The file is CoCheck's alone: it goes whole, but only when it carries CoCheck's marker (a file of the same name that is not ours stays).
|
|
220
|
-
removeHooks: (text, _file, plat = platform()) => (eventsWithOurs(text, plat).length > 0 ? { text: "", changed: true } : { text, changed: false }),
|
|
221
|
-
missingEvents: (text, _file, plat = platform()) => {
|
|
222
|
-
const have = new Set(eventsWithOurs(text, plat));
|
|
223
|
-
return copilotEvents.filter((e) => !have.has(e));
|
|
224
|
-
},
|
|
225
|
-
checkPayload: (folder) => ({ payload: { sessionId: "install-check", cwd: folder, toolName: "bash", toolArgs: { command: "true" } }, event: "preToolUse" }),
|
|
226
|
-
notes: ({ launcherDir, home }) => `If you turn on Copilot's sandbox (copilot --sandbox, or /sandbox enable), its hooks stop working unless settings.json grants them access: add ${launcherDir} and ${home} to sandbox.userPolicy.filesystem.readwritePaths. CoCheck does not edit your Copilot settings.`,
|
|
227
|
-
afterInstall: "Copilot trust step for user-level hooks: unverified. Repo hooks need a trusted folder; whether hooks in ~/.copilot/hooks ask for trust too is not known yet. If Copilot asks, trust them once, or CoCheck records nothing from it.",
|
|
228
|
-
},
|
|
229
|
-
shape: {
|
|
230
|
-
preToolUse: ["sessionId", "cwd", "toolName", "toolArgs"],
|
|
231
|
-
postToolUse: ["sessionId", "cwd", "toolName", "toolArgs", "toolResult"],
|
|
232
|
-
postToolUseFailure: ["sessionId", "cwd", "toolName", "toolArgs", "error"],
|
|
233
|
-
agentStop: ["sessionId", "cwd", "transcriptPath"],
|
|
234
|
-
userPromptSubmitted: ["sessionId", "cwd", "prompt"],
|
|
235
|
-
},
|
|
236
|
-
};
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
// The L3 extras: first-party code a harness manifest opts into by name (`"extras": ["codex-rollout-narration"]`). A manifest is data and holds no code,
|
|
2
|
+
// so whatever is not data (a reader of the host's own session file, a config editor, a trust probe) lives here, in this repo, under a name.
|
|
3
|
+
// A manifest that names an extra this table lacks fails validation. The table is read at call time: the profile modules it imports load in any order.
|
|
4
|
+
import { readClaudeCalls } from "../coverage.js";
|
|
5
|
+
import { CLAUDE_HELPERS, claudeClosing, claudeFieldText, claudeLine } from "./claude.js";
|
|
6
|
+
import { CODEX_TOML_EDITOR, codexClaimAtPre, codexFailure, codexToolName, codexDisplayText, codexLine, codexTrustProblemOf, locateHelperRollout, locateRollout, rolloutCallExits, rolloutCallText, rolloutRefusedCommands } from "./codex.js";
|
|
7
|
+
import { copilotLine, locateEvents } from "./copilot.js";
|
|
8
|
+
import { claudeSessionTitle, codexSessionTitle, copilotSessionTitle } from "./session-titles.js";
|
|
9
|
+
/** Every extra, by name. */
|
|
10
|
+
export const extras = () => ({
|
|
11
|
+
"claude-transcript-narration": { about: "Reads the call's words and the closing message from a Claude Code transcript.", narration: { foldLine: claudeLine, closing: claudeClosing } },
|
|
12
|
+
"codex-rollout-narration": { about: "Reads the call's words and the closing message from a Codex rollout.", narration: { foldLine: codexLine, claimAtPre: codexClaimAtPre, closing: (cur) => cur?.closing ?? "" } },
|
|
13
|
+
"copilot-events-narration": { about: "Reads the call's words and the closing message from a Copilot session's events.jsonl.", narration: { foldLine: copilotLine, closing: (cur) => cur?.closing ?? "" } },
|
|
14
|
+
"transcript-coverage": { about: "Lists every call id a Claude Code transcript holds, to check the hook saw them all.", coverage: { readCalls: (sessionFile, session) => readClaudeCalls(sessionFile, session) } },
|
|
15
|
+
"transcript-helpers": { about: "Finds a helper's own transcript and meta file beside a Claude Code session file.", helpers: CLAUDE_HELPERS },
|
|
16
|
+
"claude-reveal": { about: "Reads a withheld tool-input field back from a Claude Code transcript.", reveal: { fieldText: claudeFieldText } },
|
|
17
|
+
"codex-rollout-locate": { about: "Finds a Codex rollout from the thread id.", sessionFile: { bySessionId: true, locate: locateRollout } },
|
|
18
|
+
"copilot-events-locate": { about: "Finds a Copilot session's events.jsonl from the session id.", sessionFile: { bySessionId: true, locate: locateEvents } },
|
|
19
|
+
"codex-helper-rollout-lookup": { about: "Finds a Codex helper's own rollout, when its header names the main thread.", sessionFile: { locateHelper: locateHelperRollout } },
|
|
20
|
+
"codex-rollout-call-readers": { about: "Reads each call's own text, exit status and host refusals from a Codex rollout.", sessionFile: { callText: rolloutCallText, callExit: rolloutCallExits, refusedCommands: rolloutRefusedCommands } },
|
|
21
|
+
"codex-display-text": { about: "Turns a Codex reply's file-citation directives into plain words.", outsiderSafe: true, displayText: codexDisplayText },
|
|
22
|
+
"claude-session-title": { about: "Reads the title Claude Code gave a session.", sessionTitle: claudeSessionTitle },
|
|
23
|
+
"codex-failure-read": { about: "Reads a failed Codex call: the shared error flags, and a Bash output that is only shell error lines (inferred).", failureOf: codexFailure },
|
|
24
|
+
"codex-tool-name": { about: "Takes Codex's tool namespace (`collaborationsend_message`) off a tool name.", toolName: codexToolName },
|
|
25
|
+
"codex-session-title": { about: "Reads the title Codex gave a session.", sessionTitle: codexSessionTitle },
|
|
26
|
+
"copilot-session-title": { about: "Reads the title Copilot gave a session.", sessionTitle: copilotSessionTitle },
|
|
27
|
+
"codex-toml-editor": { about: "Adds, removes and checks CoCheck's hook tables in Codex's config.toml.", homeEnv: ["CODEX_HOME"], install: CODEX_TOML_EDITOR },
|
|
28
|
+
"codex-trust-probe": { about: "Asks Codex whether it trusts the installed hooks.", install: { trustProblem: codexTrustProblemOf } },
|
|
29
|
+
"helper-linker": { about: "Links a helper's events (under the helper's own session id) to the main session, or holds them (src/helper-linker.ts).", capabilities: { helperSessions: true, launchKey: true }, fields: { launchKey: "cocheckLaunchKey" } },
|
|
30
|
+
"install-default": { about: "Marks the host an install record without a host list, and a hook check without a host, fall back to." },
|
|
31
|
+
});
|
|
32
|
+
export const knownExtra = (name) => Object.hasOwn(extras(), name);
|
|
33
|
+
/** True when a manifest from the person's own folder may name the extra. */
|
|
34
|
+
export const outsiderSafeExtra = (name) => Object.hasOwn(extras(), name) && extras()[name].outsiderSafe === true;
|
|
35
|
+
const MERGED = ["narration", "sessionFile", "install", "capabilities", "fields"];
|
|
36
|
+
/** The profile with the named extras added. Throws for a name the table lacks. */
|
|
37
|
+
export function applyExtras(profile, names) {
|
|
38
|
+
const table = extras();
|
|
39
|
+
const out = { ...profile };
|
|
40
|
+
for (const name of names) {
|
|
41
|
+
const part = table[name];
|
|
42
|
+
if (part === undefined)
|
|
43
|
+
throw new Error(`unknown extra ${JSON.stringify(name)}`);
|
|
44
|
+
for (const [k, v] of Object.entries(part)) {
|
|
45
|
+
if (k === "about" || v === undefined)
|
|
46
|
+
continue;
|
|
47
|
+
if (k === "homeEnv") {
|
|
48
|
+
out[k] = [...new Set([...(out[k] ?? []), ...v])];
|
|
49
|
+
continue;
|
|
50
|
+
}
|
|
51
|
+
out[k] = MERGED.includes(k) ? { ...out[k], ...v } : v;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
return { ...out, extras: [...(profile.extras ?? []), ...names] };
|
|
55
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// Reads harness manifests from a folder (`<dir>/<key>/cocheck-harness.json`) and compiles them. The built-in folder ships with CoCheck
|
|
2
|
+
// (harnesses/ at the repo root, dist/harnesses/ in a build); the outsider folder is the person's own (`<CoCheck data home>/harnesses/`, or $COCHECK_HARNESS_DIR).
|
|
3
|
+
// A manifest that does not load is skipped with one plain line naming the file and the field; the others still load.
|
|
4
|
+
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { compileManifest } from "./compile.js";
|
|
7
|
+
import { MANIFEST_FILE, validateManifest } from "./manifest.js";
|
|
8
|
+
/** Folder names that are not host keys: `--for` words and the key a record without a host carries. */
|
|
9
|
+
export const RESERVED_KEYS = ["both", "all", "none", "unknown"];
|
|
10
|
+
/**
|
|
11
|
+
* What an outsider manifest may not declare: each would claim a proof only first-party code earns, or a built-in alias. An outsider's `foreignHookFingerprint`
|
|
12
|
+
* is allowed: it makes another host's hook skip a payload only while the outsider's own CoCheck hook is installed for that folder (see `runsOtherHostsHook`).
|
|
13
|
+
*/
|
|
14
|
+
function outsiderProblem(m) {
|
|
15
|
+
if (m.argvTag !== undefined || m.capabilities?.argvTag === true)
|
|
16
|
+
return "argvTag: only a built-in host can tag a shell call (an outsider's events are never proof)";
|
|
17
|
+
if (m.install?.inBothAlias === true)
|
|
18
|
+
return "install.inBothAlias: `--for both` means the built-in hosts";
|
|
19
|
+
return undefined;
|
|
20
|
+
}
|
|
21
|
+
/** The manifests under `dir`. `reserved`: keys already taken (a manifest may not reuse one). `source` "outsider" caps the profile's trust and applies the outsider rules. */
|
|
22
|
+
export function loadHarnessFolder(dir, source, reserved) {
|
|
23
|
+
const out = { profiles: [], errors: [] };
|
|
24
|
+
let names;
|
|
25
|
+
try {
|
|
26
|
+
if (!existsSync(dir) || !statSync(dir).isDirectory())
|
|
27
|
+
return out;
|
|
28
|
+
names = readdirSync(dir).sort();
|
|
29
|
+
}
|
|
30
|
+
catch (error) {
|
|
31
|
+
out.errors.push(`${dir}: cannot be read (${error.code ?? "error"})`);
|
|
32
|
+
return out;
|
|
33
|
+
}
|
|
34
|
+
const taken = new Set([...reserved, ...RESERVED_KEYS]);
|
|
35
|
+
for (const name of names) {
|
|
36
|
+
const file = path.join(dir, name, MANIFEST_FILE);
|
|
37
|
+
const label = `${name}/${MANIFEST_FILE}`;
|
|
38
|
+
try {
|
|
39
|
+
if (!existsSync(file))
|
|
40
|
+
continue;
|
|
41
|
+
let raw;
|
|
42
|
+
try {
|
|
43
|
+
raw = JSON.parse(readFileSync(file, "utf8"));
|
|
44
|
+
}
|
|
45
|
+
catch {
|
|
46
|
+
throw new Error(`${label}: not valid JSON`);
|
|
47
|
+
}
|
|
48
|
+
const m = validateManifest(raw, label, { outsider: source === "outsider", builtIn: source === "built-in" });
|
|
49
|
+
if (m.key !== name)
|
|
50
|
+
throw new Error(`${label}: key: ${JSON.stringify(m.key)} must match the folder name ${JSON.stringify(name)}`);
|
|
51
|
+
if (taken.has(m.key))
|
|
52
|
+
throw new Error(`${label}: key: ${JSON.stringify(m.key)} is already a host; a manifest cannot reuse a key`);
|
|
53
|
+
if (source === "outsider") {
|
|
54
|
+
const problem = outsiderProblem(m);
|
|
55
|
+
if (problem !== undefined)
|
|
56
|
+
throw new Error(`${label}: ${problem}`);
|
|
57
|
+
}
|
|
58
|
+
out.profiles.push(compileManifest(m, source));
|
|
59
|
+
taken.add(m.key);
|
|
60
|
+
}
|
|
61
|
+
catch (error) {
|
|
62
|
+
out.errors.push(error instanceof Error ? error.message : String(error));
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return out;
|
|
66
|
+
}
|
package/dist/hosts/index.js
CHANGED
|
@@ -1,14 +1,62 @@
|
|
|
1
1
|
// The host registry: the one place that lists the profiles. Lookups are functions, not a table built at load, so the profiles and the
|
|
2
2
|
// modules they import can load in any order. The built-in list is read at call time too: narration.ts imports this file and the profiles import narration.ts, so a module-level array would hit a profile before it is initialized.
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
3
|
+
import { loadHarnessFolder } from "./harnesses.js";
|
|
4
|
+
import { matchesFingerprint } from "./shared.js";
|
|
5
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
6
|
+
import path from "node:path";
|
|
6
7
|
export { MARKER } from "./types.js";
|
|
7
|
-
/** Every profile, in the order they are listed to the person. */
|
|
8
|
-
export const allProfiles = () => [...builtIn(), ...added];
|
|
9
|
-
/** The registry
|
|
10
|
-
|
|
8
|
+
/** Every profile, in the order they are listed to the person: the built-in hosts, hosts added by `registerHost`, then outsider harnesses. */
|
|
9
|
+
export const allProfiles = () => [...builtIn(), ...added, ...outsiders];
|
|
10
|
+
/** The registry: the profile modules, then the manifests that ship with CoCheck. */
|
|
11
|
+
// Listed in key order, whether a host is a profile module or a shipped manifest.
|
|
12
|
+
const builtIn = () => [...shippedManifests()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
|
|
13
|
+
const moduleProfiles = () => [];
|
|
11
14
|
const added = [];
|
|
15
|
+
let outsiders = [];
|
|
16
|
+
let outsiderErrors = [];
|
|
17
|
+
/**
|
|
18
|
+
* The folder of built-in manifests: data, not code. It is `harnesses/` at the repo root when this module runs from src/hosts/, and `dist/harnesses`
|
|
19
|
+
* when it runs from the built dist/hosts/ (scripts/build.mjs copies it there, as it does `connectors/`). Shipping a harness built in is a data change there.
|
|
20
|
+
*/
|
|
21
|
+
export const BUILTIN_HARNESSES_ROOT = import.meta.url.endsWith(".ts") ? path.join(import.meta.dirname, "..", "..", "harnesses") : path.join(import.meta.dirname, "..", "harnesses");
|
|
22
|
+
let shippedDir = BUILTIN_HARNESSES_ROOT;
|
|
23
|
+
let shipped;
|
|
24
|
+
function shippedManifests() {
|
|
25
|
+
if (shipped === undefined) {
|
|
26
|
+
const loaded = loadHarnessFolder(shippedDir, "built-in", moduleProfiles().map((p) => p.key));
|
|
27
|
+
// A built-in manifest that does not load is a defect of this build, not of the person's setup.
|
|
28
|
+
if (loaded.errors.length > 0)
|
|
29
|
+
throw new Error(`built-in harness manifest: ${loaded.errors[0]}`);
|
|
30
|
+
shipped = loaded.profiles;
|
|
31
|
+
}
|
|
32
|
+
return shipped;
|
|
33
|
+
}
|
|
34
|
+
/** Points the built-in manifest folder somewhere else (a test), or back (undefined). */
|
|
35
|
+
export function setBuiltInHarnessDirForTest(dir) {
|
|
36
|
+
shippedDir = dir ?? BUILTIN_HARNESSES_ROOT;
|
|
37
|
+
shipped = undefined;
|
|
38
|
+
}
|
|
39
|
+
/** The folder of the person's own harness manifests: `$COCHECK_HARNESS_DIR`, else `<data home>/harnesses`. */
|
|
40
|
+
export const outsiderHarnessDir = (env, home) => env.COCHECK_HARNESS_DIR || process.env.COCHECK_HARNESS_DIR || (home === undefined ? undefined : path.join(home, "harnesses"));
|
|
41
|
+
/**
|
|
42
|
+
* Loads the harnesses in `dir` as outsiders (replacing any loaded before) and returns one line per manifest skipped. Never throws: a manifest that does not
|
|
43
|
+
* load is skipped, so it cannot stop another host's hook. An outsider's events never prove more than "inferred" (`HostProfile.trust`).
|
|
44
|
+
*/
|
|
45
|
+
export function loadOutsiderHarnesses(dir) {
|
|
46
|
+
try {
|
|
47
|
+
const taken = [...builtIn(), ...added].map((p) => p.key);
|
|
48
|
+
const loaded = dir === undefined ? { profiles: [], errors: [] } : loadHarnessFolder(dir, "outsider", taken);
|
|
49
|
+
outsiders = loaded.profiles;
|
|
50
|
+
outsiderErrors = loaded.errors;
|
|
51
|
+
}
|
|
52
|
+
catch (error) {
|
|
53
|
+
outsiders = [];
|
|
54
|
+
outsiderErrors = [`harnesses: ${error instanceof Error ? error.message : String(error)}`];
|
|
55
|
+
}
|
|
56
|
+
return outsiderErrors;
|
|
57
|
+
}
|
|
58
|
+
/** The lines for the manifests the last `loadOutsiderHarnesses` skipped. */
|
|
59
|
+
export const skippedHarnesses = () => outsiderErrors;
|
|
12
60
|
/** Adds a profile after the built-in ones until the returned function is called. For tests that prove a new host needs no core edit. */
|
|
13
61
|
export function registerHost(profile) {
|
|
14
62
|
added.push(profile);
|
|
@@ -38,7 +86,87 @@ export function toolNameOf(host, reported) {
|
|
|
38
86
|
return p?.toolName === undefined ? reported : p.toolName(reported, {});
|
|
39
87
|
}
|
|
40
88
|
/** The host a task is assumed to run under when nothing says otherwise: the default main lane, and the folder variable the hook falls back to. */
|
|
41
|
-
export const defaultProfile = () =>
|
|
89
|
+
export const defaultProfile = () => profileWithExtra("install-default");
|
|
90
|
+
/** The profile that declares the named optional part (`HostProfile.extras`). Throws when no host does: a caller asks only for an extra the built-in hosts declare. */
|
|
91
|
+
export function profileWithExtra(name) {
|
|
92
|
+
const p = allProfiles().find((x) => x.extras?.includes(name) === true);
|
|
93
|
+
if (p === undefined)
|
|
94
|
+
throw new Error(`no host declares ${name}`);
|
|
95
|
+
return p;
|
|
96
|
+
}
|
|
97
|
+
/** The host keys that have an installer, in the order they are listed to the person. */
|
|
98
|
+
export const installableKeys = () => allProfiles().filter((p) => p.install !== undefined).map((p) => p.key);
|
|
99
|
+
/** The environment variables hosts set to the project folder, in listing order. */
|
|
100
|
+
export const projectDirVars = () => allProfiles().flatMap((p) => (p.install?.projectDirEnv === undefined ? [] : [p.install.projectDirEnv]));
|
|
101
|
+
/**
|
|
102
|
+
* True when a hook run of `host` carries the payload of a host that also runs this host's registration (a host that reads another's config):
|
|
103
|
+
* the run records nothing (the reading host's own entry records). A host that reads foreign hooks itself is never skipped.
|
|
104
|
+
* A built-in host's fingerprint decides on the payload shape alone. An outsider's fingerprint decides only when that outsider's own CoCheck hook
|
|
105
|
+
* is installed for the payload's folder (`outsiderHookInstalled`): otherwise nothing else would record the run, so it is recorded as before.
|
|
106
|
+
* The install check reads one small config file, and only for a payload that already matched an outsider's fingerprint.
|
|
107
|
+
*/
|
|
108
|
+
export function runsOtherHostsHook(host, payload, where) {
|
|
109
|
+
if (hasCapability(host, "readsForeignHooks"))
|
|
110
|
+
return false;
|
|
111
|
+
return allProfiles().some((p) => p.capabilities.readsForeignHooks && p.foreignHookFingerprint !== undefined && matchesFingerprint(p.foreignHookFingerprint, payload) && (p.trust !== "outsider" || (where !== undefined && outsiderHookInstalled(p, where.env, where.userHome, folderOfPayload(p, payload)))));
|
|
112
|
+
}
|
|
113
|
+
/** The task folder a payload names, read through the profile's own `cwd` field (Cursor: `workspace_roots[0]`). Undefined unless it is an absolute path. */
|
|
114
|
+
function folderOfPayload(p, payload) {
|
|
115
|
+
try {
|
|
116
|
+
const flat = p.readPayload === undefined ? payload : p.readPayload(payload);
|
|
117
|
+
const cwd = flat?.[p.fields.cwd];
|
|
118
|
+
return typeof cwd === "string" && path.isAbsolute(cwd) ? cwd : undefined;
|
|
119
|
+
}
|
|
120
|
+
catch {
|
|
121
|
+
return undefined;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* True when an outsider harness's own CoCheck hook is installed: its config file (for `folder`, when the path names `{project}`) exists and carries
|
|
126
|
+
* CoCheck's hook for every event its install block lists. The same test `cocheck status` uses for a built-in host ("installed" means no event is missing).
|
|
127
|
+
* An unreadable or unparsable config, or a path that needs a folder that is not given, is not installed.
|
|
128
|
+
*/
|
|
129
|
+
export function outsiderHookInstalled(p, env, userHome, folder) {
|
|
130
|
+
if (p.install === undefined)
|
|
131
|
+
return false;
|
|
132
|
+
try {
|
|
133
|
+
const file = p.install.configFile(env, userHome, folder);
|
|
134
|
+
if (!existsSync(file))
|
|
135
|
+
return false;
|
|
136
|
+
return p.install.missingEvents(readFileSync(file, "utf8"), file).length === 0;
|
|
137
|
+
}
|
|
138
|
+
catch {
|
|
139
|
+
return false;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
/** The outsider harnesses whose fingerprint is in force for one of `folders`: each with the config file that carries its hook, and the hosts whose hooks it makes skip a payload. */
|
|
143
|
+
export function activeOutsiderFingerprints(env, userHome, folders) {
|
|
144
|
+
const out = [];
|
|
145
|
+
for (const p of outsiders) {
|
|
146
|
+
if (!p.capabilities.readsForeignHooks || p.foreignHookFingerprint === undefined)
|
|
147
|
+
continue;
|
|
148
|
+
// A user-scope config needs no folder; a project-scope one is looked for in each folder CoCheck watches.
|
|
149
|
+
const candidates = [undefined, ...folders];
|
|
150
|
+
const at = candidates.findIndex((f) => outsiderHookInstalled(p, env, userHome, f));
|
|
151
|
+
if (at < 0)
|
|
152
|
+
continue;
|
|
153
|
+
const folder = candidates[at];
|
|
154
|
+
let configFile;
|
|
155
|
+
try {
|
|
156
|
+
configFile = p.install.configFile(env, userHome, folder);
|
|
157
|
+
}
|
|
158
|
+
catch {
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
const named = (p.readsConfigsOf ?? []).map((k) => allProfiles().find((x) => x.key === k)?.displayName ?? k);
|
|
162
|
+
out.push({ profile: p, configFile, skippedBy: named.length > 0 ? named : allProfiles().filter((x) => x.trust !== "outsider" && !x.capabilities.readsForeignHooks).map((x) => x.displayName) });
|
|
163
|
+
}
|
|
164
|
+
return out;
|
|
165
|
+
}
|
|
166
|
+
/** The hosts whose session id this environment carries (a shell the host started), each with its key and the id. */
|
|
167
|
+
export function sessionOfEnv(env) {
|
|
168
|
+
return allProfiles().flatMap((p) => (p.sessionEnv !== undefined && typeof env[p.sessionEnv] === "string" && env[p.sessionEnv] !== "" ? [{ host: p.key, session: env[p.sessionEnv] }] : []));
|
|
169
|
+
}
|
|
42
170
|
/** Clients that name themselves in a record but have no profile (nothing is recorded for them). Label only. */
|
|
43
171
|
const OTHER_CLIENTS = { gemini: "Gemini", cursor: "Cursor" };
|
|
44
172
|
/** The name for a host as stored on a record ("claude", "codex", or any client name). Undefined when nothing is known of it. */
|
|
@@ -50,3 +178,43 @@ export function knownHostLabel(host) {
|
|
|
50
178
|
export function reportsFailureEvents(host) {
|
|
51
179
|
return allProfiles().some((p) => p.key === host && p.capabilities.failureEvent);
|
|
52
180
|
}
|
|
181
|
+
// ---- tool classes ----
|
|
182
|
+
const toolIndexes = new WeakMap();
|
|
183
|
+
function indexOfTable(table) {
|
|
184
|
+
let ix = toolIndexes.get(table);
|
|
185
|
+
if (ix === undefined) {
|
|
186
|
+
const entries = Object.entries(table);
|
|
187
|
+
ix = { exact: new Map(entries), lower: new Map(entries.filter(([, e]) => e.anyCase === true).map(([n, e]) => [n.toLowerCase(), e])) };
|
|
188
|
+
toolIndexes.set(table, ix);
|
|
189
|
+
}
|
|
190
|
+
return ix;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* What the host's table says a tool is, by the exact name; with `anyCase`, a name the host varies in letter case is also found in any case.
|
|
194
|
+
* A record with no host, or a host with no profile, reads the built-in tables together (a name no host declares is unknown): the answer
|
|
195
|
+
* a record gave before tables were per host, so a stored op that names no host keeps its credit.
|
|
196
|
+
*/
|
|
197
|
+
export function toolEntryOf(host, tool, anyCase = false) {
|
|
198
|
+
if (tool == null)
|
|
199
|
+
return undefined;
|
|
200
|
+
const p = findProfile(host);
|
|
201
|
+
const tables = (p !== undefined ? [p] : builtIn()).map((x) => indexOfTable(x.toolClasses));
|
|
202
|
+
for (const ix of tables) {
|
|
203
|
+
const e = ix.exact.get(tool);
|
|
204
|
+
if (e !== undefined)
|
|
205
|
+
return e;
|
|
206
|
+
}
|
|
207
|
+
if (anyCase) {
|
|
208
|
+
const low = tool.toLowerCase();
|
|
209
|
+
for (const ix of tables) {
|
|
210
|
+
const e = ix.lower.get(low);
|
|
211
|
+
if (e !== undefined)
|
|
212
|
+
return e;
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
return undefined;
|
|
216
|
+
}
|
|
217
|
+
/** True when the host's table says a call of this tool wakes a helper that already ran (see `ToolEntry.resumesHelper`). */
|
|
218
|
+
export const resumesHelper = (host, tool) => toolEntryOf(host, tool)?.resumesHelper === true;
|
|
219
|
+
/** The class of a tool by its exact name, or undefined when the host does not declare it. */
|
|
220
|
+
export const toolClassOf = (host, tool) => toolEntryOf(host, tool)?.class;
|