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,702 @@
1
+ """Trusted VM-side persistent container lifecycle. Not mounted into workloads."""
2
+ import argparse
3
+ from datetime import datetime
4
+ import fcntl
5
+ import io
6
+ import json
7
+ import os
8
+ from pathlib import Path, PurePosixPath
9
+ import re
10
+ import shutil
11
+ import stat
12
+ import struct
13
+ import subprocess
14
+ import sys
15
+ import tarfile
16
+ import time
17
+
18
+ LABEL = 'io.raytace.project'
19
+ FORK_OF = 'io.raytace.fork-of'
20
+ PROJECT_ID = r'rtp-[a-f0-9]{32}'
21
+ FORK_ID = r'rtf-[a-f0-9]{32}'
22
+ SNAPSHOTS = '/home/node/.raytace/snapshots.git'
23
+ # Each sandbox's Claude Code hook, as enable-claude last installed it, root-only.
24
+ HOOKS = Path('/var/lib/raytace/hooks')
25
+ # Each sandbox's restricted files, as set-guardrails last left them, root-only.
26
+ GUARDRAILS = Path('/var/lib/raytace/guardrails')
27
+ GUARDRAILS_IN_SANDBOX = '/opt/raytace-claude/guardrails.json'
28
+ # Which sandbox each container is, for the fact engine (engine.py), root-only.
29
+ CONTAINERS = Path('/var/lib/raytace/containers')
30
+ # The file attribute `chattr +i` sets, and the calls that read and write it.
31
+ IMMUTABLE, GET_FLAGS, SET_FLAGS = 0x10, 0x80086601, 0x40086602
32
+
33
+ def bridge():
34
+ # The manager's model and transcript bridge as sandboxes reach it (network.py).
35
+ path = Path('/etc/raytace/bridge')
36
+ return path.read_text().strip() if path.exists() else 'http://192.168.5.2:8799'
37
+
38
+ def run(*args, **kwargs):
39
+ return subprocess.run(args, check=True, **kwargs)
40
+
41
+ def inspect(name):
42
+ if not re.fullmatch(PROJECT_ID, name) and not re.fullmatch(FORK_ID, name):
43
+ raise ValueError('Invalid sandbox ID')
44
+ data = json.loads(subprocess.check_output(['docker', 'inspect', name]))[0]
45
+ if data['Config'].get('Labels', {}).get(LABEL) != name:
46
+ raise ValueError('Container is not a managed RayTrace project')
47
+ if data['HostConfig']['Runtime'] != 'raytace-gvisor':
48
+ raise ValueError('Unexpected runtime; refusing operation')
49
+ return data
50
+
51
+ def preflight():
52
+ # No sandbox runs unrecorded, or with names it cannot resolve.
53
+ for unit, does in (('raytace-collector', 'records what a sandbox runs'), ('raytace-dns', 'resolves names for sandboxes')):
54
+ if subprocess.run(['systemctl', 'is-active', '--quiet', unit]).returncode:
55
+ sys.exit(f'RayTrace: {unit}, which {does}, is not running on this host; no sandbox is started without it.')
56
+ run('python3', '/opt/raytace/network.py')
57
+
58
+ def remember(name):
59
+ """Tells the fact engine which sandbox a container is: where its project
60
+ and home folders are on this host and, once it runs, its address on the
61
+ sandbox network (which is how a DNS lookup is known to be its own). gVisor
62
+ names a container by its id alone, so without this the engine sees calls
63
+ and cannot tell whose files they are. Written again at every start: the
64
+ address is given then."""
65
+ state = inspect(name)
66
+ mount = lambda suffix: subprocess.check_output(['docker', 'volume', 'inspect', '-f', '{{.Mountpoint}}', name+'-'+suffix], text=True).strip()
67
+ addresses = [joined.get('IPAddress') for joined in (state.get('NetworkSettings', {}).get('Networks') or {}).values()]
68
+ record = {'id': name, 'workspace': mount('workspace'), 'home': mount('home'),
69
+ 'ip': next(filter(None, addresses), None), 'fork_of': state['Config'].get('Labels', {}).get(FORK_OF)}
70
+ CONTAINERS.mkdir(parents=True, exist_ok=True, mode=0o700)
71
+ staged = CONTAINERS / (state['Id']+'.new')
72
+ staged.write_text(json.dumps(record))
73
+ staged.replace(CONTAINERS / (state['Id']+'.json'))
74
+
75
+ def predates_collector(state):
76
+ """Whether a running sandbox started before the collector did. gVisor
77
+ connects to the collector once, at start, and never reconnects, so such a
78
+ sandbox reports nothing: its commands would run unrecorded."""
79
+ if not state['State']['Running']:
80
+ return False
81
+ shown = subprocess.check_output(['systemctl', 'show', 'raytace-collector', '-p', 'ActiveEnterTimestamp',
82
+ '--timestamp=unix'], text=True).strip()
83
+ collector = float(shown.partition('@')[2] or 0)
84
+ # Docker's RFC 3339 time, nanoseconds cut to what fromisoformat reads.
85
+ started = re.sub(r'(\.\d{6})\d*', r'\1', state['State']['StartedAt']).replace('Z', '+00:00')
86
+ return datetime.fromisoformat(started).timestamp() < collector
87
+
88
+ def validate_archive(path):
89
+ total = 0
90
+ with tarfile.open(path, 'r:gz') as archive:
91
+ for item in archive:
92
+ parts = PurePosixPath(item.name)
93
+ if parts.is_absolute() or '..' in parts.parts or not item.isfile():
94
+ raise ValueError('Archive contains unsafe path or non-regular file')
95
+ total += item.size
96
+ if total > 256 * 1024 * 1024:
97
+ raise ValueError('Import exceeds 256 MiB')
98
+
99
+ def stage_archive(sid):
100
+ """The import archive from stdin, written once to /tmp/<id>.tar.gz."""
101
+ path = '/tmp/'+sid+'.tar.gz'
102
+ limit = 300 * 1024 * 1024
103
+ with open(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'wb') as out:
104
+ total = 0
105
+ while chunk := sys.stdin.buffer.read(1024 * 1024):
106
+ total += len(chunk)
107
+ if total > limit:
108
+ raise ValueError('Import archive exceeds 300 MiB')
109
+ out.write(chunk)
110
+ return path
111
+
112
+ # Codex the same: no approval prompts, and none of its own sandboxing, which
113
+ # the sandbox already is (and gVisor would not let it set up).
114
+ # What `shell --agent` starts: the agent's name and its command line.
115
+ AGENTS = {'claude': ('Claude Code', 'claude --dangerously-skip-permissions'),
116
+ 'codex': ('Codex', 'codex --dangerously-bypass-approvals-and-sandbox')}
117
+ CODEX_MANAGED = b'approval_policy = "never"\nsandbox_mode = "danger-full-access"\n'
118
+
119
+ def install_claude_hooks(container, hook):
120
+ """The hook script, root-owned, with Claude Code's managed settings, which
121
+ user and project settings cannot override, and Codex's managed config: the
122
+ agent can read them, not change them. Re-running replaces them with the
123
+ current version."""
124
+ if not 0 < len(hook) <= 262144:
125
+ raise ValueError('Expected the hook script')
126
+ command = 'node /opt/raytace-claude/hook.mjs'
127
+ # No permission prompts for any Claude Code session here: the sandbox is
128
+ # what contains the agent, and the hook still refuses restricted files.
129
+ settings = json.dumps({'permissions': {'defaultMode': 'bypassPermissions'}, 'skipDangerousModePermissionPrompt': True, 'hooks': {
130
+ # Bash for the call id; the file tools so an edit to a restricted file is refused (see guardrails()).
131
+ 'PreToolUse': [{'matcher': 'Bash|Write|Edit|MultiEdit|NotebookEdit', 'hooks': [{'type': 'command', 'command': command, 'timeout': 5}]}],
132
+ **{event: [{**({'matcher': '*'} if event == 'PostToolUse' else {}),
133
+ 'hooks': [{'type': 'command', 'command': command, 'timeout': 15}]}]
134
+ for event in ('UserPromptSubmit', 'PostToolUse', 'Stop', 'SubagentStop', 'SessionEnd')}}}, indent=2).encode()
135
+ # Written by root from inside the container: docker cp does not keep
136
+ # owners under gVisor, and a node-owned hook is one the agent can edit.
137
+ # Needs the container running. Files an older install left node-owned
138
+ # are emptied by node, then their directories removed by root.
139
+ subprocess.run(['docker', 'exec', '-u', '1000', container, 'sh', '-c',
140
+ 'rm -rf /opt/raytace-claude/* /etc/claude-code/* /etc/codex/*'], stderr=subprocess.DEVNULL)
141
+ for path, content in (('/opt/raytace-claude/hook.mjs', hook), ('/etc/claude-code/managed-settings.json', settings),
142
+ ('/etc/codex/managed_config.toml', CODEX_MANAGED)):
143
+ write_as_root(container, path, content)
144
+
145
+ def write_as_root(container, path, content):
146
+ """A root-owned file inside a running sandbox, which its agent can read and not change."""
147
+ directory = path.rsplit('/', 1)[0]
148
+ run('docker', 'exec', '-i', '-u', '0', container, 'sh', '-c',
149
+ f'if [ -O {directory} ]; then :; else rm -rf {directory}; fi; mkdir -p -m 755 {directory} && '
150
+ f'cat > {path}.new && chmod 644 {path}.new && mv {path}.new {path}', input=content)
151
+
152
+ def lock(root, path, on):
153
+ """Locks or unlocks one project file from the host, or with on=None only
154
+ looks. Locked is root's, read-only and immutable: nothing in the sandbox
155
+ can write, replace, rename or delete it, whatever tool tries, and it still
156
+ reads. Returns whether the file is now locked. The agent names its own
157
+ folders, so every step of the path is opened without following links: a
158
+ link out of the project is never touched."""
159
+ at = os.open(root, os.O_RDONLY | os.O_DIRECTORY)
160
+ try:
161
+ parts = PurePosixPath(path).parts
162
+ for index, part in enumerate(parts):
163
+ last = index == len(parts) - 1
164
+ below = os.open(part, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | (0 if last else os.O_DIRECTORY), dir_fd=at)
165
+ os.close(at)
166
+ at = below
167
+ mode = os.fstat(at).st_mode
168
+ if not stat.S_ISREG(mode):
169
+ return False
170
+ flags = struct.unpack('i', fcntl.ioctl(at, GET_FLAGS, struct.pack('i', 0)))[0]
171
+ locked = bool(flags & IMMUTABLE)
172
+ if on is None or on == locked:
173
+ return locked
174
+ runs = mode & 0o111
175
+ if on:
176
+ os.fchown(at, 0, 0)
177
+ os.fchmod(at, 0o555 if runs else 0o444)
178
+ fcntl.ioctl(at, SET_FLAGS, struct.pack('i', flags | IMMUTABLE))
179
+ else:
180
+ fcntl.ioctl(at, SET_FLAGS, struct.pack('i', flags & ~IMMUTABLE))
181
+ os.fchown(at, 1000, 1000)
182
+ os.fchmod(at, 0o755 if runs else 0o644)
183
+ return on
184
+ except OSError:
185
+ return False
186
+ finally:
187
+ os.close(at)
188
+
189
+ def guardrails(sid, state, restricted=None, watched=None):
190
+ """Applies a sandbox's restricted files: the new list, or the stored one
191
+ again. The Claude Code hook gets the list at once and refuses the edit
192
+ with the reason. The lock that holds for every tool is put on only while
193
+ the sandbox is stopped, so from its next start: gVisor keeps what it knows
194
+ of a file while it runs, and a file locked under it stops being readable.
195
+ A file no longer restricted is unlocked now. `watched` are the files whose
196
+ owner wants to hear of a read or a change: the hook reports an attempt on
197
+ them and nothing is locked. Returns {hook: the hook has the list,
198
+ read_only: the files locked}."""
199
+ GUARDRAILS.mkdir(parents=True, exist_ok=True, mode=0o700)
200
+ stored = GUARDRAILS / (sid+'.json')
201
+ kept = json.loads(stored.read_text()) if stored.exists() else {}
202
+ before = kept.get('restricted', [])
203
+ if restricted is None:
204
+ restricted = before
205
+ if watched is None:
206
+ watched = kept.get('watched', [])
207
+ root = subprocess.check_output(['docker', 'volume', 'inspect', '-f', '{{.Mountpoint}}', sid+'-workspace'], text=True).strip()
208
+ running = state['State']['Running']
209
+ for path in set(before) - set(restricted):
210
+ lock(root, path, False)
211
+ read_only = [path for path in restricted if lock(root, path, None if running else True)]
212
+ lists = json.dumps({'restricted': restricted, 'watched': watched})
213
+ stored.write_text(lists)
214
+ if running and (restricted or before or watched or kept.get('watched')):
215
+ write_as_root(sid, GUARDRAILS_IN_SANDBOX, lists.encode())
216
+ return {'hook': bool(running), 'read_only': read_only}
217
+
218
+ def as_node(container, *command, data=None, check=True):
219
+ """Runs a command in a sandbox as its agent user, never root."""
220
+ return subprocess.run(['docker', 'exec', *(['-i'] if data is not None else []), '-u', '1000', container, *command],
221
+ input=data, check=check, capture_output=True).stdout
222
+
223
+ def start_container(name):
224
+ """docker exec needs a running container. A sandbox stopped since it
225
+ was recorded (host restart, idle stop) is started again for the work
226
+ below; starting one that already runs is a no-op."""
227
+ run('docker', 'start', name, stdout=subprocess.DEVNULL)
228
+
229
+ def fork_container(fork, parent):
230
+ """A sandbox like the project's own, for one Playground fork: same image,
231
+ limits and network, its own volumes, labelled with the project it forks."""
232
+ labels = ['--label', LABEL+'='+fork, '--label', FORK_OF+'='+parent]
233
+ for suffix in ('workspace', 'home'):
234
+ run('docker', 'volume', 'create', *labels, fork+'-'+suffix, stdout=subprocess.DEVNULL)
235
+ return subprocess.check_output(['docker', 'create', '--name', fork, *labels, '--runtime=raytace-gvisor',
236
+ '--label', 'io.raytace.storage=volumes-v1',
237
+ '--network=raytace-egress', '--cap-drop=ALL', '--security-opt=no-new-privileges',
238
+ '--user=1000:1000', '--memory=2g', '--cpus=2', '--pids-limit=256',
239
+ '--tmpfs=/tmp:rw,nosuid,nodev,size=512m',
240
+ '--mount=type=volume,src='+fork+'-workspace,dst=/workspace',
241
+ '--mount=type=volume,src='+fork+'-home,dst=/home/node',
242
+ '--mount=type=bind,src=/etc/raytace/resolv.conf,dst=/etc/resolv.conf,readonly',
243
+ '--env', 'RAYTRACE_SESSION='+fork, '--env', 'RAYTRACE_BROKER='+bridge(),
244
+ '--workdir=/workspace', '--entrypoint=/bin/sleep',
245
+ 'raytace-gvisor-agent', 'infinity'], text=True).strip()
246
+
247
+ def fork_state(fork):
248
+ state = inspect(fork)
249
+ parent = state['Config'].get('Labels', {}).get(FORK_OF, '')
250
+ if not re.fullmatch(FORK_ID, fork) or not re.fullmatch(PROJECT_ID, parent):
251
+ raise ValueError('Not a Playground fork')
252
+ return state, parent
253
+
254
+ def safe_path(path):
255
+ parts = PurePosixPath(path)
256
+ if not path or len(path) > 1024 or parts.is_absolute() or '..' in parts.parts or '\0' in path:
257
+ raise ValueError('Invalid workspace path: ' + path[:80])
258
+ return '/workspace/' + str(parts)
259
+
260
+ def fork_action(action, fork, forget=False):
261
+ if not re.fullmatch(FORK_ID, fork):
262
+ raise ValueError('Invalid fork ID')
263
+ if action == 'fork-create':
264
+ # stdin: {parent, commit, session, transcript, files: {path: text}, delete: [path], hook}
265
+ data = json.loads(sys.stdin.buffer.read(40 * 1024 * 1024))
266
+ parent, commit, session = data['parent'], data['commit'], data['session']
267
+ if not re.fullmatch(PROJECT_ID, parent) or not re.fullmatch(r'[0-9a-f]{40}', commit) \
268
+ or not re.fullmatch(r'[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}', session):
269
+ raise ValueError('Invalid fork request')
270
+ inspect(parent)
271
+ preflight()
272
+ cid = fork_container(fork, parent)
273
+ run('docker', 'start', fork, stdout=subprocess.DEVNULL)
274
+ remember(fork)
275
+ # The parent is read from below, so it must be running too: it is
276
+ # often stopped by fork time, and exec into it exits 1.
277
+ start_container(parent)
278
+ # The project folder as the snapshot has it, and nothing else.
279
+ archive = as_node(parent, 'git', '--git-dir='+SNAPSHOTS, 'archive', '--format=tar', commit)
280
+ as_node(fork, 'tar', '-x', '-C', '/workspace', data=archive)
281
+ # The user's Claude Code sign-in and the sandbox's RayTrace token (a
282
+ # local sandbox keeps it in .raytace/sandbox-token, a hosted one in its Codex config).
283
+ wanted = ['.claude/.credentials.json', '.claude.json', '.claude/settings.json', '.raytace/sandbox-token', '.raytace-codex/config.toml']
284
+ present = [path for path in wanted if subprocess.run(['docker', 'exec', '-u', '1000', parent, 'test', '-f', '/home/node/'+path]).returncode == 0]
285
+ if present:
286
+ as_node(fork, 'tar', '-x', '-C', '/home/node', data=as_node(parent, 'tar', '-c', '-C', '/home/node', *present))
287
+ # The session cut at the forked step, where `claude --resume` finds it.
288
+ as_node(fork, 'sh', '-c', 'mkdir -p "$(dirname "$1")" && cat > "$1"', 'sh',
289
+ '/home/node/.claude/projects/-workspace/'+session+'.jsonl', data=data['transcript'].encode())
290
+ for path, text in (data.get('files') or {}).items():
291
+ as_node(fork, 'sh', '-c', 'mkdir -p "$(dirname "$1")" && cat > "$1"', 'sh', safe_path(path), data=text.encode())
292
+ # Excluded files: not in the fork's copy of the project at all.
293
+ for path in (data.get('delete') or [])[:200]:
294
+ as_node(fork, 'rm', '-rf', '--', safe_path(path))
295
+ install_claude_hooks(fork, data['hook'].encode())
296
+ print(json.dumps({'container_id': cid}))
297
+ elif action == 'fork-run':
298
+ # stdin: {session, model, prompt}. Claude's stream-json events go to stdout.
299
+ state, parent = fork_state(fork)
300
+ data = json.loads(sys.stdin.buffer.read(65536))
301
+ if not re.fullmatch(r'[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}', data['session']) \
302
+ or not re.fullmatch(r'[A-Za-z0-9_.:/\[\]-]{1,100}', data['model']) or not 0 < len(data['prompt']) <= 4000:
303
+ raise ValueError('Invalid run request')
304
+ # gVisor is the sandbox, as for the project's own session.
305
+ sys.exit(subprocess.call(['docker', 'exec', '-u', '1000', '-w', '/workspace', fork,
306
+ 'claude', '-p', '--resume', data['session'], '--model', data['model'],
307
+ '--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose', data['prompt']]))
308
+ elif action == 'fork-check':
309
+ # stdin: {command, seconds}. The user's pass/fail check, run where the
310
+ # fork left the project, as the agent user: exit 0 passes. Prints
311
+ # {exit_code, timed_out, output (its last 20 KB, stdout and stderr)}.
312
+ state, parent = fork_state(fork)
313
+ data = json.loads(sys.stdin.buffer.read(65536))
314
+ command, seconds = data.get('command'), data.get('seconds')
315
+ if not isinstance(command, str) or not 0 < len(command) <= 2000 or not isinstance(seconds, int) or not 0 < seconds <= 1800:
316
+ raise ValueError('Invalid check request')
317
+ # timeout(1) inside the sandbox, so the check's own processes end with
318
+ # it, not only the docker exec client; -k for one that ignores TERM.
319
+ result = subprocess.run(['docker', 'exec', '-u', '1000', '-w', '/workspace', fork,
320
+ 'timeout', '-k', '5', str(seconds), 'sh', '-c', command], stdin=subprocess.DEVNULL,
321
+ stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
322
+ output = result.stdout[-20000:].decode('utf-8', 'replace')
323
+ print(json.dumps({'exit_code': result.returncode, 'timed_out': result.returncode in (124, 137), 'output': output}))
324
+ elif action == 'fork-collect':
325
+ # stdin: {original}. The fork's snapshot history goes into the project's
326
+ # own (refs/forks/<id>/*), so its files outlive the fork, and its last
327
+ # snapshot is compared with the original run's last one.
328
+ state, parent = fork_state(fork)
329
+ data = json.loads(sys.stdin.buffer.read(4096))
330
+ if not re.fullmatch(r'[0-9a-f]{40}', data['original']):
331
+ raise ValueError('Invalid original commit')
332
+ # Both containers are read from below; either may have stopped
333
+ # since the run (see start_container).
334
+ start_container(parent)
335
+ start_container(fork)
336
+ # A fork that answered without a tool call never snapshots, so its
337
+ # store has no refs (or does not exist) and `git bundle` exits 128
338
+ # there. That is a fork with nothing to collect, not a failure:
339
+ # report no final snapshot and let the fork's check still run.
340
+ refs = as_node(fork, 'git', '--git-dir='+SNAPSHOTS, 'for-each-ref', '--format=%(refname)', check=False)
341
+ if not refs.strip():
342
+ print(json.dumps({'final': None, 'changes': []}))
343
+ return
344
+ bundle = as_node(fork, 'sh', '-c', 'git --git-dir="$1" bundle create - --all 2>/dev/null', 'sh', SNAPSHOTS)
345
+ if not bundle:
346
+ print(json.dumps({'final': None, 'changes': []}))
347
+ return
348
+ as_node(parent, 'sh', '-c', 'cat > /tmp/fork.bundle && git --git-dir="$1" fetch -q /tmp/fork.bundle "+refs/heads/*:refs/forks/$2/*"; '
349
+ 'status=$?; rm -f /tmp/fork.bundle; exit $status', 'sh', SNAPSHOTS, fork, data=bundle)
350
+ final = as_node(parent, 'sh', '-c', 'git --git-dir="$1" for-each-ref --format="%(objectname)" "refs/forks/$2/"', 'sh', SNAPSHOTS, fork).decode().split()[0]
351
+ stats = as_node(parent, 'git', '--git-dir='+SNAPSHOTS, 'diff', '--no-renames', '-z', '--numstat', data['original'], final).decode()
352
+ statuses = as_node(parent, 'git', '--git-dir='+SNAPSHOTS, 'diff', '--no-renames', '-z', '--name-status', data['original'], final).decode().split('\0')
353
+ counts = {}
354
+ for entry in filter(None, stats.split('\0')):
355
+ added, removed, path = entry.split('\t', 2)
356
+ counts[path] = (None if added == '-' else int(added), None if removed == '-' else int(removed))
357
+ changes = [{'path': statuses[i + 1], 'status': statuses[i], 'added': counts.get(statuses[i + 1], (None, None))[0],
358
+ 'removed': counts.get(statuses[i + 1], (None, None))[1]} for i in range(0, len(statuses) - 1, 2) if statuses[i]]
359
+ print(json.dumps({'final': final, 'changes': changes[:500]}))
360
+ elif action == 'fork-stop':
361
+ # Kept for looking around, not running: stops whatever is still going.
362
+ fork_state(fork)
363
+ subprocess.run(['docker', 'stop', '-t', '3', fork], stdout=subprocess.DEVNULL, check=True)
364
+ print(json.dumps({'stopped': fork}))
365
+ elif action == 'fork-delete':
366
+ # Only ever a fork: fork_state refuses anything without the fork label.
367
+ state, parent = fork_state(fork)
368
+ subprocess.run(['docker', 'rm', '-f', fork], stdout=subprocess.DEVNULL, check=True)
369
+ (CONTAINERS / (state['Id']+'.json')).unlink(missing_ok=True)
370
+ # With --forget-evidence (its project destroyed with its logs), what the collector recorded of it too.
371
+ if forget:
372
+ evidence(state['Id'], forget=True)
373
+ for suffix in ('workspace', 'home'):
374
+ volume = fork+'-'+suffix
375
+ result = subprocess.run(['docker', 'volume', 'inspect', volume], capture_output=True, text=True)
376
+ if result.returncode == 0:
377
+ if json.loads(result.stdout)[0].get('Labels', {}).get(FORK_OF) != parent:
378
+ raise ValueError('Unexpected volume ownership; volume retained')
379
+ run('docker', 'volume', 'rm', volume, stdout=subprocess.DEVNULL)
380
+ print(json.dumps({'deleted': fork}))
381
+
382
+ SNAPSHOT_REF = r'[0-9a-f]{40}|refs/forks/rtf-[a-f0-9]{32}/[A-Za-z0-9_-]{1,40}'
383
+
384
+ def snapshot_read(project):
385
+ """Read-only views of a project's snapshot history, for the Playground:
386
+ stdin {op: list|show|diff, commit, to?, path?}. Never writes."""
387
+ data = json.loads(sys.stdin.buffer.read(8192))
388
+ op, commit = data.get('op'), data.get('commit', '')
389
+ if op not in ('list', 'show', 'diff') or not re.fullmatch(SNAPSHOT_REF, commit) \
390
+ or (op == 'diff' and not re.fullmatch(SNAPSHOT_REF, data.get('to', ''))):
391
+ raise ValueError('Invalid snapshot request')
392
+ path = safe_path(data['path'])[len('/workspace/'):] if data.get('path') else None
393
+ git = ['git', '--git-dir='+SNAPSHOTS]
394
+ if op == 'list':
395
+ names = as_node(project, *git, 'ls-tree', '-r', '-z', '--name-only', commit).decode().split('\0')
396
+ print(json.dumps({'files': [name for name in names if name][:20000]}))
397
+ elif op == 'show':
398
+ if not path:
399
+ raise ValueError('A path is required')
400
+ result = subprocess.run(['docker', 'exec', '-u', '1000', project, *git, 'show', commit+':'+path], capture_output=True)
401
+ if result.returncode != 0:
402
+ print(json.dumps({'missing': True}))
403
+ return
404
+ content = result.stdout
405
+ binary = b'\0' in content[:8000]
406
+ print(json.dumps({'binary': binary, 'size': len(content), 'truncated': len(content) > 1_000_000,
407
+ 'text': None if binary else content[:1_000_000].decode('utf-8', 'replace')}))
408
+ else:
409
+ text = as_node(project, *git, 'diff', '--no-renames', '--no-color', commit, data['to'], *(['--', path] if path else [])).decode('utf-8', 'replace')
410
+ print(json.dumps({'diff': text[:500_000], 'truncated': len(text) > 500_000}))
411
+
412
+ def read_snapshot(project, running):
413
+ """snapshot_read for a project in whatever state it was found.
414
+
415
+ The snapshot history lives inside the sandbox, so reading it needs the
416
+ container up. A stopped one is started for the read and stopped again
417
+ after: looking at an old run's diff must not need its owner to start the
418
+ sandbox first, and must not leave it running behind their back either
419
+ (no agent runs in between, so nothing is recorded or changed). A failed
420
+ read leaves as one plain sentence, not a traceback: the line reaches a
421
+ dashboard, whose reader cannot act on a raw docker command."""
422
+ try:
423
+ if running:
424
+ return snapshot_read(project)
425
+ run('docker', 'start', project, stdout=subprocess.DEVNULL)
426
+ try:
427
+ return snapshot_read(project)
428
+ finally:
429
+ try:
430
+ run('docker', 'stop', '-t', '10', project, stdout=subprocess.DEVNULL)
431
+ except subprocess.CalledProcessError:
432
+ pass # left running; the read's own outcome is what matters
433
+ except subprocess.CalledProcessError:
434
+ raise SystemExit("RayTrace: this sandbox's snapshot history could not be read.") from None
435
+
436
+ def create(opts, parser):
437
+ if not opts.archive or not re.fullmatch(r'/tmp/rtp-[a-f0-9]{32}\.tar\.gz', opts.archive):
438
+ parser.error('Expected staged import archive')
439
+ validate_archive(opts.archive)
440
+ preflight()
441
+ for suffix in ('workspace','home'):
442
+ run('docker','volume','create','--label',LABEL+'='+opts.id,opts.id+'-'+suffix,stdout=subprocess.DEVNULL)
443
+ cid = subprocess.check_output(['docker', 'create', '--name', opts.id,
444
+ '--label', LABEL+'='+opts.id, '--runtime=raytace-gvisor',
445
+ '--label', 'io.raytace.storage=volumes-v1',
446
+ '--network=raytace-egress', '--cap-drop=ALL', '--security-opt=no-new-privileges',
447
+ '--user=1000:1000', '--memory=2g', '--cpus=2', '--pids-limit=256',
448
+ '--tmpfs=/tmp:rw,nosuid,nodev,size=512m',
449
+ '--mount=type=volume,src='+opts.id+'-workspace,dst=/workspace',
450
+ '--mount=type=volume,src='+opts.id+'-home,dst=/home/node',
451
+ '--mount=type=bind,src=/etc/raytace/resolv.conf,dst=/etc/resolv.conf,readonly',
452
+ # Session marker on PID 1: env is inherited across fork/exec, so
453
+ # every process in this sandbox carries it without the collector
454
+ # reconstructing a process tree. Read back by the allowlist in
455
+ # collector.py. Session scope only -- a per-call RAYTRACE_CALL_ID
456
+ # has to be stamped by whatever spawns the command, and inside
457
+ # this sandbox that is Codex, not RayTrace.
458
+ '--env', 'RAYTRACE_SESSION='+opts.id, '--env', 'RAYTRACE_BROKER='+bridge(),
459
+ '--workdir=/workspace', '--entrypoint=/bin/sleep',
460
+ 'raytace-gvisor-agent', 'infinity'], text=True).strip()
461
+ # docker cp -a honors the deliberately normalized uid/gid in this tar.
462
+ with tarfile.open(opts.archive, 'r:gz') as source:
463
+ with io.BytesIO() as buffer:
464
+ with tarfile.open(fileobj=buffer, mode='w') as dest:
465
+ made = set()
466
+ for item in source:
467
+ # The upload holds files only. Without its folders named here, docker
468
+ # would make them root's, and the agent could add nothing inside them.
469
+ for parent in reversed(PurePosixPath(item.name).parents[:-1]):
470
+ if str(parent) not in made:
471
+ made.add(str(parent))
472
+ folder = tarfile.TarInfo(str(parent))
473
+ folder.type, folder.mode = tarfile.DIRTYPE, 0o755
474
+ folder.uid = folder.gid = 1000
475
+ folder.uname = folder.gname = 'node'
476
+ folder.mtime = item.mtime
477
+ dest.addfile(folder)
478
+ item.uid = item.gid = 1000
479
+ item.uname = item.gname = 'node'
480
+ item.mode = 0o755 if item.mode & 0o111 else 0o644
481
+ # Names, sizes and modes only: no extended attributes or other pax records.
482
+ item.pax_headers = {}
483
+ dest.addfile(item, source.extractfile(item))
484
+ run('docker', 'cp', '-a', '-', cid+':/workspace', input=buffer.getvalue())
485
+ remember(opts.id)
486
+ print(cid)
487
+
488
+ RUNTIME_DB = '/var/lib/raytace/runtime.db'
489
+
490
+ def evidence(container, forget=False):
491
+ """What the collector recorded for one sandbox's container: its process
492
+ events and the fact engine's file and network facts. Printed as JSON lines,
493
+ or with `forget` deleted, for when its owner destroys it with its logs.
494
+ Called once the sandbox is stopped: its last events (its exit, the
495
+ connection closing) come just after, and the collector commits every
496
+ quarter second, so they are waited for."""
497
+ import sqlite3
498
+ time.sleep(1.5)
499
+ if not Path(RUNTIME_DB).exists():
500
+ return
501
+ with sqlite3.connect(RUNTIME_DB, timeout=30) as db:
502
+ tables = {name for (name,) in db.execute("SELECT name FROM sqlite_master WHERE type='table'")}
503
+ if 'capture_streams' in tables:
504
+ if forget:
505
+ db.execute('DELETE FROM capture_streams WHERE container_id=?', (container,))
506
+ else:
507
+ for row in db.execute('SELECT id,collector_id,started_ms,ended_ms,heartbeat_ms,dropped,errors,capabilities_json FROM capture_streams WHERE container_id=?', (container,)):
508
+ names=('id','collector_id','started_ms','ended_ms','heartbeat_ms','dropped','errors','capabilities')
509
+ body=dict(zip(names,row)); body['capabilities']=json.loads(body['capabilities'])
510
+ print(json.dumps({'table':'capture_streams','body':body}))
511
+ for table, columns in (('runtime_events', 'kind, received_ms, body'), ('facts', 'kind, at_ns, received_ms, body')):
512
+ if table not in tables:
513
+ continue
514
+ if forget:
515
+ db.execute(f'DELETE FROM {table} WHERE container_id = ?', (container,))
516
+ continue
517
+ names = [column.strip() for column in columns.split(',')]
518
+ for row in db.execute(f'SELECT {columns} FROM {table} WHERE container_id = ? ORDER BY id', (container,)):
519
+ record = dict(zip(names, row))
520
+ record['body'] = json.loads(record['body'])
521
+ print(json.dumps({'table': table, **record}))
522
+
523
+ # What the dashboard calls each kind of fact, and how many of each it is shown.
524
+ FACT_KINDS = {'file': 'files', 'network': 'network', 'dns': 'lookups', 'package': 'packages', 'identity': 'identity', 'summary': 'bulk'}
525
+ FACT_LIMITS = {'file': 500, 'network': 500, 'dns': 300, 'package': 100, 'identity': 100, 'summary': 100}
526
+
527
+ def activity(container, since_ms=0, until_ms=0):
528
+ """What the fact engine saw one sandbox do, newest first, by kind -- the
529
+ shape RayTrace's hosted dashboard reads -- each list capped, with `more`
530
+ naming the kinds that were. since/until (epoch ms) scope it to one prompt."""
531
+ import sqlite3
532
+ found, more = {name: [] for name in FACT_KINDS.values()}, []
533
+ if not Path(RUNTIME_DB).exists():
534
+ return {**found, 'more': more}
535
+ where, args = ['container_id = ?', 'kind = ?'], [container]
536
+ if since_ms:
537
+ where.append('CAST(at_ns AS INTEGER) >= ?'); args.append(since_ms * 1_000_000)
538
+ if until_ms:
539
+ where.append('CAST(at_ns AS INTEGER) <= ?'); args.append(until_ms * 1_000_000)
540
+ with sqlite3.connect(f'file:{RUNTIME_DB}?mode=ro', uri=True, timeout=30) as db:
541
+ if not db.execute("SELECT 1 FROM sqlite_master WHERE name = 'facts'").fetchone():
542
+ return {**found, 'more': more}
543
+ for kind, name in FACT_KINDS.items():
544
+ limit = FACT_LIMITS[kind]
545
+ rows = db.execute('SELECT fact_id, at_ns, body FROM facts WHERE ' + ' AND '.join(where) + ' ORDER BY id DESC LIMIT ?',
546
+ (args[0], kind, *args[1:], limit + 1)).fetchall()
547
+ for fact_id, at_ns, body in rows[:limit]:
548
+ fact = json.loads(body)
549
+ last = fact.get('last_ns') or at_ns
550
+ try:
551
+ at = int(last) / 1e9
552
+ except (TypeError, ValueError):
553
+ at = None
554
+ found[name].append({**fact, 'id': fact_id, 'at': at})
555
+ if len(rows) > limit:
556
+ more.append(name)
557
+ return {**found, 'more': more}
558
+
559
+ def main():
560
+ parser = argparse.ArgumentParser()
561
+ parser.add_argument('action', choices=['create', 'list', 'start', 'shell', 'stop', 'delete', 'set-token', 'enable-claude', 'evidence', 'activity',
562
+ 'fork-create', 'fork-run', 'fork-check', 'fork-collect', 'fork-stop', 'fork-delete', 'snapshot',
563
+ 'set-guardrails', 'guardrails'])
564
+ parser.add_argument('id', nargs='?')
565
+ parser.add_argument('--archive')
566
+ parser.add_argument('--confirm')
567
+ parser.add_argument('--since', type=int, default=0, help='activity: from this epoch ms')
568
+ parser.add_argument('--until', type=int, default=0, help='activity: up to this epoch ms')
569
+ parser.add_argument('--forget-evidence', action='store_true', help='delete: also delete what the collector recorded for it')
570
+ parser.add_argument('--agent', choices=sorted(AGENTS), help='shell: start this agent first, without approval prompts; its exit leaves the shell')
571
+ opts = parser.parse_args()
572
+ if opts.action == 'list':
573
+ ids = subprocess.check_output(['docker', 'ps', '-aq', '--filter', 'label='+LABEL], text=True).split()
574
+ result = []
575
+ for cid in ids:
576
+ d = json.loads(subprocess.check_output(['docker', 'inspect', '--size', cid]))[0]
577
+ result.append({'id': d['Name'].lstrip('/'), 'container_id': d['Id'],
578
+ 'status': d['State']['Status'], 'created': d['Created'],
579
+ 'persistent_volumes': d['Config'].get('Labels',{}).get('io.raytace.storage')=='volumes-v1',
580
+ 'size_bytes': d.get('SizeRw', 0), 'fork_of': d['Config'].get('Labels',{}).get(FORK_OF)})
581
+ print(json.dumps(result))
582
+ return
583
+ if opts.action.startswith('fork-'):
584
+ return fork_action(opts.action, opts.id or '', opts.forget_evidence)
585
+ if not opts.id or not re.fullmatch(PROJECT_ID, opts.id):
586
+ parser.error('Invalid sandbox ID')
587
+ if opts.action == 'create':
588
+ # Over SSH the archive arrives on stdin; staged where a copied one would be.
589
+ staged = opts.archive == '-'
590
+ if staged:
591
+ opts.archive = stage_archive(opts.id)
592
+ try:
593
+ return create(opts, parser)
594
+ finally:
595
+ if staged:
596
+ Path(opts.archive).unlink(missing_ok=True)
597
+ state = inspect(opts.id)
598
+ if opts.action == 'evidence':
599
+ return evidence(state['Id'])
600
+ if opts.action == 'activity':
601
+ return print(json.dumps(activity(state['Id'], opts.since, opts.until)))
602
+ if opts.action == 'snapshot':
603
+ return read_snapshot(opts.id, state['State']['Running'])
604
+ if opts.action == 'set-guardrails':
605
+ # stdin: {restricted: [project paths], watched?: [project paths]}, the whole lists each time.
606
+ sent = json.loads(sys.stdin.buffer.read(4 * 1024 * 1024))
607
+ lists = {}
608
+ for key, cap in (('restricted', 20000), ('watched', 2000)):
609
+ if key == 'watched' and key not in sent:
610
+ lists[key] = None # an older control plane: keep the list the host has
611
+ continue
612
+ if not isinstance(sent.get(key), list) or len(sent[key]) > cap:
613
+ raise ValueError('Invalid '+key+' list')
614
+ lists[key] = [safe_path(path)[len('/workspace/'):] for path in sent[key]]
615
+ return print(json.dumps(guardrails(opts.id, state, lists['restricted'], lists['watched'])))
616
+ if opts.action == 'guardrails':
617
+ return print(json.dumps(guardrails(opts.id, inspect(opts.id))))
618
+ if opts.action == 'set-token':
619
+ # The token the sandbox's Claude Code hook sends its transcript with, to
620
+ # the RayTrace CLI on this machine (its sandbox bridge). Model calls are
621
+ # not routed anywhere: sign in to Claude Code or Codex inside the sandbox.
622
+ token = sys.stdin.buffer.read(201).decode().strip()
623
+ if not re.fullmatch(r'[A-Za-z0-9_-]{40,100}', token):
624
+ raise ValueError('Invalid sandbox token')
625
+ with io.BytesIO() as buffer:
626
+ with tarfile.open(fileobj=buffer, mode='w') as archive:
627
+ directory = tarfile.TarInfo('.raytace'); directory.type = tarfile.DIRTYPE
628
+ directory.uid = directory.gid = 1000; directory.mode = 0o700
629
+ archive.addfile(directory)
630
+ entry = tarfile.TarInfo('.raytace/sandbox-token'); entry.uid = entry.gid = 1000
631
+ entry.mode = 0o600; entry.size = len(token)
632
+ archive.addfile(entry, io.BytesIO(token.encode()))
633
+ run('docker', 'cp', '-a', '-', opts.id+':/home/node', input=buffer.getvalue())
634
+ print('Sandbox token set')
635
+ elif opts.action == 'enable-claude':
636
+ # The hook script arrives on stdin from the Mac (worker/gvisor/claude-hook.mjs).
637
+ hook = sys.stdin.buffer.read(262145)
638
+ install_claude_hooks(opts.id, hook)
639
+ HOOKS.mkdir(parents=True, exist_ok=True, mode=0o700)
640
+ (HOOKS / (opts.id+'.mjs')).write_bytes(hook)
641
+ print('Claude Code hooks installed')
642
+ elif opts.action in ('shell', 'start'):
643
+ preflight()
644
+ if predates_collector(state):
645
+ # Files and sign-in are on volumes; only running processes end.
646
+ print('RayTrace: the evidence collector restarted since this sandbox started; '
647
+ 'restarting the sandbox so its commands are recorded again.', file=sys.stderr)
648
+ run('docker', 'stop', '-t', '10', opts.id, stdout=subprocess.DEVNULL)
649
+ state = inspect(opts.id)
650
+ restricts = (GUARDRAILS / (opts.id+'.json')).exists()
651
+ if not state['State']['Running']:
652
+ # Stopped is when restricted files are locked (see guardrails()).
653
+ if restricts:
654
+ guardrails(opts.id, state)
655
+ run('docker', 'start', opts.id, stdout=subprocess.DEVNULL)
656
+ # Outside its volumes a sandbox's files last until it restarts, so the
657
+ # hook is put back every time, from the host's copy.
658
+ hook = HOOKS / (opts.id+'.mjs')
659
+ if hook.exists():
660
+ install_claude_hooks(opts.id, hook.read_bytes())
661
+ # The hook's list of restricted files goes the same way.
662
+ if restricts:
663
+ guardrails(opts.id, inspect(opts.id))
664
+ remember(opts.id)
665
+ if opts.action == 'start':
666
+ return
667
+ # Exiting this shell or Codex never stops/removes the persistent container.
668
+ start = 'if [ -f /home/node/.raytace-codex/config.toml ]; then export CODEX_HOME=/home/node/.raytace-codex; fi; '
669
+ if opts.agent:
670
+ name, line = AGENTS[opts.agent]
671
+ start += f'cd /workspace 2>/dev/null; if command -v {opts.agent} >/dev/null; then {line}; else echo "{name} is not installed in this sandbox."; fi; '
672
+ proc = subprocess.run(['docker', 'exec', '-it', opts.id, '/bin/bash', '-c', start+'exec /bin/bash'], check=False)
673
+ sys.exit(proc.returncode)
674
+ elif opts.action == 'stop':
675
+ run('docker', 'stop', '-t', '10', opts.id)
676
+ elif opts.action == 'delete':
677
+ if opts.confirm != opts.id:
678
+ parser.error('Deletion requires --confirm with the exact sandbox ID')
679
+ if state['State']['Running']:
680
+ parser.error('Stop the sandbox before deleting it')
681
+ run('docker', 'rm', opts.id)
682
+ if opts.forget_evidence:
683
+ evidence(state['Id'], forget=True)
684
+ (CONTAINERS / (state['Id']+'.json')).unlink(missing_ok=True)
685
+ (HOOKS / (opts.id+'.mjs')).unlink(missing_ok=True)
686
+ # An immutable file cannot be removed with its volume; chattr -R follows no links.
687
+ if (GUARDRAILS / (opts.id+'.json')).exists():
688
+ root = subprocess.run(['docker', 'volume', 'inspect', '-f', '{{.Mountpoint}}', opts.id+'-workspace'], capture_output=True, text=True)
689
+ if root.returncode == 0:
690
+ subprocess.run(['chattr', '-R', '-f', '-i', root.stdout.strip()], stderr=subprocess.DEVNULL)
691
+ (GUARDRAILS / (opts.id+'.json')).unlink(missing_ok=True)
692
+ for suffix in ('workspace','home'):
693
+ volume=opts.id+'-'+suffix
694
+ result=subprocess.run(['docker','volume','inspect',volume],capture_output=True,text=True)
695
+ if result.returncode==0:
696
+ item=json.loads(result.stdout)[0]
697
+ if item.get('Labels',{}).get(LABEL)!=opts.id:
698
+ raise ValueError('Unexpected volume ownership; volume retained')
699
+ run('docker','volume','rm',volume)
700
+
701
+ if __name__ == '__main__':
702
+ main()