raytrace-cli 0.11.1__py3-none-win_arm64.whl

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 (165) hide show
  1. raytrace/__init__.py +1 -0
  2. raytrace/__main__.py +33 -0
  3. raytrace/app/LICENSE +21 -0
  4. raytrace/app/README.md +599 -0
  5. raytrace/app/bin/raytrace.mjs +297 -0
  6. raytrace/app/dist/dashboard/assets/dm-sans-latin-400-normal-BwCSEQnW.woff +0 -0
  7. raytrace/app/dist/dashboard/assets/dm-sans-latin-400-normal-CW0RaeGs.woff2 +0 -0
  8. raytrace/app/dist/dashboard/assets/dm-sans-latin-500-normal-B9HHJjqV.woff2 +0 -0
  9. raytrace/app/dist/dashboard/assets/dm-sans-latin-500-normal-Dr3UlScf.woff +0 -0
  10. raytrace/app/dist/dashboard/assets/dm-sans-latin-600-normal-Aqo67rzb.woff2 +0 -0
  11. raytrace/app/dist/dashboard/assets/dm-sans-latin-600-normal-BmdmIIQ2.woff +0 -0
  12. raytrace/app/dist/dashboard/assets/dm-sans-latin-700-normal-CUSSCpQX.woff +0 -0
  13. raytrace/app/dist/dashboard/assets/dm-sans-latin-700-normal-DvUfVpUG.woff2 +0 -0
  14. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-400-normal-BjWJ59Pq.woff +0 -0
  15. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-400-normal-BtiwyxMk.woff2 +0 -0
  16. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-500-normal-BJfUCQsA.woff2 +0 -0
  17. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-500-normal-DR84L5F-.woff +0 -0
  18. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-600-normal-4vooXBpG.woff2 +0 -0
  19. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-600-normal-DRtaDpgU.woff +0 -0
  20. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-700-normal-BLI3TTWz.woff +0 -0
  21. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-700-normal-CJIcxD6K.woff2 +0 -0
  22. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-400-normal-BSMlKf0J.woff2 +0 -0
  23. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-400-normal-CEL4l2ZJ.woff +0 -0
  24. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-500-normal-Ael50iVv.woff +0 -0
  25. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-500-normal-Bq9vWWag.woff2 +0 -0
  26. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-600-normal-CTOM6hUh.woff2 +0 -0
  27. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-600-normal-fLZuRloM.woff +0 -0
  28. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-400-normal-DMdlQ8Kv.woff +0 -0
  29. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-400-normal-xuaO2J-f.woff2 +0 -0
  30. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-500-normal-BIfNGwUT.woff +0 -0
  31. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-500-normal-BqneJy0T.woff2 +0 -0
  32. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-600-normal-9HEixskS.woff +0 -0
  33. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-600-normal-V-xxqcpd.woff2 +0 -0
  34. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-400-normal-CvHOgSBP.woff +0 -0
  35. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-400-normal-DMJ8VG8y.woff2 +0 -0
  36. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-500-normal-CB9ihrfo.woff +0 -0
  37. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-500-normal-DSY6xOcd.woff2 +0 -0
  38. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-600-normal-BgSNZQsw.woff2 +0 -0
  39. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-600-normal-DWFSQ4vo.woff +0 -0
  40. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-400-normal-BmRBH3aV.woff2 +0 -0
  41. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-400-normal-D3D2R8hC.woff +0 -0
  42. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-500-normal-CAhNIIs5.woff2 +0 -0
  43. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-500-normal-CZ70TYgx.woff +0 -0
  44. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-600-normal-D38SheWl.woff2 +0 -0
  45. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-600-normal-DmB0ttJJ.woff +0 -0
  46. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-400-normal-BulugwFq.woff2 +0 -0
  47. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-400-normal-DDuiU_S-.woff +0 -0
  48. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-500-normal-C8zxqsMH.woff +0 -0
  49. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-500-normal-DZ4AoWbu.woff2 +0 -0
  50. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-600-normal-D2EvbN8M.woff2 +0 -0
  51. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-600-normal-iLQfcSjf.woff +0 -0
  52. raytrace/app/dist/dashboard/assets/index-DepcI8Fi.js +38 -0
  53. raytrace/app/dist/dashboard/assets/index-H97VLD5l.css +1 -0
  54. raytrace/app/dist/dashboard/favicon.svg +6 -0
  55. raytrace/app/dist/dashboard/index.html +15 -0
  56. raytrace/app/package.json +48 -0
  57. raytrace/app/proxy/agent-intent-schema.test.mjs +142 -0
  58. raytrace/app/proxy/call-assessment.mjs +385 -0
  59. raytrace/app/proxy/call-assessment.test.mjs +167 -0
  60. raytrace/app/proxy/call-category.mjs +461 -0
  61. raytrace/app/proxy/capture-health.mjs +30 -0
  62. raytrace/app/proxy/capture-health.test.mjs +44 -0
  63. raytrace/app/proxy/capture.mjs +38 -0
  64. raytrace/app/proxy/capture.test.mjs +49 -0
  65. raytrace/app/proxy/claude-code-adapter.mjs +301 -0
  66. raytrace/app/proxy/claude-code-hook.mjs +22 -0
  67. raytrace/app/proxy/codex-config.mjs +36 -0
  68. raytrace/app/proxy/codex.mjs +14 -0
  69. raytrace/app/proxy/evidence-schema.test.mjs +240 -0
  70. raytrace/app/proxy/evidence-store.mjs +993 -0
  71. raytrace/app/proxy/evidence-store.test.mjs +301 -0
  72. raytrace/app/proxy/exec-narrative.mjs +625 -0
  73. raytrace/app/proxy/exec-narrative.test.mjs +262 -0
  74. raytrace/app/proxy/execution-correlation.mjs +185 -0
  75. raytrace/app/proxy/execution-correlation.test.mjs +146 -0
  76. raytrace/app/proxy/execution-runner.mjs +89 -0
  77. raytrace/app/proxy/execution-runner.test.mjs +38 -0
  78. raytrace/app/proxy/experiment-engine.mjs +195 -0
  79. raytrace/app/proxy/experiment-engine.test.mjs +93 -0
  80. raytrace/app/proxy/explanations.mjs +36 -0
  81. raytrace/app/proxy/explanations.test.mjs +20 -0
  82. raytrace/app/proxy/failure-signature.mjs +56 -0
  83. raytrace/app/proxy/gvisor-forwarder.mjs +493 -0
  84. raytrace/app/proxy/gvisor-forwarder.test.mjs +433 -0
  85. raytrace/app/proxy/init-evidence-db.mjs +227 -0
  86. raytrace/app/proxy/local-sandboxes.mjs +94 -0
  87. raytrace/app/proxy/local-token.mjs +30 -0
  88. raytrace/app/proxy/playground-recovery.test.mjs +130 -0
  89. raytrace/app/proxy/playground.mjs +439 -0
  90. raytrace/app/proxy/prompt-context.mjs +278 -0
  91. raytrace/app/proxy/prompt-traces.mjs +40 -0
  92. raytrace/app/proxy/prompt-traces.test.mjs +32 -0
  93. raytrace/app/proxy/providers.mjs +65 -0
  94. raytrace/app/proxy/providers.test.mjs +76 -0
  95. raytrace/app/proxy/proxy.integration.test.mjs +135 -0
  96. raytrace/app/proxy/raytace-proxy.mjs +941 -0
  97. raytrace/app/proxy/request-metrics.mjs +13 -0
  98. raytrace/app/proxy/request-metrics.test.mjs +19 -0
  99. raytrace/app/proxy/request-policy.mjs +45 -0
  100. raytrace/app/proxy/request-policy.test.mjs +47 -0
  101. raytrace/app/proxy/run-recap.mjs +139 -0
  102. raytrace/app/proxy/runtime-attribution.mjs +110 -0
  103. raytrace/app/proxy/sandbox-bridge.mjs +49 -0
  104. raytrace/app/proxy/schema/EVIDENCE_DATABASE.md +276 -0
  105. raytrace/app/proxy/schema/agent_intent.sql +101 -0
  106. raytrace/app/proxy/schema/auxiliary.sql +90 -0
  107. raytrace/app/proxy/schema/capture_health.sql +14 -0
  108. raytrace/app/proxy/schema/classification.sql +89 -0
  109. raytrace/app/proxy/schema/file_context.sql +53 -0
  110. raytrace/app/proxy/schema/runtime_evidence.sql +201 -0
  111. raytrace/app/proxy/schema/search.sql +66 -0
  112. raytrace/app/proxy/schema/shared_storage.sql +21 -0
  113. raytrace/app/proxy/search.mjs +418 -0
  114. raytrace/app/proxy/search.test.mjs +161 -0
  115. raytrace/app/proxy/smoke.test.mjs +93 -0
  116. raytrace/app/proxy/step-attribution.mjs +380 -0
  117. raytrace/app/proxy/step-lab.mjs +78 -0
  118. raytrace/app/proxy/step-lab.test.mjs +38 -0
  119. raytrace/app/proxy/summaries.mjs +151 -0
  120. raytrace/app/proxy/summaries.test.mjs +69 -0
  121. raytrace/app/proxy/tool-metadata.mjs +111 -0
  122. raytrace/app/proxy/tool-metadata.test.mjs +38 -0
  123. raytrace/app/proxy/trace-view.mjs +324 -0
  124. raytrace/app/proxy/trace-view.test.mjs +92 -0
  125. raytrace/app/proxy/typesafe.mjs +63 -0
  126. raytrace/app/proxy/typesafe.test.mjs +39 -0
  127. raytrace/app/src/agents.mjs +7 -0
  128. raytrace/app/src/api.mjs +57 -0
  129. raytrace/app/src/auth.mjs +205 -0
  130. raytrace/app/src/beta.mjs +96 -0
  131. raytrace/app/src/claude-code.mjs +93 -0
  132. raytrace/app/src/commands.mjs +285 -0
  133. raytrace/app/src/config.mjs +49 -0
  134. raytrace/app/src/export.mjs +200 -0
  135. raytrace/app/src/lima.mjs +176 -0
  136. raytrace/app/src/local-sandbox.mjs +358 -0
  137. raytrace/app/src/mcp.mjs +688 -0
  138. raytrace/app/src/paths.mjs +33 -0
  139. raytrace/app/src/prompt.mjs +42 -0
  140. raytrace/app/src/proxy-process.mjs +143 -0
  141. raytrace/app/src/sandbox.mjs +306 -0
  142. raytrace/app/src/share.mjs +86 -0
  143. raytrace/app/src/terminal.mjs +68 -0
  144. raytrace/app/src/upload.mjs +198 -0
  145. raytrace/app/worker/sandbox/Dockerfile +8 -0
  146. raytrace/app/worker/sandbox/SYSCALL_CATALOG.md +197 -0
  147. raytrace/app/worker/sandbox/claude-hook.mjs +364 -0
  148. raytrace/app/worker/sandbox/collector.py +405 -0
  149. raytrace/app/worker/sandbox/dns_forwarder.py +255 -0
  150. raytrace/app/worker/sandbox/engine.py +940 -0
  151. raytrace/app/worker/sandbox/file_scan.py +491 -0
  152. raytrace/app/worker/sandbox/lima.yaml +29 -0
  153. raytrace/app/worker/sandbox/network.py +90 -0
  154. raytrace/app/worker/sandbox/projects.py +702 -0
  155. raytrace/app/worker/sandbox/setup.py +159 -0
  156. raytrace/app/worker/sandbox/syscall_catalog.sql +985 -0
  157. raytrace/app/worker/sandbox/transcript-delivery.test.mjs +153 -0
  158. raytrace/app/worker/sandbox/viewer.py +195 -0
  159. raytrace/node/LICENSE +2946 -0
  160. raytrace/node/node.exe +4 -0
  161. raytrace_cli-0.11.1.dist-info/LICENSE +21 -0
  162. raytrace_cli-0.11.1.dist-info/METADATA +42 -0
  163. raytrace_cli-0.11.1.dist-info/RECORD +165 -0
  164. raytrace_cli-0.11.1.dist-info/WHEEL +4 -0
  165. raytrace_cli-0.11.1.dist-info/entry_points.txt +2 -0
@@ -0,0 +1,68 @@
1
+ // A new terminal running one command, for `raytrace mcp` to open a sandbox's
2
+ // terminal next to the editor. The environment says where the agent itself
3
+ // runs (an MCP server inherits it from its client), and the new terminal goes
4
+ // there when that can be driven from outside: a tmux window beside it, an iTerm
5
+ // or WezTerm window or tab. Otherwise the system's own terminal. VS Code's
6
+ // built-in terminal cannot be opened from outside VS Code, so there it is a
7
+ // separate Terminal window.
8
+ import { spawnSync } from 'node:child_process';
9
+
10
+ /** One argument, quoted for sh. */
11
+ export const shellQuote = (arg) => (/^[A-Za-z0-9_./:=@%+-]+$/.test(arg) ? arg : `'${String(arg).replace(/'/g, `'\\''`)}'`);
12
+ const appleString = (text) => `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
13
+ const has = (program) => spawnSync('sh', ['-c', `command -v ${shellQuote(program)}`], { stdio: 'ignore' }).status === 0;
14
+
15
+ function attempt(how, program, args) {
16
+ const result = spawnSync(program, args, { stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8', timeout: 15_000 });
17
+ if (result.error || result.status !== 0) {
18
+ return { opened: false, how, error: (result.error?.message || result.stderr || `exit ${result.status}`).trim().split('\n').slice(-2).join(' ') };
19
+ }
20
+ return { opened: true, how };
21
+ }
22
+
23
+ /** Where to open it, best first: [label, program, args]. */
24
+ function candidates(args, title, env) {
25
+ const command = args.map(shellQuote).join(' ');
26
+ const found = [];
27
+ if (env.TMUX && has('tmux')) found.push(['a new tmux window', 'tmux', ['new-window', '-n', title, command]]);
28
+ if (process.platform === 'darwin') {
29
+ if (env.TERM_PROGRAM === 'iTerm.app') {
30
+ found.push(['a new iTerm window', 'osascript', ['-e', `tell application "iTerm"
31
+ activate
32
+ set w to (create window with default profile)
33
+ tell current session of w to write text ${appleString(command)}
34
+ end tell`]]);
35
+ }
36
+ if (env.TERM_PROGRAM === 'WezTerm' && has('wezterm')) found.push(['a new WezTerm tab', 'wezterm', ['cli', 'spawn', '--', '/bin/sh', '-c', command]]);
37
+ found.push(['a new Terminal window', 'osascript', ['-e', `tell application "Terminal"
38
+ activate
39
+ do script ${appleString(command)}
40
+ end tell`]]);
41
+ } else if (process.platform === 'win32') {
42
+ const line = args.map((arg) => (/[\s"]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg)).join(' ');
43
+ if (spawnSync('where', ['wt'], { stdio: 'ignore' }).status === 0) found.push(['a new Windows Terminal tab', 'wt', ['new-tab', '--title', title, 'cmd', '/k', line]]);
44
+ found.push(['a new Command Prompt window', 'cmd', ['/c', 'start', `"${title}"`, 'cmd', '/k', line]]);
45
+ } else if (env.DISPLAY || env.WAYLAND_DISPLAY) {
46
+ for (const [program, flag] of [['x-terminal-emulator', '-e'], ['gnome-terminal', '--'], ['konsole', '-e'], ['xfce4-terminal', '-x'],
47
+ ['kitty', null], ['alacritty', '-e'], ['wezterm', 'start'], ['xterm', '-e']]) {
48
+ if (has(program)) found.push([`a new ${program} window`, program, [...(flag ? [flag] : []), '/bin/sh', '-c', command]]);
49
+ }
50
+ }
51
+ return found;
52
+ }
53
+
54
+ /**
55
+ * Open a new terminal running `args` (a program and its arguments). Answers
56
+ * { opened, how, command }: how it was opened, or why not, and the command as
57
+ * the user would type it, for when it could not be.
58
+ */
59
+ export function openTerminal(args, { title = 'RayTrace', env = process.env } = {}) {
60
+ const command = args.map(shellQuote).join(' ');
61
+ const errors = [];
62
+ for (const [how, program, programArgs] of candidates(args, title, env)) {
63
+ const result = attempt(how, program, programArgs);
64
+ if (result.opened) return { opened: true, how, command };
65
+ errors.push(`${how}: ${result.error}`);
66
+ }
67
+ return { opened: false, how: errors.length ? errors.join('; ') : 'no terminal found to open', command };
68
+ }
@@ -0,0 +1,198 @@
1
+ // `raytrace upload logs`: send a local sandbox's recorded evidences (the
2
+ // gzipped ~/.raytrace/evidence.db snapshot) to RayTrace cloud, where they
3
+ // render on app.raytracer.si like a cloud sandbox's. Uploading is always
4
+ // explicit: what will go is printed and confirmed first, and nothing is
5
+ // sent signed-out — the account flow runs first, like `sandbox create`.
6
+ import { DatabaseSync } from 'node:sqlite';
7
+ import { createHash } from 'node:crypto';
8
+ import { createReadStream, createWriteStream, existsSync, mkdtempSync, rmSync } from 'node:fs';
9
+ import { open, stat } from 'node:fs/promises';
10
+ import { tmpdir } from 'node:os';
11
+ import { join } from 'node:path';
12
+ import { createGzip } from 'node:zlib';
13
+ import { pipeline } from 'node:stream/promises';
14
+ import { accessToken, login } from './auth.mjs';
15
+ import { readConfig } from './config.mjs';
16
+ import { ask, interactive } from './prompt.mjs';
17
+ import { registry } from './local-sandbox.mjs';
18
+ import { paths } from './paths.mjs';
19
+ import { openEvidenceStore } from '../proxy/evidence-store.mjs';
20
+
21
+ const say = (line = '') => console.log(line);
22
+ const API = 'https://api.raytracer.si';
23
+ const CHUNK = 8 * 1024 * 1024;
24
+ const RETRIES = 5;
25
+ const mb = (bytes) => bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(2)} GB` : `${(bytes / 1024 ** 2).toFixed(1)} MB`;
26
+
27
+ /** The local sandbox an upload names: by id or name, else the only one. */
28
+ export function pickSandbox(ref, boxes = registry()) {
29
+ const ids = Object.keys(boxes);
30
+ if (!ids.length) throw new Error('No local sandboxes yet. Create one: raytrace sandbox create --local');
31
+ if (!ref) {
32
+ if (ids.length > 1) throw new Error(`More than one local sandbox; say which: raytrace upload logs --sandbox <name>\n${ids.map((id) => ` ${boxes[id].name} ${id}`).join('\n')}`);
33
+ return { id: ids[0], ...boxes[ids[0]] };
34
+ }
35
+ const byId = boxes[ref];
36
+ if (byId) return { id: ref, ...byId };
37
+ const byName = ids.find((id) => boxes[id].name === ref);
38
+ if (byName) return { id: byName, ...boxes[byName] };
39
+ throw new Error(`No local sandbox named ${ref}. Local sandboxes:\n${ids.map((id) => ` ${boxes[id].name} ${id}`).join('\n')}`);
40
+ }
41
+
42
+ /** A consistent gzipped snapshot of the evidences database (never the live
43
+ * WAL file itself), plus what one sandbox holds in it. */
44
+ export function snapshotEvidences(database = paths.database) {
45
+ if (!existsSync(database)) throw new Error(`No evidences recorded yet (${database} does not exist). Run an agent in a local sandbox first.`);
46
+ const dir = mkdtempSync(join(tmpdir(), 'raytrace-upload-'));
47
+ const plain = join(dir, 'evidence.db');
48
+ const source = new DatabaseSync(database, { readOnly: true });
49
+ try { source.exec(`VACUUM INTO '${plain.replaceAll("'", "''")}'`); } finally { source.close(); }
50
+ return { dir, plain };
51
+ }
52
+
53
+ /** Trims the snapshot to one sandbox, so nothing of any other sandbox or
54
+ * session leaves this machine. Only ever run on the temporary copy. */
55
+ export function keepOnlySandbox(plain, keep) {
56
+ const scratch = 'upload-unattributed';
57
+ const db = new DatabaseSync(plain);
58
+ let others;
59
+ try {
60
+ others = db.prepare('SELECT external_session_id AS id FROM agent_sessions WHERE external_session_id IS NOT NULL').all()
61
+ .map((row) => row.id).filter((id) => !keep.includes(id));
62
+ // Captures no sandbox claimed: forgetSessions finds a sandbox's by project id.
63
+ db.prepare('UPDATE runtime_sandboxes SET project_id = ? WHERE project_id IS NULL').run(scratch);
64
+ others.push(...db.prepare('SELECT DISTINCT project_id AS id FROM runtime_sandboxes WHERE project_id IS NOT NULL').all()
65
+ .map((row) => row.id).filter((id) => !keep.includes(id) && !others.includes(id)));
66
+ } finally { db.close(); }
67
+ const store = openEvidenceStore(plain);
68
+ try { store.forgetSessions(others); } finally { store.close(); }
69
+ const compact = new DatabaseSync(plain);
70
+ try { compact.exec('VACUUM'); } finally { compact.close(); }
71
+ }
72
+
73
+ export function sandboxStats(plain, sandboxId) {
74
+ const db = new DatabaseSync(plain, { readOnly: true });
75
+ try {
76
+ const row = db.prepare(`
77
+ SELECT COUNT(DISTINCT e.id) AS exchanges, COUNT(DISTINCT e.turn_id) AS turns,
78
+ MIN(e.started_at_ms) AS first, MAX(e.started_at_ms) AS last
79
+ FROM agent_sessions s LEFT JOIN agent_exchanges e ON e.session_id = s.id
80
+ WHERE s.external_session_id = ?`).get(sandboxId);
81
+ return { exchanges: row.exchanges ?? 0, turns: row.turns ?? 0, first: row.first ?? null, last: row.last ?? null };
82
+ } finally { db.close(); }
83
+ }
84
+
85
+ /** Sends the file in chunks. The server says where its copy ends, so an
86
+ * interrupted upload (this run's or an earlier one's) carries on from there. */
87
+ export async function sendChunks({ url, key, sandbox, name, file, size, sha256, onProgress = () => {}, send = fetch }) {
88
+ const handle = await open(file, 'r');
89
+ const buffer = Buffer.alloc(CHUNK);
90
+ let offset = 0;
91
+ let failures = 0;
92
+ try {
93
+ for (;;) {
94
+ const { bytesRead } = await handle.read(buffer, 0, Math.min(CHUNK, size - offset), offset);
95
+ const query = new URLSearchParams({ sandbox, name, sha256, size: String(size), offset: String(offset) });
96
+ let response;
97
+ try {
98
+ response = await send(new URL(`/v1/evidence/import?${query}`, url), {
99
+ method: 'POST', body: buffer.subarray(0, bytesRead),
100
+ headers: { authorization: `Bearer ${key}`, 'content-type': 'application/gzip' },
101
+ });
102
+ } catch (error) {
103
+ if (++failures > RETRIES) throw new Error(`Upload interrupted: ${error.message}. Run it again to continue where it stopped.`);
104
+ await new Promise((resolve) => { setTimeout(resolve, 500 * 2 ** failures); });
105
+ continue;
106
+ }
107
+ const data = await response.json().catch(() => ({}));
108
+ if (response.status === 409 && data.code === 'upload_offset') { offset = data.offset; onProgress(offset); continue; }
109
+ if (response.status >= 500 && ++failures <= RETRIES) {
110
+ await new Promise((resolve) => { setTimeout(resolve, 500 * 2 ** failures); });
111
+ continue;
112
+ }
113
+ if (!response.ok) {
114
+ const hint = data.upgrade ? '\nUpgrade: https://raytracer.si/pricing' : '';
115
+ throw new Error(`${data.error || `HTTP ${response.status}`}${hint}`);
116
+ }
117
+ failures = 0;
118
+ if (data.complete) return data;
119
+ offset = data.offset;
120
+ onProgress(offset);
121
+ }
122
+ } finally {
123
+ await handle.close();
124
+ }
125
+ }
126
+
127
+ async function api() {
128
+ const config = readConfig();
129
+ const url = process.env.RAYTRACE_API_URL || config.RAYTRACE_API_URL || API;
130
+ let key = process.env.RAYTRACE_API_KEY || config.RAYTRACE_API_KEY || await accessToken();
131
+ if (!key) {
132
+ if (!interactive()) throw new Error('Uploading evidences needs a RayTrace account. Sign in first: raytrace auth login');
133
+ say('Uploading evidences needs a RayTrace account — let us sign you in (or create your account) first.');
134
+ await login();
135
+ key = await accessToken();
136
+ if (!key) throw new Error('Not signed in. Run: raytrace auth login');
137
+ say();
138
+ }
139
+ return { url: new URL(url), key };
140
+ }
141
+
142
+ async function callJson(method, path) {
143
+ const { url, key } = await api();
144
+ const response = await fetch(new URL(path, url), { method, headers: { authorization: `Bearer ${key}` } });
145
+ const data = await response.json().catch(() => ({}));
146
+ if (!response.ok) throw new Error(data.error || `HTTP ${response.status}`);
147
+ return data;
148
+ }
149
+
150
+ export async function uploadStatus() {
151
+ const me = await callJson('GET', '/v1/me');
152
+ const plan = me.plan ?? {};
153
+ say(`Plan: ${plan.label ?? plan.plan ?? 'Free'}`);
154
+ say(`Evidences storage: ${mb(plan.storage_used_bytes ?? 0)} of ${mb(plan.storage_bytes ?? 0)} used`);
155
+ say(`Retention: ${plan.retention_days ? `${plan.retention_days} days` : 'kept only while a sandbox lives (Free)'}`);
156
+ say(`Sandboxes: up to ${plan.max_live ?? 1} live`);
157
+ const boxes = await callJson('GET', '/v1/sandboxes');
158
+ for (const box of Array.isArray(boxes) ? boxes : []) {
159
+ if (!box.traces_kept_until) continue;
160
+ const days = Math.max(0, Math.ceil((box.traces_kept_until * 1000 - Date.now()) / 86_400_000));
161
+ say(` ${box.name}: traces kept ${days} more day${days === 1 ? '' : 's'}`);
162
+ }
163
+ }
164
+
165
+ export async function uploadLogs({ sandbox: ref = null, yes = false, dryRun = false } = {}) {
166
+ const box = pickSandbox(ref);
167
+ const { dir, plain } = snapshotEvidences();
168
+ try {
169
+ keepOnlySandbox(plain, [box.id]);
170
+ const gz = `${plain}.gz`;
171
+ await pipeline(createReadStream(plain), createGzip({ level: 6 }), createWriteStream(gz, { mode: 0o600 }));
172
+ const size = (await stat(gz)).size;
173
+ const stats = sandboxStats(plain, box.id);
174
+ const day = (ms) => new Date(ms).toISOString().slice(0, 10);
175
+ say(`Sandbox ${box.name} (${box.id}): ${stats.turns} prompt${stats.turns === 1 ? '' : 's'}, ${stats.exchanges} model exchanges${stats.first ? `, ${day(stats.first)} to ${day(stats.last)}` : ''}.`);
176
+ say(`Evidences to upload: ${mb(size)} gzipped, this sandbox only. They will be readable at https://app.raytracer.si/?view=sandboxes`);
177
+ say('Credential-shaped fields are withheld when recorded. That covers named fields only: prompts and tool output can still contain secrets, with no guarantee.');
178
+ if (dryRun) { say('Dry run: nothing uploaded.'); return; }
179
+ if (!yes) {
180
+ if (!interactive()) throw new Error('Pass --yes to upload without a prompt.');
181
+ if (!/^y(es)?$/i.test((await ask('We are uploading evidences. Continue? [y/N] ')).trim())) { say('Not uploaded.'); return; }
182
+ }
183
+ const { url, key } = await api();
184
+ const sha256 = createHash('sha256');
185
+ await pipeline(createReadStream(gz), sha256);
186
+ const data = await sendChunks({
187
+ url, key, sandbox: box.id, name: box.name, file: gz, size, sha256: sha256.digest('hex'),
188
+ onProgress: (sent) => { if (process.stdout.isTTY) process.stdout.write(`\rUploading: ${mb(sent)} of ${mb(size)}`); },
189
+ });
190
+ if (process.stdout.isTTY) say();
191
+ say(`Uploaded: ${data.exchanges} exchanges for ${box.name}. Storage: ${mb(data.storage.used_bytes)} of ${mb(data.storage.limit_bytes)}.`);
192
+ if (data.kept_until) say(`Kept until ${new Date(data.kept_until * 1000).toLocaleDateString()}.`);
193
+ if (data.runtime?.error) say(`Note: ${data.runtime.error}; its prompts and tool calls did upload.`);
194
+ say('See it at https://app.raytracer.si/?view=sandboxes');
195
+ } finally {
196
+ rmSync(dir, { recursive: true, force: true });
197
+ }
198
+ }
@@ -0,0 +1,8 @@
1
+ FROM node:22-bookworm-slim
2
+ RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates python3 curl ripgrep \
3
+ && rm -rf /var/lib/apt/lists/*
4
+ RUN npm install -g @openai/codex @anthropic-ai/claude-code
5
+ RUN mkdir /workspace && chown node:node /workspace
6
+ USER node
7
+ WORKDIR /workspace
8
+ ENV HOME=/home/node CODEX_HOME=/home/node/.codex
@@ -0,0 +1,197 @@
1
+ # Syscall catalog
2
+
3
+ `syscall_catalog.sql` is a standalone, version-controlled SQLite catalog (catalog
4
+ version **2**). It has one row for every syscall name gVisor knows, 353 in all,
5
+ in eight groups: files, network, process, identity, memory, IPC, time and other.
6
+ Version 1 held the 84 file rows only; they are unchanged.
7
+
8
+ The catalog is the rulebook the sandbox host runs from:
9
+
10
+ - `setup.py` builds gVisor's trace configuration from the rows whose `capture`
11
+ is `yes` or `watcher`, so what is subscribed cannot drift from what is listed.
12
+ - `engine.py` names raw events with `syscall_numbers` and reads each captured
13
+ call with the rule its row names in `effect_rule`.
14
+
15
+ Loading the file into a database still enables nothing by itself, and changing
16
+ a row changes what is captured only after `setup.py` runs again on a host.
17
+
18
+ ## Import and query
19
+
20
+ From the repository root, create a disposable database:
21
+
22
+ ```sh
23
+ catalog_dir=$(mktemp -d)
24
+ sqlite3 "$catalog_dir/catalog.db" < worker/gvisor/syscall_catalog.sql
25
+ sqlite3 -header -column "$catalog_dir/catalog.db" \
26
+ "SELECT syscall_name, category, default_impact_level, capture, detail FROM syscall_catalog_readable WHERE syscall_name = 'unlinkat';"
27
+ ```
28
+
29
+ Expected result:
30
+
31
+ ```text
32
+ syscall_name category default_impact_level capture detail
33
+ ------------ -------- -------------------- ------- -----------
34
+ unlinkat Delete 3 watcher number_only
35
+ ```
36
+
37
+ What RayTrace captures, and how much gVisor can tell of each:
38
+
39
+ ```sh
40
+ sqlite3 -header -column "$catalog_dir/catalog.db" \
41
+ "SELECT group_id, syscall_name, capture, detail, effect_rule FROM syscall_catalog_readable WHERE capture != 'no' ORDER BY group_id, syscall_name;"
42
+ ```
43
+
44
+ The import is transactional and idempotent. Re-importing restores catalog-owned
45
+ rows using upserts and preserves unrelated rows. It does not delete removed
46
+ entries or upgrade a version 1 database; use a fresh database. Use a dedicated
47
+ database, not the application or runtime evidence database. The script does not
48
+ modify `PRAGMA user_version`.
49
+
50
+ ## Data model
51
+
52
+ | Table/view | Purpose |
53
+ | --- | --- |
54
+ | `syscall_impact_levels` | Four file impact levels and their meanings. |
55
+ | `syscall_groups` | The eight top-level groups. |
56
+ | `syscall_categories` | Stable operation identifiers, labels, and descriptions; the second level under a group. |
57
+ | `syscall_catalog` | One row per syscall name: description, group, category, nullable default level, rule identifier, required evidence, interpretation notes, the capture decision, and catalog version. |
58
+ | `syscall_numbers` | Generated. The number of each call on `x86_64` and `aarch64`, and whether gVisor implements it. |
59
+ | `syscall_coverage` | Generated. For the pinned gVisor release, whether a call has a typed trace point and with which optional fields, and what a live test observed. |
60
+ | `syscall_catalog_readable` | Joined view with group, category and impact labels, `detail` and `observed`, for inspection or export. |
61
+
62
+ | Level | Label | Meaning |
63
+ | --- | --- | --- |
64
+ | 0 | Observe | Read or inspect; sensitive reads and incidental access-time updates remain possible. |
65
+ | 1 | Create | Add an entry without replacing existing data. |
66
+ | 2 | Modify | Change contents, metadata, layout, or location. |
67
+ | 3 | Remove/replace | Remove an entry or replace an existing destination. |
68
+
69
+ Levels describe filesystem impact, **not maliciousness**. A level-0 secret read
70
+ can be concerning; a level-3 temporary-file deletion can be expected. Null means
71
+ conditional or not applicable, never level 0, and every row outside the file
72
+ group has a null level. Unknown syscall names have no row and must remain
73
+ unclassified. A recognized syscall with missing evidence may still have a known
74
+ operation category, but its actual effect stays unknown.
75
+
76
+ Names are not architecture-specific syscall numbers. For example, `newfstatat`
77
+ is a syscall name while `fstatat` is a common library interface. A listed name
78
+ need not exist on every architecture: `open`, `unlink` and `rename` have no
79
+ number on `aarch64`, where only the `*at` forms exist. Resolve numbers in
80
+ `syscall_numbers` against the execution architecture before lookup; do not
81
+ infer them from the collector host.
82
+
83
+ ## What is captured
84
+
85
+ `capture` is RayTrace's decision for each row:
86
+
87
+ | `capture` | Meaning | Rows |
88
+ | --- | --- | --- |
89
+ | `yes` | Its gVisor trace point is subscribed, with the optional fields in `capture_fields`. | `open`, `openat`, `creat`, `connect`, `listen`, `setuid`, `setgid`, `setresuid`, `setresgid` |
90
+ | `watcher` | Only its raw exit point is subscribed: which process, when, and whether it was refused. gVisor does not decode its path, so the host's file watcher supplies the name. | `unlink`, `unlinkat`, `rmdir`, `rename`, `renameat`, `renameat2`, `truncate`, `ftruncate`, `mkdir`, `mkdirat`, `chmod`, `fchmod`, `fchmodat` |
91
+ | `sentry` | Seen through gVisor's own process points (clone, exec, exit), whatever syscall caused them. | `clone`, `clone3`, `fork`, `vfork`, `execve`, `execveat`, `exit`, `exit_group` |
92
+ | `no` | Not captured. | everything else |
93
+
94
+ `read` and `write` are deliberately `no`: they are by far the most frequent
95
+ calls, and whether a file changed is settled by comparing it before and after.
96
+ Every other `no` row is there so that no call is without a group, and so the
97
+ coverage can be stated: "we read this", "we see it without its path", or "we do
98
+ not watch it".
99
+
100
+ `detail` in the view is what gVisor can tell of a call in the pinned release:
101
+ `full` (a typed point with decoded paths, flags or addresses), `number_only`
102
+ (the number and six integers) or `none` (that release has no such call, as for
103
+ `openat2`). `observed` records what a live test saw arrive and is null until
104
+ `spike_points.py` has run for the release.
105
+
106
+ ## Regenerating the generated tables
107
+
108
+ `syscall_numbers` and `syscall_coverage` come from gVisor's own source for the
109
+ release `setup.py` installs. After changing that release:
110
+
111
+ ```sh
112
+ python3 worker/gvisor/catalog_numbers.py # fetch the release, rewrite both tables
113
+ python3 worker/gvisor/catalog_numbers.py --check # change nothing; fail if a call has no row
114
+ ```
115
+
116
+ A syscall the new release has and the catalog lacks is refused until its row
117
+ is written. What a spike observed is kept for the same release and cleared for
118
+ a new one, since it has to be seen again.
119
+
120
+ ## Classification contract
121
+
122
+ The rule identifiers below are specifications. `engine.py` implements the ones
123
+ its captured rows name (`open_effect`, `remove_entry`, `rename_effect`,
124
+ `file_resize`, `directory_create`, `metadata_change`, `connect_effect`,
125
+ `listen_effect`, `identity_effect`); the others describe calls that are not
126
+ captured. Keep the raw observation, attempted operation, outcome, and confirmed
127
+ effect separate. Preserve the catalog version when persisting classifications.
128
+
129
+ Every event needs sandbox/process identity, timestamp, syscall identity, and
130
+ outcome. A missing exit result is unknown, not success. Apply the row-specific
131
+ `required_evidence` and rules only after decoding signed results and errno.
132
+
133
+ | Rule | Interpretation |
134
+ | --- | --- |
135
+ | `open_effect` | Read-only opens without mutation flags are level 0, but do not prove bytes were read. Confirmed creation is level 1; successful truncation of an existing file is level 2. Writable access alone has no confirmed mutation level. `O_CREAT` alone does not establish creation. `creat` implies `O_WRONLY\|O_CREAT\|O_TRUNC`; `openat2` requires decoding `open_how`. Successful `O_CREAT\|O_EXCL` can establish new creation. Other ambiguous cases stay unresolved. |
136
+ | `file_write` | Level 2 applies only to file targets. Positive returned bytes establish writes, not necessarily different contents or durable storage. Record actual bytes, not just requested bytes; zero-byte and failed writes do not confirm modification. Honor append/offset flags without inventing an unavailable actual offset. |
137
+ | `remove_entry` | Level 3 is the attempted operation. A successful result confirms entry removal; failure does not. `AT_REMOVEDIR` distinguishes directory deletion. Other hard links or open descriptors may retain data. |
138
+ | `rename_effect` | Confirmed non-replacing move is level 2; confirmed replacement is level 3. Unknown destination history remains unresolved. `RENAME_NOREPLACE` success excludes replacement; `RENAME_EXCHANGE` is an exchange at level 2. Same-object operations may be no-ops. `RENAME_WHITEOUT` and unsupported flag combinations stay unresolved until specifically decoded. An earlier directory scan alone is not race-free replacement evidence. |
139
+ | `file_resize` | Level 2 operation; record requested length. Success confirms a length-setting operation, not a change from an unknown prior size. |
140
+ | `directory_create` | Level 1 operation; success confirms creation. Requested mode may differ from effective permissions because of umask or ACLs. |
141
+ | `file_read` | Level 0 for file targets; positive returned bytes establish a read. Zero bytes, failures, and an open alone do not. Do not retain buffer contents. |
142
+ | `inspect` | Level 0 inspection; metadata and accessibility checks do not prove later content access. |
143
+ | `metadata_change` | Level 2 operation; success does not prove a value differed. Keep attribute names and relevant permissions/ownership/timestamps, not attribute payloads. |
144
+ | `link_create` | Level 1 entry creation; distinguish hard links from symbolic-link target text. No claim that contents were copied or the target is safe. |
145
+ | `copy_effect` | Positive transfer to a known existing file is level 2. Creation is established separately by creation evidence. Unknown targets remain unresolved; pipes and sockets are not filesystem edits. |
146
+ | `allocation_effect` | Successful, decoded file allocation/range changes are level 2. Distinguish allocation from punch-hole, zero-range, collapse-range and insert-range; allocation does not alone establish changed content. Unknown flags remain unresolved. |
147
+ | `ioctl_effect` | Decode command-specific semantics first. Supported file clone operations and attribute changes are level 2; supported inspection is level 0. Unknown commands have no default level. |
148
+ | `mapping_effect` | Record mapping capability/lifecycle, not confirmed reads or writes. `MAP_SHARED` plus writable protection permits edits but does not prove them. `msync`/`munmap` alone do not prove changed bytes. Leave confirmed impact unresolved without additional evidence. |
149
+ | `bookkeeping` | No direct filesystem impact level. Track descriptor duplication/reuse, working directories, offsets, synchronization, and command-dependent `fcntl` behavior as context. |
150
+ | `connect_effect` | Decode the address family, IP address and port. A zero result is a connection on a stream socket and only a default peer on a datagram socket. `EINPROGRESS` is an attempt whose outcome this call does not report. A destination in a range the sandbox firewall rejects is a refused attempt. The address is never a host name: a name shown beside it comes from DNS evidence and is a best match. No payload is captured. |
151
+ | `listen_effect` | Success means the process accepts connections on the bound address. Nothing outside the sandbox network is routed to it. |
152
+ | `identity_effect` | Record the requested IDs and the result. Success changes the identity the process acts as; the sandbox has no capabilities, so a successful change away from its one user is unexpected, and a failure is an attempt. |
153
+ | `process_lifecycle` | gVisor's clone, exec and exit points report every task, program start and exit, whichever syscall caused it. A successful exec proves a program started, not what it did; a zero result on the exec syscall point is not treated as success. Keep arguments as observed and, of the environment, only the two `RAYTRACE_` markers. |
154
+ | `not_classified` | The call is listed and grouped, and nothing is collected for it. No fact records its use and none rules it out. |
155
+
156
+ For example, successful `unlinkat` can display **L3 · Delete · Succeeded**;
157
+ `EACCES` can display **L3 · Delete · Failed: permission denied**. Neither label
158
+ requires a new process or PID. A failed operation must not appear in a list of
159
+ confirmed file changes.
160
+
161
+ Store the supplied pathname and directory base independently; do not label a
162
+ lexically joined path as fully resolved through symlinks. Descriptor identities
163
+ must account for reuse and inheritance. Unresolved target types/paths must stay
164
+ explicit. Preserve both source and destination for rename/link/copy events.
165
+
166
+ ## Boundaries and validation
167
+
168
+ A row is not a completeness guarantee, and a default level is not evidence of
169
+ success. What the captured set does not see:
170
+
171
+ - **Bytes read or written.** An open for reading is recorded as a read of the
172
+ file; whether a file changed comes from comparing it before and after.
173
+ - **Memory-mapped writes and `io_uring`.** Both change files without the
174
+ ordinary calls. The file still has to be opened, and the before/after
175
+ comparison still sees the change.
176
+ - **Datagrams sent without `connect`.** `sendto` and `sendmsg` name their own
177
+ destination and are not captured. The firewall still applies, and DNS is seen
178
+ by the host resolver.
179
+ - **Paths of `watcher` calls.** A refused delete or rename is known by process
180
+ and time, not by file.
181
+ - **Calls gVisor does not implement** (`support = 'unsupported'` in
182
+ `syscall_numbers`) fail inside the sandbox whatever the catalog says.
183
+
184
+ No buffer contents or environment values are required by these rules. This
185
+ catalog does not change existing evidence storage, retention, or redaction.
186
+
187
+ Run isolated validation, including repeat import and constraints:
188
+
189
+ ```sh
190
+ python3 -B -m unittest discover -s worker/gvisor -p 'test_syscall_catalog.py'
191
+ ```
192
+
193
+ Semantic references: [Linux syscall inventory](https://man7.org/linux/man-pages/man2/syscalls.2.html),
194
+ [open](https://man7.org/linux/man-pages/man2/open.2.html),
195
+ [rename](https://man7.org/linux/man-pages/man2/rename.2.html),
196
+ [memory mappings](https://man7.org/linux/man-pages/man2/mmap.2.html), and
197
+ [gVisor SecCheck](https://github.com/google/gvisor/blob/release-20260817.0/pkg/sentry/seccheck/README.md).