passcontrol 1.7.2 → 1.8.0
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/bin/passcontrol.mjs +51 -0
- package/cli/codex-hooks.mjs +2 -2
- package/cli/memory-custody-sidecar.d.mts +19 -0
- package/cli/memory-custody-sidecar.mjs +470 -0
- package/cli/memory-custody.d.mts +24 -0
- package/cli/memory-custody.mjs +444 -0
- package/cli/memory-inventory.d.mts +15 -0
- package/cli/memory-inventory.mjs +390 -0
- package/cli/memory-review.d.mts +3 -0
- package/cli/memory-review.mjs +65 -0
- package/cli/menu.mjs +1 -0
- package/cli/mission-tools.d.mts +27 -0
- package/cli/mission-tools.mjs +373 -0
- package/cli/sidecar.mjs +138 -2
- package/cli/subscription-gate.mjs +9 -1
- package/cli/tool-gate.mjs +45 -3
- package/cli/tripwire-scan.d.mts +20 -0
- package/cli/tripwire-scan.mjs +279 -0
- package/cli/tripwire-sidecar.d.mts +10 -0
- package/cli/tripwire-sidecar.mjs +84 -0
- package/cli/tripwires.d.mts +21 -0
- package/cli/tripwires.mjs +208 -0
- package/package.json +1 -1
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
// Idea 13: which files an agent remembers with, and their entries' keys right now.
|
|
2
|
+
//
|
|
3
|
+
// The default set follows what each client documents it loads (SOURCES.md #1), and errs
|
|
4
|
+
// wide: a file the client might load is in the set even when it might not be.
|
|
5
|
+
//
|
|
6
|
+
// claude-code CLAUDE.md, CLAUDE.local.md and AGENTS.md in the working directory and
|
|
7
|
+
// every directory above it; .claude/CLAUDE.md; .claude/rules/**/*.md;
|
|
8
|
+
// nested CLAUDE.md / CLAUDE.local.md / AGENTS.md anywhere in the workspace
|
|
9
|
+
// (Claude Code loads those on demand); ~/.claude/CLAUDE.md and
|
|
10
|
+
// ~/.claude/rules/**; the managed CLAUDE.md; the auto-memory folder
|
|
11
|
+
// (~/.claude/projects/<repo>/memory/**, and any `autoMemoryDirectory` a
|
|
12
|
+
// settings file names); and every `@import` those files make, four hops deep.
|
|
13
|
+
// codex AGENTS.md and AGENTS.override.md from the git root down to the working
|
|
14
|
+
// directory, and $CODEX_HOME/AGENTS(.override).md.
|
|
15
|
+
//
|
|
16
|
+
// The owner adds their own paths on the agent's page. That list is held at the gateway and
|
|
17
|
+
// arrives with /self, never from a file here: a file here is one the agent can edit, and an
|
|
18
|
+
// agent that could shrink the set could hide a file from it. The owner can only ADD.
|
|
19
|
+
//
|
|
20
|
+
// Symlinks are followed, because the client follows them: what is hashed is what loads.
|
|
21
|
+
// A file that cannot be read, or is over the client's own size limit, is an `error`, and an
|
|
22
|
+
// error holds like an arrival. Nothing here decides custody; it only says what is there.
|
|
23
|
+
import { randomBytes } from "node:crypto";
|
|
24
|
+
import fs from "node:fs";
|
|
25
|
+
import os from "node:os";
|
|
26
|
+
import path from "node:path";
|
|
27
|
+
import { entryKeys, fileKey, memoryEntries, saltFingerprint, hmacHex } from "./memory-custody.mjs";
|
|
28
|
+
|
|
29
|
+
export const FILE_LIMIT_BYTES = 4 * 1024 * 1024; // Claude Code skips a CLAUDE.md over 4 MiB
|
|
30
|
+
export const TOTAL_LIMIT_BYTES = 32 * 1024 * 1024;
|
|
31
|
+
export const MAX_FILES = 2000;
|
|
32
|
+
const IMPORT_HOPS = 4;
|
|
33
|
+
const WALK_MAX_DIRS = 20000;
|
|
34
|
+
const WALK_SKIP = new Set(["node_modules", ".git", ".next", "dist", "build", ".venv", "venv", "__pycache__", "target", ".turbo", ".cache"]);
|
|
35
|
+
|
|
36
|
+
/** Labels shown to the owner: a closed set, never a file name the agent chose. */
|
|
37
|
+
export const LABELS = [
|
|
38
|
+
"project_instructions", // CLAUDE.md, .claude/CLAUDE.md, AGENTS.md at the workspace root
|
|
39
|
+
"local_instructions", // CLAUDE.local.md
|
|
40
|
+
"ancestor_instructions", // the same files in a directory above the workspace
|
|
41
|
+
"nested_instructions", // the same files in a subdirectory, loaded on demand
|
|
42
|
+
"rules_file", // .claude/rules/**
|
|
43
|
+
"user_instructions", // ~/.claude/CLAUDE.md, ~/.claude/rules/**
|
|
44
|
+
"managed_instructions",
|
|
45
|
+
"memory_index", // MEMORY.md in the auto-memory folder
|
|
46
|
+
"memory_note", // any other file in the auto-memory folder
|
|
47
|
+
"imported_file", // reached through an @import
|
|
48
|
+
"codex_instructions",
|
|
49
|
+
"owner_path",
|
|
50
|
+
];
|
|
51
|
+
|
|
52
|
+
/** The device's custody salt: created once, 0600. The gateway only ever sees its fingerprint. */
|
|
53
|
+
export function custodySalt({ env = process.env } = {}) {
|
|
54
|
+
const base = env.XDG_CONFIG_HOME || path.join(env.HOME || os.homedir(), ".config");
|
|
55
|
+
const file = path.join(base, "passcontrol", "memory-custody-salt");
|
|
56
|
+
try {
|
|
57
|
+
const value = fs.readFileSync(file, "utf8").trim();
|
|
58
|
+
if (/^[0-9a-f]{64}$/.test(value)) return value;
|
|
59
|
+
} catch {}
|
|
60
|
+
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
61
|
+
const value = randomBytes(32).toString("hex");
|
|
62
|
+
fs.writeFileSync(file, `${value}\n`, { mode: 0o600, flag: "w" });
|
|
63
|
+
return value;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The workspace root: the nearest directory above `cwd` with a `.git`, else `cwd`. */
|
|
67
|
+
export function workspaceRoot(cwd) {
|
|
68
|
+
let dir = path.resolve(cwd);
|
|
69
|
+
for (;;) {
|
|
70
|
+
if (fs.existsSync(path.join(dir, ".git"))) return dir;
|
|
71
|
+
const parent = path.dirname(dir);
|
|
72
|
+
if (parent === dir) return path.resolve(cwd);
|
|
73
|
+
dir = parent;
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Claude Code's project folder name: every character that is not a letter or digit becomes `-`. */
|
|
78
|
+
export const claudeProjectDirName = (root) => root.replace(/[^A-Za-z0-9]/g, "-");
|
|
79
|
+
|
|
80
|
+
const ancestors = (from) => {
|
|
81
|
+
const out = [];
|
|
82
|
+
let dir = path.resolve(from);
|
|
83
|
+
for (;;) {
|
|
84
|
+
out.push(dir);
|
|
85
|
+
const parent = path.dirname(dir);
|
|
86
|
+
if (parent === dir) return out;
|
|
87
|
+
dir = parent;
|
|
88
|
+
}
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
function readJson(file) {
|
|
92
|
+
try {
|
|
93
|
+
const v = JSON.parse(fs.readFileSync(file, "utf8"));
|
|
94
|
+
return v && typeof v === "object" && !Array.isArray(v) ? v : null;
|
|
95
|
+
} catch {
|
|
96
|
+
return null;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
const expandHome = (p, home) => (p === "~" ? home : p.startsWith("~/") ? path.join(home, p.slice(2)) : p);
|
|
101
|
+
|
|
102
|
+
/** Markdown files under `dir`, recursively, with a loop guard. */
|
|
103
|
+
function markdownUnder(dir, { limit = MAX_FILES } = {}) {
|
|
104
|
+
const out = [];
|
|
105
|
+
const seen = new Set();
|
|
106
|
+
let truncated = false;
|
|
107
|
+
const walk = (d, depth) => {
|
|
108
|
+
if (out.length >= limit) { truncated = true; return; }
|
|
109
|
+
let real;
|
|
110
|
+
try {
|
|
111
|
+
real = fs.realpathSync(d);
|
|
112
|
+
} catch (e) {
|
|
113
|
+
if (e?.code !== "ENOENT" && e?.code !== "ENOTDIR") truncated = true;
|
|
114
|
+
return;
|
|
115
|
+
}
|
|
116
|
+
if (seen.has(real)) return;
|
|
117
|
+
if (depth > 12) { truncated = true; return; }
|
|
118
|
+
seen.add(real);
|
|
119
|
+
let names;
|
|
120
|
+
try {
|
|
121
|
+
names = fs.readdirSync(d, { withFileTypes: true });
|
|
122
|
+
} catch {
|
|
123
|
+
truncated = true;
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
for (const e of names.sort((a, b) => (a.name < b.name ? -1 : 1))) {
|
|
127
|
+
if (out.length >= limit) { truncated = true; return; }
|
|
128
|
+
const p = path.join(d, e.name);
|
|
129
|
+
let stat;
|
|
130
|
+
try {
|
|
131
|
+
stat = fs.statSync(p);
|
|
132
|
+
} catch {
|
|
133
|
+
truncated = true;
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
if (stat.isDirectory()) walk(p, depth + 1);
|
|
137
|
+
else if (stat.isFile() && /\.md$/i.test(e.name)) out.push(p);
|
|
138
|
+
}
|
|
139
|
+
};
|
|
140
|
+
walk(dir, 0);
|
|
141
|
+
return { files: out, truncated };
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Nested instruction files anywhere in the workspace (loaded on demand by Claude Code). */
|
|
145
|
+
function nestedInstructions(root, names) {
|
|
146
|
+
const out = [];
|
|
147
|
+
let dirs = 0;
|
|
148
|
+
let truncated = false;
|
|
149
|
+
const walk = (d, depth) => {
|
|
150
|
+
if (depth > 24 || dirs++ > WALK_MAX_DIRS) { truncated = true; return; }
|
|
151
|
+
let entries;
|
|
152
|
+
try {
|
|
153
|
+
entries = fs.readdirSync(d, { withFileTypes: true });
|
|
154
|
+
} catch {
|
|
155
|
+
truncated = true;
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
for (const e of entries) {
|
|
159
|
+
if (e.isDirectory() && !WALK_SKIP.has(e.name)) walk(path.join(d, e.name), depth + 1);
|
|
160
|
+
else if ((e.isFile() || e.isSymbolicLink()) && names.has(e.name) && d !== root) out.push(path.join(d, e.name));
|
|
161
|
+
}
|
|
162
|
+
// .claude/rules inside a nested directory loads on demand too
|
|
163
|
+
if (d !== root && fs.existsSync(path.join(d, ".claude", "rules"))) {
|
|
164
|
+
const rules = markdownUnder(path.join(d, ".claude", "rules"));
|
|
165
|
+
out.push(...rules.files);
|
|
166
|
+
if (rules.truncated) truncated = true;
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
walk(root, 0);
|
|
170
|
+
return { files: out, truncated };
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** `@path` imports outside code spans and fences (the client's own rule). */
|
|
174
|
+
export function importsOf(text) {
|
|
175
|
+
const out = [];
|
|
176
|
+
let fence = null;
|
|
177
|
+
for (const line of String(text).replace(/\r\n?/g, "\n").split("\n")) {
|
|
178
|
+
const m = line.match(/^ {0,3}(`{3,}|~{3,})/);
|
|
179
|
+
if (m) {
|
|
180
|
+
if (!fence) fence = m[1][0];
|
|
181
|
+
else if (m[1][0] === fence) fence = null;
|
|
182
|
+
continue;
|
|
183
|
+
}
|
|
184
|
+
if (fence) continue;
|
|
185
|
+
const stripped = line.replace(/`[^`]*`/g, " ");
|
|
186
|
+
for (const im of stripped.matchAll(/(?:^|\s)@((?:\\ |[^\s])+)/g)) out.push(im[1].replace(/\\ /g, " "));
|
|
187
|
+
}
|
|
188
|
+
return out;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The memory set: `[{ id, label, path }]`, ids unique and stable for this workspace.
|
|
193
|
+
* @param {{ cwd: string, agent?: "claude-code" | "codex", env?: object, ownerPaths?: string[] }} options
|
|
194
|
+
*/
|
|
195
|
+
export function memoryFiles({ cwd, agent = "claude-code", env = process.env, ownerPaths = [], touchedDirs = [], touchedFiles = [] }) {
|
|
196
|
+
const home = env.HOME || os.homedir();
|
|
197
|
+
const root = workspaceRoot(cwd);
|
|
198
|
+
const files = new Map(); // id → { id, label, path }
|
|
199
|
+
const accessed = new Set(touchedFiles.filter((p) => typeof p === "string" && p).map((p) => path.resolve(cwd, p)));
|
|
200
|
+
let overflow = false;
|
|
201
|
+
const add = (id, label, p) => {
|
|
202
|
+
if (files.has(id)) return;
|
|
203
|
+
// Past the cap a file is not silently left out: the scan reports an error, which holds
|
|
204
|
+
// (red team R1-7: a poisoned note hid as file 2,001).
|
|
205
|
+
if (files.size >= MAX_FILES) {
|
|
206
|
+
overflow = true;
|
|
207
|
+
// Keep a specifically accessed memory file visible even when the bulk set is full.
|
|
208
|
+
if (!accessed.has(p)) return;
|
|
209
|
+
const victim = [...files.values()].reverse().find((f) => !accessed.has(f.path));
|
|
210
|
+
if (!victim) return;
|
|
211
|
+
files.delete(victim.id);
|
|
212
|
+
}
|
|
213
|
+
files.set(id, { id, label, path: p });
|
|
214
|
+
};
|
|
215
|
+
let walkTruncated = false;
|
|
216
|
+
const markdown = (dir) => {
|
|
217
|
+
const r = markdownUnder(dir);
|
|
218
|
+
if (r.truncated) walkTruncated = true;
|
|
219
|
+
// Only memory directories already in scope qualify; an ordinary source Read is not memory.
|
|
220
|
+
return [...new Set([...accessed].filter((p) => p.startsWith(path.resolve(dir) + path.sep) && /\.md$/i.test(p)).concat(r.files))];
|
|
221
|
+
};
|
|
222
|
+
const nested = (names) => {
|
|
223
|
+
const r = nestedInstructions(root, names);
|
|
224
|
+
if (r.truncated) walkTruncated = true;
|
|
225
|
+
return r.files;
|
|
226
|
+
};
|
|
227
|
+
const idFor = (p) => {
|
|
228
|
+
const abs = path.resolve(p);
|
|
229
|
+
if (abs === root || abs.startsWith(root + path.sep)) return `project:${path.relative(root, abs)}`;
|
|
230
|
+
if (abs.startsWith(home + path.sep)) return `home:${path.relative(home, abs)}`;
|
|
231
|
+
return `abs:${abs}`;
|
|
232
|
+
};
|
|
233
|
+
|
|
234
|
+
if (agent === "codex") {
|
|
235
|
+
const codexHome = env.CODEX_HOME || path.join(home, ".codex");
|
|
236
|
+
for (const name of ["AGENTS.md", "AGENTS.override.md"]) add(`codex:${name}`, "codex_instructions", path.join(codexHome, name));
|
|
237
|
+
for (const dir of ancestors(cwd)) {
|
|
238
|
+
for (const name of ["AGENTS.md", "AGENTS.override.md"]) add(idFor(path.join(dir, name)), dir === root ? "project_instructions" : "ancestor_instructions", path.join(dir, name));
|
|
239
|
+
if (dir === root) break;
|
|
240
|
+
}
|
|
241
|
+
for (const f of nested(new Set(["AGENTS.md", "AGENTS.override.md"]))) add(idFor(f), "nested_instructions", f);
|
|
242
|
+
} else {
|
|
243
|
+
const config = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
|
|
244
|
+
add("managed:CLAUDE.md", "managed_instructions", process.platform === "darwin" ? "/Library/Application Support/ClaudeCode/CLAUDE.md" : "/etc/claude-code/CLAUDE.md");
|
|
245
|
+
add("user:CLAUDE.md", "user_instructions", path.join(config, "CLAUDE.md"));
|
|
246
|
+
for (const f of markdown(path.join(config, "rules"))) add(`user:rules/${path.relative(path.join(config, "rules"), f)}`, "user_instructions", f);
|
|
247
|
+
for (const dir of ancestors(cwd)) {
|
|
248
|
+
const label = (name) => (name === "CLAUDE.local.md" ? "local_instructions" : dir === root || dir === path.resolve(cwd) ? "project_instructions" : "ancestor_instructions");
|
|
249
|
+
for (const name of ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]) add(idFor(path.join(dir, name)), label(name), path.join(dir, name));
|
|
250
|
+
}
|
|
251
|
+
add(idFor(path.join(cwd, ".claude", "CLAUDE.md")), "project_instructions", path.join(cwd, ".claude", "CLAUDE.md"));
|
|
252
|
+
for (const f of markdown(path.join(root, ".claude", "rules"))) add(idFor(f), "rules_file", f);
|
|
253
|
+
for (const f of nested(new Set(["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"]))) {
|
|
254
|
+
add(idFor(f), f.includes(`${path.sep}.claude${path.sep}rules${path.sep}`) ? "rules_file" : "nested_instructions", f);
|
|
255
|
+
}
|
|
256
|
+
// Auto memory: the default folder, plus any folder a settings file points it at.
|
|
257
|
+
const memoryDirs = new Set([path.join(config, "projects", claudeProjectDirName(root), "memory")]);
|
|
258
|
+
for (const s of [path.join(config, "settings.json"), path.join(root, ".claude", "settings.json"), path.join(root, ".claude", "settings.local.json")]) {
|
|
259
|
+
const v = readJson(s)?.autoMemoryDirectory;
|
|
260
|
+
if (typeof v === "string" && v) memoryDirs.add(path.resolve(root, expandHome(v, home)));
|
|
261
|
+
}
|
|
262
|
+
for (const dir of memoryDirs) {
|
|
263
|
+
const tag = dir === [...memoryDirs][0] ? "automem" : `automem@${idFor(dir)}`;
|
|
264
|
+
add(`${tag}:MEMORY.md`, "memory_index", path.join(dir, "MEMORY.md"));
|
|
265
|
+
for (const f of markdown(dir)) {
|
|
266
|
+
const rel = path.relative(dir, f);
|
|
267
|
+
add(`${tag}:${rel}`, rel === "MEMORY.md" ? "memory_index" : "memory_note", f);
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
// Imports, breadth-first, four hops.
|
|
271
|
+
let frontier = [...files.values()];
|
|
272
|
+
for (let hop = 0; hop < IMPORT_HOPS && frontier.length; hop++) {
|
|
273
|
+
const next = [];
|
|
274
|
+
for (const f of frontier) {
|
|
275
|
+
let text;
|
|
276
|
+
try {
|
|
277
|
+
text = fs.readFileSync(f.path, "utf8");
|
|
278
|
+
} catch {
|
|
279
|
+
continue;
|
|
280
|
+
}
|
|
281
|
+
for (const target of importsOf(text)) {
|
|
282
|
+
const p = path.resolve(path.dirname(f.path), expandHome(target, home));
|
|
283
|
+
const id = `import:${idFor(p)}`;
|
|
284
|
+
if (files.has(id) || [...files.values()].some((x) => x.path === p)) continue;
|
|
285
|
+
add(id, "imported_file", p);
|
|
286
|
+
next.push(files.get(id));
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
frontier = next.filter(Boolean);
|
|
290
|
+
}
|
|
291
|
+
// Four hops bounds work, not trust: report any imports the bound left unvisited.
|
|
292
|
+
for (const f of frontier) {
|
|
293
|
+
let text;
|
|
294
|
+
try { text = fs.readFileSync(f.path, "utf8"); } catch { continue; }
|
|
295
|
+
if (importsOf(text).some((target) => {
|
|
296
|
+
const p = path.resolve(path.dirname(f.path), expandHome(target, home));
|
|
297
|
+
return ![...files.values()].some((x) => x.path === p);
|
|
298
|
+
})) walkTruncated = true;
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
// Directories a tool of this agent worked in: Claude Code loads the instruction files of
|
|
303
|
+
// any directory it reads or writes in, including ones the walk skips (node_modules, dist):
|
|
304
|
+
// red team R1-8. Their ancestors up to the workspace root are covered too.
|
|
305
|
+
const names = agent === "codex" ? ["AGENTS.md", "AGENTS.override.md"] : ["CLAUDE.md", "CLAUDE.local.md", "AGENTS.md"];
|
|
306
|
+
for (const raw of touchedDirs) {
|
|
307
|
+
if (typeof raw !== "string") continue;
|
|
308
|
+
let dir = path.resolve(raw);
|
|
309
|
+
if (!(dir === root || dir.startsWith(root + path.sep))) continue;
|
|
310
|
+
for (; dir.startsWith(root + path.sep); dir = path.dirname(dir)) {
|
|
311
|
+
for (const name of names) add(idFor(path.join(dir, name)), "nested_instructions", path.join(dir, name));
|
|
312
|
+
if (agent !== "codex") for (const f of markdown(path.join(dir, ".claude", "rules"))) add(idFor(f), "rules_file", f);
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
for (const raw of ownerPaths) {
|
|
316
|
+
if (typeof raw !== "string" || !raw) continue;
|
|
317
|
+
if (raw.length > 512) { walkTruncated = true; continue; }
|
|
318
|
+
const p = path.resolve(root, expandHome(raw, home));
|
|
319
|
+
let stat = null;
|
|
320
|
+
try {
|
|
321
|
+
stat = fs.statSync(p);
|
|
322
|
+
} catch {}
|
|
323
|
+
if (stat?.isDirectory()) for (const f of markdown(p)) add(`owner:${raw}/${path.relative(p, f)}`, "owner_path", f);
|
|
324
|
+
else add(`owner:${raw}`, "owner_path", p);
|
|
325
|
+
}
|
|
326
|
+
return { root, files: [...files.values()].sort((a, b) => Number(accessed.has(b.path)) - Number(accessed.has(a.path))), overflow, truncated: walkTruncated };
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Read and key the memory set. Files that do not exist are left out: an absent file has
|
|
331
|
+
* no entries. Returns `{ root, workspace, saltFp, files: [{ id, label, fileKey, keys, entries, bytes, link }], errors }`.
|
|
332
|
+
* `entries` (with text) stays on this machine; only `fileKey`, `keys` and `label` are sent.
|
|
333
|
+
*/
|
|
334
|
+
export function scanMemory({ salt, cwd, agent = "claude-code", env = process.env, ownerPaths = [], touchedDirs = [], touchedFiles = [] }) {
|
|
335
|
+
const { root, files, overflow, truncated } = memoryFiles({ cwd, agent, env, ownerPaths, touchedDirs, touchedFiles });
|
|
336
|
+
const out = [];
|
|
337
|
+
const errors = overflow ? [{ id: "inventory:overflow", label: "memory_note", reason: "too_many_files" }] : [];
|
|
338
|
+
if (truncated) errors.push({ id: "inventory:truncated", label: "memory_note", reason: "enumeration_incomplete" });
|
|
339
|
+
let total = 0;
|
|
340
|
+
for (const f of files) {
|
|
341
|
+
let lstat;
|
|
342
|
+
try {
|
|
343
|
+
lstat = fs.lstatSync(f.path);
|
|
344
|
+
} catch (e) {
|
|
345
|
+
if (e?.code === "ENOENT" || e?.code === "ENOTDIR") continue;
|
|
346
|
+
errors.push({ id: f.id, label: f.label, reason: "unreadable" });
|
|
347
|
+
continue;
|
|
348
|
+
}
|
|
349
|
+
let stat;
|
|
350
|
+
try {
|
|
351
|
+
stat = fs.statSync(f.path);
|
|
352
|
+
} catch {
|
|
353
|
+
// A dangling symlink loads nothing, but someone pointed it somewhere: say so.
|
|
354
|
+
errors.push({ id: f.id, label: f.label, reason: "dangling_link" });
|
|
355
|
+
continue;
|
|
356
|
+
}
|
|
357
|
+
if (!stat.isFile()) {
|
|
358
|
+
errors.push({ id: f.id, label: f.label, reason: "not_a_file" });
|
|
359
|
+
continue;
|
|
360
|
+
}
|
|
361
|
+
if (stat.size > FILE_LIMIT_BYTES || total + stat.size > TOTAL_LIMIT_BYTES) {
|
|
362
|
+
errors.push({ id: f.id, label: f.label, reason: "too_large" });
|
|
363
|
+
continue;
|
|
364
|
+
}
|
|
365
|
+
let text;
|
|
366
|
+
try {
|
|
367
|
+
text = fs.readFileSync(f.path, "utf8");
|
|
368
|
+
} catch {
|
|
369
|
+
errors.push({ id: f.id, label: f.label, reason: "unreadable" });
|
|
370
|
+
continue;
|
|
371
|
+
}
|
|
372
|
+
total += stat.size;
|
|
373
|
+
const entries = memoryEntries(text);
|
|
374
|
+
const keys = entryKeys(salt, f.id, entries);
|
|
375
|
+
out.push({
|
|
376
|
+
id: f.id,
|
|
377
|
+
label: f.label,
|
|
378
|
+
path: f.path,
|
|
379
|
+
fileKey: fileKey(salt, f.id),
|
|
380
|
+
keys,
|
|
381
|
+
entries: entries.map((e, n) => ({ key: keys[n], text: e.text, scope: e.scope })),
|
|
382
|
+
bytes: stat.size,
|
|
383
|
+
link: lstat.isSymbolicLink(),
|
|
384
|
+
});
|
|
385
|
+
}
|
|
386
|
+
return { root, workspace: hmacHex(salt, `pc-memory-workspace\0${root}`), saltFp: saltFingerprint(salt), files: out, errors };
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/** Every key in a scan, for snapshot diffs. */
|
|
390
|
+
export const scanKeys = (scan) => scan.files.flatMap((f) => f.keys);
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
export function inert(text: string): string;
|
|
2
|
+
export function formatReview(answer: { state: string; items?: Record<string, unknown>[] }, options?: { dashboard?: string }): string[];
|
|
3
|
+
export function memoryReviewCommand(options: { sidecarUrl: string; cwd?: string; client?: string; fetchImpl?: typeof fetch; print?: (line: string) => void }): Promise<void>;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
// `passcontrol memory review` (idea 13): the text of the memory entries waiting at customs,
|
|
2
|
+
// shown on the owner's own machine, where it never left. The gateway holds only hashes;
|
|
3
|
+
// the running sidecar matches them to this workspace's files (cli/memory-custody-sidecar.mjs).
|
|
4
|
+
// Deciding happens on the agent's page (cookie session, MFA), never here: this machine is
|
|
5
|
+
// the agent's machine, and anything that runs here, the agent can run.
|
|
6
|
+
//
|
|
7
|
+
// Entry text is the attacker's text when the entry is hostile, so it is printed inert: every
|
|
8
|
+
// control character but newline and tab becomes a visible escape, so it cannot move the
|
|
9
|
+
// cursor, recolour the terminal or overwrite the line that says where it came from.
|
|
10
|
+
|
|
11
|
+
const STATUS = { stamped: "written after outside content", unrecorded: "no custody record", rejected: "REJECTED, still in the file: remove it" };
|
|
12
|
+
const KIND = { web: "web or search", mcp: "MCP", shell_network: "network shell command", outside_read: "file outside the workspace", workspace_read: "third-party workspace", memory_arrival: "memory that was itself waiting" };
|
|
13
|
+
|
|
14
|
+
// C0/C1 controls, zero-width and bidi controls, line/paragraph separators, BOM.
|
|
15
|
+
const INERT = new RegExp("[\\u0000-\\u0008\\u000b-\\u001f\\u007f-\\u009f\\u200b-\\u200f\\u2028-\\u202e\\u2066-\\u2069\\ufeff]", "g");
|
|
16
|
+
|
|
17
|
+
/** Control characters made visible, so hostile text cannot drive the terminal. */
|
|
18
|
+
export function inert(text) {
|
|
19
|
+
return String(text).replace(INERT, (c) => `\\u{${c.codePointAt(0).toString(16)}}`);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** The lines `memory review` prints, from the sidecar's answer. Pure, for tests. */
|
|
23
|
+
export function formatReview(answer, { dashboard = "the agent's page on the dashboard" } = {}) {
|
|
24
|
+
if (answer.state === "off") return ["Memory custody is off for this agent."];
|
|
25
|
+
if (answer.state === "unknown") return ["The sidecar has not read this agent's settings yet. Try again in a few seconds."];
|
|
26
|
+
if (answer.state === "unavailable") return ["The sidecar could not ask the gateway. While it cannot, the agent is held."];
|
|
27
|
+
const items = Array.isArray(answer.items) ? answer.items.filter((i) => i.status === "rejected" || i.seen) : [];
|
|
28
|
+
if (!items.length) return ["Nothing waits at customs."];
|
|
29
|
+
const lines = [`${items.length} ${items.length === 1 ? "entry waits" : "entries wait"}. Decide on ${dashboard}; this command only shows them.`, ""];
|
|
30
|
+
const groups = new Map();
|
|
31
|
+
for (const i of items) {
|
|
32
|
+
const g = i.review_id ?? "(no review yet)";
|
|
33
|
+
if (!groups.has(g)) groups.set(g, []);
|
|
34
|
+
groups.get(g).push(i);
|
|
35
|
+
}
|
|
36
|
+
for (const [review, list] of groups) {
|
|
37
|
+
lines.push(`Review ${review}`);
|
|
38
|
+
for (const i of list) {
|
|
39
|
+
const origin = i.writer_session
|
|
40
|
+
? `written by session ${inert(i.writer_session)}${i.marks?.length ? ` after ${i.marks.map((k) => KIND[k] ?? inert(k)).join(", ")}` : ""}${i.hosts?.length ? ` (${i.hosts.map(inert).join(", ")})` : ""}`
|
|
41
|
+
: "no session wrote it that PassControl saw";
|
|
42
|
+
lines.push(` [${String(i.key).slice(0, 12)}] ${STATUS[i.status] ?? inert(i.status)}; ${origin}`);
|
|
43
|
+
if (i.local) {
|
|
44
|
+
lines.push(` ${inert(i.local.file)}${i.local.scope?.length ? ` under ${i.local.scope.map(inert).join(" > ")}` : ""}`);
|
|
45
|
+
for (const l of inert(i.local.text).split("\n")) lines.push(` | ${l}`);
|
|
46
|
+
} else {
|
|
47
|
+
lines.push(" (not in this workspace's files now: it may be in another workspace, or already removed)");
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
lines.push("");
|
|
51
|
+
}
|
|
52
|
+
return lines;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export async function memoryReviewCommand({ sidecarUrl, cwd = process.cwd(), client = "claude-code", fetchImpl = fetch, print = console.log }) {
|
|
56
|
+
const url = `${sidecarUrl.replace(/\/+$/, "")}/_passcontrol/memory?cwd=${encodeURIComponent(cwd)}${client === "codex" ? "&client=codex" : ""}`;
|
|
57
|
+
let answer;
|
|
58
|
+
try {
|
|
59
|
+
const res = await fetchImpl(url, { signal: AbortSignal.timeout(10_000) });
|
|
60
|
+
answer = await res.json();
|
|
61
|
+
} catch {
|
|
62
|
+
throw new Error(`No sidecar answered at ${sidecarUrl}. Start it with \`passcontrol sidecar\`, then run this again.`);
|
|
63
|
+
}
|
|
64
|
+
for (const line of formatReview(answer)) print(line);
|
|
65
|
+
}
|
package/cli/menu.mjs
CHANGED
|
@@ -269,6 +269,7 @@ export const HIDDEN = {
|
|
|
269
269
|
seal: "needs a session and an agent, both named by `sessions`, which is listed under Money",
|
|
270
270
|
statusline: "Claude Code runs it, not a person; `configure claude-code --statusline` installs it",
|
|
271
271
|
"codex-hook": "Codex runs it, not a person; `configure codex --subscription` installs it",
|
|
272
|
+
memory: "idea 13 research build: `memory review` needs a running sidecar with memory custody on; the decision is on the agent's page",
|
|
272
273
|
};
|
|
273
274
|
|
|
274
275
|
/** Every top-level command name the menu can reach, flattened. */
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
export type ShellClass =
|
|
2
|
+
| "inspect" | "build" | "vcs_local" | "process" | "fs_mutate" | "container" | "network" | "opaque" | "vcs_push" | "rm_rf";
|
|
3
|
+
export type ToolItem =
|
|
4
|
+
| { kind: "workspace"; root: string; write: boolean }
|
|
5
|
+
| { kind: "shell"; class: string }
|
|
6
|
+
| { kind: "host"; host: string; via: "web" | "browser" | "shell" }
|
|
7
|
+
| { kind: "tool"; name: string }
|
|
8
|
+
| { kind: "memory_write" };
|
|
9
|
+
export const SHELL_CLASSES: readonly ShellClass[];
|
|
10
|
+
export const NEVER_LEARNED: ReadonlySet<string>;
|
|
11
|
+
export const HOST_VIA: readonly ("web" | "browser" | "shell")[];
|
|
12
|
+
export const INTERNAL_TOOLS: ReadonlySet<string>;
|
|
13
|
+
export function validRoot(root: unknown): boolean;
|
|
14
|
+
export function normalisePath(path: unknown): string | null;
|
|
15
|
+
export function within(root: string, path: string): boolean;
|
|
16
|
+
export function normaliseHost(raw: unknown): string | null;
|
|
17
|
+
export function parseToolItem(item: unknown): ToolItem | null;
|
|
18
|
+
export function toolItemContains(outer: ToolItem | null | undefined, inner: ToolItem | null | undefined): boolean;
|
|
19
|
+
export function toolItemKey(item: ToolItem): string;
|
|
20
|
+
export function shellClassOf(word: unknown): ShellClass;
|
|
21
|
+
export function classifyShell(command: unknown): ToolItem[];
|
|
22
|
+
export function itemsForToolCall(input: unknown): ToolItem[];
|
|
23
|
+
export function internalItem(item: ToolItem): boolean;
|
|
24
|
+
export function evaluateMissionTools(
|
|
25
|
+
missionTools: readonly ToolItem[],
|
|
26
|
+
input: unknown
|
|
27
|
+
): { state: "inside" | "outside"; missing: ToolItem[] };
|