devzero-sandbox 0.1.0__py3-none-any.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.
@@ -0,0 +1,1007 @@
1
+ """MCP tools mapped onto the SDK (ADR-007-W14).
2
+
3
+ Exactly the seven tools of ADR-003 §MCP, each one SDK call:
4
+
5
+ ================= ==============================================================
6
+ ``create_sandbox`` ``client.sandboxes.create(policy, wait=True)``; without a
7
+ policy (and no configured default) it lists the caller's
8
+ policies from ``ListSandboxPolicies`` instead
9
+ ``run_command`` ``sandbox.commands.run(cmd, timeout_s, cwd)``: unary exec up
10
+ to 60 s, the SSE stream above that (the SDK's own switch)
11
+ ``read_file`` ``sandbox.files.read`` (a ``Range`` tail with ``tail_bytes``)
12
+ ``write_file`` ``sandbox.files.write``
13
+ ``list_files`` ``sandbox.files.list``
14
+ ``upload`` ``sandbox.files.write`` from a local file, in 8 MiB chunks
15
+ once the file is 8 MiB or more
16
+ ``delete_sandbox`` ``sandbox.delete()``
17
+ ================= ==============================================================
18
+
19
+ Credentials. The DevZero credential stays inside the SDK ``Client``; each
20
+ sandbox's token stays inside its ``Sandbox`` (in memory, never written to
21
+ disk). A sandbox this session did not create (or whose create answer it lost)
22
+ is found with ``GetSandbox`` and given a fresh token from
23
+ ``CreateSandboxToken``, scoped as ADR-005 scopes MCP-issued tokens: every
24
+ scope but ``ports``. The model sees sandbox ids, never tokens: every string a
25
+ result or an error carries passes through
26
+ :func:`devzero_sandbox.redaction.redact`, so a JWT or a ``dzu-``/``dzs-``
27
+ token in a command's output or a file reaches the model as ``[REDACTED]``.
28
+ Bytes are redacted before they are decoded or base64-encoded
29
+ (:func:`redact_bytes`): the patterns run over a Latin-1 view of the raw bytes
30
+ (one character per byte, so a token in a file that is not valid UTF-8 is
31
+ still found) and over UTF-16LE/BE views at both alignments, and the matching
32
+ byte ranges are replaced. A token that is itself encoded (base64, gzip) is not
33
+ recognisable and is not redacted.
34
+
35
+ Uploads read local files only under ``upload_root``, which must be set
36
+ explicitly (no default): never the filesystem root, the home directory or an
37
+ ancestor of it (:func:`check_upload_root`), and never a credential path inside
38
+ it (``.ssh``, ``.aws``, ``.config/gcloud``, ``.kube``, ``.docker/config.json``,
39
+ ``.netrc``, ``.devzero``, ...; :data:`CREDENTIAL_PATHS`), after symlinks are
40
+ resolved.
41
+
42
+ Model context. Command output keeps its first quarter and last three quarters
43
+ of :attr:`Settings.max_output_bytes` per stream around an omission marker; a
44
+ file larger than :attr:`Settings.max_read_bytes` is refused (``tail_bytes``
45
+ reads its end); the read itself is bounded (a ``Range`` request, and the
46
+ response is never read past the limit), so a file that grows after its listing
47
+ or a symlink to a large file cannot exceed it; a listing stops at
48
+ :attr:`Settings.max_list_entries`.
49
+
50
+ Errors. Every failure is a :class:`ToolError` with a stable ``code`` (the
51
+ gateway's or DevZero's own code where there is one), ``retryable`` and a
52
+ redacted message; the server returns it as a tool error result, so the model
53
+ can read it and correct its call.
54
+
55
+ Session end. :meth:`SandboxTools.close` deletes every sandbox this session
56
+ created (``cleanup_on_exit``, default true), including one whose create timed
57
+ out waiting for ``ready`` and one whose ``create_sandbox`` is still running:
58
+ each create carries its own idempotency key, and close replays it without
59
+ waiting (DevZero answers a replay with the original sandbox; ``wait_ready`` is
60
+ not part of the request it compares), so the sandbox is found and deleted even
61
+ while the first call is still waiting for it to be ready.
62
+ """
63
+
64
+ from __future__ import annotations
65
+
66
+ import base64
67
+ import json
68
+ import posixpath
69
+ import re
70
+ import threading
71
+ import uuid
72
+ from collections.abc import Callable, Mapping, Sequence
73
+ from dataclasses import dataclass, field
74
+ from pathlib import Path
75
+ from typing import Any
76
+ from urllib.parse import quote
77
+
78
+ import httpx
79
+
80
+ from devzero_sandbox import errors
81
+ from devzero_sandbox._proto.sandbox.v1 import service_pb2 as pb
82
+ from devzero_sandbox.commands import WORKSPACE, CommandResult
83
+ from devzero_sandbox.redaction import _PATTERNS as _TOKEN_PATTERNS
84
+ from devzero_sandbox.redaction import REDACTED, get_logger, redact
85
+ from devzero_sandbox.sandbox import Client, Sandbox, phase_name
86
+
87
+ log = get_logger(__name__)
88
+
89
+ #: ADR-005 §Token claims: MCP-issued tokens default to every scope but ``ports``.
90
+ MCP_TOKEN_SCOPES = ("exec", "files", "terminal", "watch")
91
+ #: ADR-007-W14: an upload of this size or more is split into appending PUTs of this size.
92
+ UPLOAD_CHUNK_BYTES = 8 << 20
93
+
94
+ _SANDBOX_ID = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
95
+
96
+ #: Local paths ``upload`` never reads, at any depth, even inside ``upload_root``:
97
+ #: directories (every file under them) and files, as path-component sequences.
98
+ CREDENTIAL_PATHS: tuple[tuple[str, ...], ...] = (
99
+ (".ssh",),
100
+ (".aws",),
101
+ (".azure",),
102
+ (".kube",),
103
+ (".gnupg",),
104
+ (".devzero",), # the dz CLI's credentials (cli/internal/auth)
105
+ (".config", "gcloud"),
106
+ (".config", "gh"),
107
+ (".docker", "config.json"),
108
+ (".netrc",),
109
+ (".git-credentials",),
110
+ (".pgpass",),
111
+ (".pypirc",),
112
+ (".npmrc",),
113
+ )
114
+
115
+
116
+ def is_credential_path(path: Path) -> bool:
117
+ """Whether resolved ``path`` is, or lies inside, one of :data:`CREDENTIAL_PATHS`."""
118
+ parts = [p.lower() for p in path.parts]
119
+ for cred in CREDENTIAL_PATHS:
120
+ n = len(cred)
121
+ if any(tuple(parts[i : i + n]) == cred for i in range(len(parts) - n + 1)):
122
+ return True
123
+ return False
124
+
125
+
126
+ def check_upload_root(root: str) -> Path:
127
+ """``root`` resolved, or ``ValueError`` if it is unsafe as ``upload``'s directory.
128
+
129
+ Refused: a missing directory, the filesystem root, the home directory and
130
+ any directory above it (each would expose ``~/.ssh``, ``~/.aws`` and the
131
+ DevZero credentials to the model), and a credential directory itself.
132
+ """
133
+ p = Path(root).expanduser().resolve()
134
+ if not p.is_dir():
135
+ raise ValueError(f"upload directory {root!r} is not a directory")
136
+ home = Path.home().resolve()
137
+ if p == Path(p.anchor):
138
+ raise ValueError("the upload directory must not be the filesystem root")
139
+ if p == home or p in home.parents:
140
+ raise ValueError(
141
+ f"the upload directory must not be the home directory or above it ({p}); "
142
+ "use a project directory"
143
+ )
144
+ if is_credential_path(p):
145
+ raise ValueError(f"the upload directory {p} is a credential directory")
146
+ return p
147
+
148
+
149
+ @dataclass(frozen=True)
150
+ class Settings:
151
+ """The defaults a model does not have to pass, and the context budgets."""
152
+
153
+ #: The sandbox root (``sandboxd``'s ``--root-dir``): relative paths and ``cwd`` resolve here.
154
+ workspace: str = WORKSPACE
155
+ #: ``create_sandbox`` without ``policy`` / ``cluster_id`` uses these (an MCP config
156
+ #: generated with a policy pre-selected, ADR-004 §UI); empty lists the policies.
157
+ default_policy: str = ""
158
+ default_cluster_id: str = ""
159
+ #: How long ``create_sandbox`` waits for ``ready`` (the SDK's default).
160
+ create_timeout_s: float = 300.0
161
+ #: ``run_command``'s ``timeout_s`` when the model passes none, and the largest it may pass.
162
+ default_timeout_s: int = 60
163
+ max_timeout_s: int = 3600
164
+ #: Bytes of stdout and of stderr returned per command (head + tail around a marker).
165
+ max_output_bytes: int = 32 * 1024
166
+ #: Largest file ``read_file`` returns whole; also the cap on ``tail_bytes``.
167
+ max_read_bytes: int = 256 * 1024
168
+ #: Entries ``list_files`` returns before it says the listing was cut.
169
+ max_list_entries: int = 1000
170
+ #: ``upload`` reads local files only under this directory; empty disables
171
+ #: ``upload``. Never the filesystem root or the home directory (or above it).
172
+ upload_root: str = ""
173
+ #: Delete the sandboxes this session created when it ends.
174
+ cleanup_on_exit: bool = True
175
+
176
+
177
+ @dataclass(frozen=True)
178
+ class ToolSpec:
179
+ """One MCP tool: its name, description and JSON Schema for the arguments."""
180
+
181
+ name: str
182
+ description: str
183
+ input_schema: dict[str, Any]
184
+
185
+
186
+ @dataclass(frozen=True)
187
+ class ToolResult:
188
+ """A tool's answer: ``structured`` (JSON object) and ``text`` (the same, for the model)."""
189
+
190
+ structured: dict[str, Any]
191
+ text: str
192
+
193
+
194
+ class ToolError(Exception):
195
+ """A tool call that failed; the server returns it as an error result, not a protocol error."""
196
+
197
+ def __init__(
198
+ self,
199
+ code: str,
200
+ message: str,
201
+ *,
202
+ retryable: bool = False,
203
+ details: Mapping[str, Any] | None = None,
204
+ ) -> None:
205
+ self.code = code
206
+ self.message = redact(message)
207
+ self.retryable = retryable
208
+ self.details = {
209
+ k: redact(v) if isinstance(v, str) else v
210
+ for k, v in (details or {}).items()
211
+ }
212
+ super().__init__(f"{code}: {self.message}")
213
+
214
+ def to_dict(self) -> dict[str, Any]:
215
+ err: dict[str, Any] = {
216
+ "code": self.code,
217
+ "message": self.message,
218
+ "retryable": self.retryable,
219
+ }
220
+ if self.details:
221
+ err["details"] = self.details
222
+ return {"error": err}
223
+
224
+
225
+ def _schema(properties: dict[str, Any], required: Sequence[str] = ()) -> dict[str, Any]:
226
+ return {
227
+ "type": "object",
228
+ "properties": properties,
229
+ "required": list(required),
230
+ "additionalProperties": False,
231
+ }
232
+
233
+
234
+ _ID = {
235
+ "type": "string",
236
+ "description": "The sandbox id create_sandbox returned.",
237
+ "pattern": _SANDBOX_ID.pattern,
238
+ }
239
+
240
+ TOOLS: tuple[ToolSpec, ...] = (
241
+ ToolSpec(
242
+ "create_sandbox",
243
+ "Create a DevZero sandbox (an isolated Linux container in the team's own Kubernetes "
244
+ "cluster) and wait until it is ready; returns its sandbox_id. Without a policy it "
245
+ "creates nothing and lists the sandbox policies you may use instead. Sandboxes this "
246
+ "session creates are deleted when it ends.",
247
+ _schema(
248
+ {
249
+ "policy": {
250
+ "type": "string",
251
+ "description": "The SandboxPolicy name. Omit it to list the policies.",
252
+ },
253
+ "cluster_id": {
254
+ "type": "string",
255
+ "description": "The cluster, when the policy name exists on more than one.",
256
+ },
257
+ "ttl_seconds": {
258
+ "type": "integer",
259
+ "minimum": 1,
260
+ "description": "Lifetime in seconds; the policy's default and maximum apply.",
261
+ },
262
+ }
263
+ ),
264
+ ),
265
+ ToolSpec(
266
+ "run_command",
267
+ "Run a shell command (/bin/sh -c) in a sandbox and return its exit code, stdout and "
268
+ "stderr. Long output is cut in the middle. The command is killed at timeout_s.",
269
+ _schema(
270
+ {
271
+ "sandbox_id": _ID,
272
+ "cmd": {
273
+ "type": "string",
274
+ "minLength": 1,
275
+ "description": "The command.",
276
+ },
277
+ "cwd": {
278
+ "type": "string",
279
+ "description": "Working directory; relative to /workspace. Default /workspace.",
280
+ },
281
+ "timeout_s": {
282
+ "type": "integer",
283
+ "minimum": 1,
284
+ "description": "Seconds before the command is killed (default 60).",
285
+ },
286
+ },
287
+ ["sandbox_id", "cmd"],
288
+ ),
289
+ ),
290
+ ToolSpec(
291
+ "read_file",
292
+ "Read a file from a sandbox. Paths are relative to /workspace. Text comes back as "
293
+ "UTF-8, anything else as base64. A large file is refused with its size: read its end "
294
+ "with tail_bytes, or a part of it with run_command (head, sed -n, grep).",
295
+ _schema(
296
+ {
297
+ "sandbox_id": _ID,
298
+ "path": {"type": "string", "minLength": 1},
299
+ "tail_bytes": {
300
+ "type": "integer",
301
+ "minimum": 1,
302
+ "description": "Return only the file's last N bytes.",
303
+ },
304
+ },
305
+ ["sandbox_id", "path"],
306
+ ),
307
+ ),
308
+ ToolSpec(
309
+ "write_file",
310
+ "Create or replace a file in a sandbox (or append to it). Paths are relative to "
311
+ "/workspace; missing directories are created.",
312
+ _schema(
313
+ {
314
+ "sandbox_id": _ID,
315
+ "path": {"type": "string", "minLength": 1},
316
+ "content": {"type": "string"},
317
+ "encoding": {
318
+ "type": "string",
319
+ "enum": ["utf-8", "base64"],
320
+ "description": "How content is encoded (default utf-8).",
321
+ },
322
+ "append": {
323
+ "type": "boolean",
324
+ "description": "Append instead of replace.",
325
+ },
326
+ },
327
+ ["sandbox_id", "path", "content"],
328
+ ),
329
+ ),
330
+ ToolSpec(
331
+ "list_files",
332
+ "List a directory in a sandbox (default /workspace): name, path, type, size.",
333
+ _schema(
334
+ {"sandbox_id": _ID, "path": {"type": "string"}},
335
+ ["sandbox_id"],
336
+ ),
337
+ ),
338
+ ToolSpec(
339
+ "upload",
340
+ "Copy a file from this machine into a sandbox. local_path is relative to the "
341
+ "upload directory the server was configured with (uploads are off without one) and "
342
+ "must stay inside it; credential files (.ssh, .aws, .kube, .netrc, ...) are refused. "
343
+ "path defaults to the file's name in /workspace.",
344
+ _schema(
345
+ {
346
+ "sandbox_id": _ID,
347
+ "local_path": {"type": "string", "minLength": 1},
348
+ "path": {
349
+ "type": "string",
350
+ "description": "Destination in the sandbox.",
351
+ },
352
+ },
353
+ ["sandbox_id", "local_path"],
354
+ ),
355
+ ),
356
+ ToolSpec(
357
+ "delete_sandbox",
358
+ "Delete a sandbox. Its processes and files are gone afterwards.",
359
+ _schema({"sandbox_id": _ID}, ["sandbox_id"]),
360
+ ),
361
+ )
362
+
363
+ TOOL_NAMES = tuple(t.name for t in TOOLS)
364
+ _SPECS = {t.name: t for t in TOOLS}
365
+
366
+ _JSON_TYPES: dict[str, Callable[[Any], bool]] = {
367
+ "string": lambda v: isinstance(v, str),
368
+ "integer": lambda v: isinstance(v, int) and not isinstance(v, bool),
369
+ "boolean": lambda v: isinstance(v, bool),
370
+ }
371
+
372
+
373
+ def _validate(spec: ToolSpec, arguments: Mapping[str, Any] | None) -> dict[str, Any]:
374
+ """The arguments, checked against the tool's schema (the subset the schemas use)."""
375
+ args = dict(arguments or {})
376
+ schema = spec.input_schema
377
+ props: dict[str, Any] = schema["properties"]
378
+ unknown = sorted(set(args) - set(props))
379
+ if unknown:
380
+ raise ToolError(
381
+ "invalid_argument", f"unknown argument(s): {', '.join(unknown)}"
382
+ )
383
+ for name in schema["required"]:
384
+ if name not in args:
385
+ raise ToolError("invalid_argument", f"missing required argument {name!r}")
386
+ for name, value in args.items():
387
+ p = props[name]
388
+ if not _JSON_TYPES[p["type"]](value):
389
+ raise ToolError("invalid_argument", f"{name!r} must be of type {p['type']}")
390
+ if "minimum" in p and value < p["minimum"]:
391
+ raise ToolError(
392
+ "invalid_argument", f"{name!r} must be at least {p['minimum']}"
393
+ )
394
+ if "minLength" in p and len(value) < p["minLength"]:
395
+ raise ToolError("invalid_argument", f"{name!r} must not be empty")
396
+ if "enum" in p and value not in p["enum"]:
397
+ raise ToolError("invalid_argument", f"{name!r} must be one of {p['enum']}")
398
+ if "pattern" in p and not re.match(p["pattern"], value):
399
+ raise ToolError("invalid_argument", f"{name!r} is not a sandbox id")
400
+ return args
401
+
402
+
403
+ def _spans(view: str) -> list[tuple[int, int]]:
404
+ """Token spans in ``view``, merged, in order."""
405
+ found = sorted(m.span() for p in _TOKEN_PATTERNS for m in p.finditer(view))
406
+ merged: list[tuple[int, int]] = []
407
+ for start, end in found:
408
+ if merged and start <= merged[-1][1]:
409
+ merged[-1] = (merged[-1][0], max(end, merged[-1][1]))
410
+ else:
411
+ merged.append((start, end))
412
+ return merged
413
+
414
+
415
+ def _replace(data: bytes, spans: list[tuple[int, int]], marker: bytes) -> bytes:
416
+ for start, end in reversed(spans):
417
+ data = data[:start] + marker + data[end:]
418
+ return data
419
+
420
+
421
+ def _utf16_view(data: bytes, big_endian: bool) -> str:
422
+ """One character per 2-byte unit: its ASCII character, or U+FFFF if it is none."""
423
+ lo, hi = (data[1::2], data[0::2]) if big_endian else (data[0::2], data[1::2])
424
+ return "".join(
425
+ chr(a) if b == 0 and 0 < a < 128 else "\uffff"
426
+ for a, b in zip(lo, hi, strict=False)
427
+ )
428
+
429
+
430
+ def redact_bytes(data: bytes) -> bytes:
431
+ """``data`` with every credential replaced by ``[REDACTED]``, whatever its encoding.
432
+
433
+ Latin-1 maps each byte to one character, so the redaction patterns run on
434
+ the raw bytes losslessly (UTF-8 text, text with stray bytes, binary files);
435
+ UTF-16 views at both byte alignments and both byte orders catch wide-char
436
+ tokens (Windows text, UTF-16 strings in binaries), and are replaced with a
437
+ UTF-16 marker. Over-matching is possible (``Bearer`` followed by binary);
438
+ under-matching of a plain-text token is not.
439
+ """
440
+ data = _replace(data, _spans(data.decode("latin-1")), REDACTED.encode())
441
+ if b"\x00" not in data:
442
+ return data
443
+ for big_endian in (False, True):
444
+ marker = REDACTED.encode("utf-16-be" if big_endian else "utf-16-le")
445
+ for align in (0, 1):
446
+ body = data[align:]
447
+ spans = _spans(_utf16_view(body[: len(body) // 2 * 2], big_endian))
448
+ if spans:
449
+ data = _replace(
450
+ data,
451
+ [(align + 2 * s, align + 2 * e) for s, e in spans],
452
+ marker,
453
+ )
454
+ return data
455
+
456
+
457
+ def clip(data: bytes, limit: int) -> tuple[str, bool]:
458
+ """``data`` as text within ``limit`` bytes: its head and tail around a marker."""
459
+ data = redact_bytes(data)
460
+ if len(data) <= limit:
461
+ return redact(data.decode("utf-8", "replace")), False
462
+ head = limit // 4
463
+ tail = limit - head
464
+ omitted = len(data) - head - tail
465
+ text = (
466
+ data[:head].decode("utf-8", "replace")
467
+ + f"\n[... {omitted} bytes omitted ...]\n"
468
+ + data[len(data) - tail :].decode("utf-8", "replace")
469
+ )
470
+ return redact(text), True
471
+
472
+
473
+ def _redact_all(value: Any) -> Any:
474
+ if isinstance(value, str):
475
+ return redact(value)
476
+ if isinstance(value, dict):
477
+ return {k: _redact_all(v) for k, v in value.items()}
478
+ if isinstance(value, list):
479
+ return [_redact_all(v) for v in value]
480
+ return value
481
+
482
+
483
+ def _json_result(structured: dict[str, Any]) -> ToolResult:
484
+ structured = _redact_all(structured)
485
+ return ToolResult(structured, json.dumps(structured, indent=2, sort_keys=True))
486
+
487
+
488
+ def tool_error(exc: BaseException) -> ToolError:
489
+ """The tool error for an exception an SDK call raised (ADR-007-W14's error mapping)."""
490
+ if isinstance(exc, ToolError):
491
+ return exc
492
+ if isinstance(exc, ValueError):
493
+ return ToolError("invalid_argument", str(exc))
494
+ if isinstance(exc, errors.UpstreamTimeout):
495
+ return ToolError(
496
+ "command_timeout",
497
+ "the command ran past timeout_s and was killed; raise timeout_s, or start it "
498
+ "in the background (`nohup ... > out.log 2>&1 &`) and read the log",
499
+ details={"pid": exc.pid} if exc.pid is not None else None,
500
+ )
501
+ if isinstance(exc, errors.PayloadTooLarge):
502
+ return ToolError(
503
+ "output_too_large",
504
+ "the command ran, but its stdout or stderr passed the gateway's 4 MiB limit; "
505
+ "run it again with its output redirected to a file and read the part you need",
506
+ )
507
+ if isinstance(exc, errors.SandboxFileNotFound):
508
+ return ToolError("file_not_found", exc.message or "no such file or directory")
509
+ if isinstance(exc, errors.GatewayError):
510
+ details: dict[str, Any] = {"status": exc.status}
511
+ if exc.sandbox_id:
512
+ details["sandbox_id"] = exc.sandbox_id
513
+ return ToolError(
514
+ exc.code or f"http_{exc.status}",
515
+ exc.message,
516
+ retryable=exc.retryable,
517
+ details=details,
518
+ )
519
+ if isinstance(exc, errors.StreamInterrupted):
520
+ return ToolError(
521
+ "stream_interrupted",
522
+ f"the connection to the command ended before it exited ({exc.code}); the "
523
+ "command was stopped and is not re-run",
524
+ retryable=True,
525
+ details={"pid": exc.pid} if exc.pid is not None else None,
526
+ )
527
+ if isinstance(exc, errors.ControlPlaneError):
528
+ return ToolError(
529
+ exc.code, exc.message, retryable=exc.retryable, details=exc.details
530
+ )
531
+ if isinstance(exc, errors.SandboxWaitTimeout):
532
+ return ToolError(
533
+ "sandbox_not_ready",
534
+ f"{exc}; it may still become ready, and is deleted when this session ends",
535
+ retryable=True,
536
+ details={"sandbox_id": exc.sandbox_id, "status": exc.phase},
537
+ )
538
+ if isinstance(exc, errors.SandboxFailed):
539
+ return ToolError(
540
+ "sandbox_failed",
541
+ str(exc),
542
+ details={"sandbox_id": exc.sandbox_id, "status": exc.phase},
543
+ )
544
+ if isinstance(exc, errors.DevZeroSandboxError):
545
+ return ToolError("sandbox_error", str(exc))
546
+ if isinstance(exc, httpx.TransportError):
547
+ return ToolError(
548
+ "network_error", f"{type(exc).__name__}: {exc}", retryable=True
549
+ )
550
+ if isinstance(exc, OSError):
551
+ return ToolError("local_io_error", f"{type(exc).__name__}: {exc}")
552
+ log.error("tool call failed unexpectedly: %r", exc, exc_info=exc)
553
+ return ToolError("internal", "the sandbox MCP server failed; see its log")
554
+
555
+
556
+ @dataclass(frozen=True)
557
+ class _Create:
558
+ """A ``create_sandbox`` call's request, replayed by close() under its idempotency key."""
559
+
560
+ key: str
561
+ policy: str
562
+ cluster_id: str
563
+ ttl_s: int | None
564
+
565
+ def run(self, client: Client, *, wait: bool, timeout_s: float = 300) -> Sandbox:
566
+ return client.sandboxes.create(
567
+ self.policy,
568
+ cluster_id=self.cluster_id,
569
+ wait=wait,
570
+ timeout_s=timeout_s,
571
+ ttl_s=self.ttl_s,
572
+ idempotency_key=self.key,
573
+ )
574
+
575
+
576
+ @dataclass
577
+ class _Session:
578
+ """Sandboxes this session holds a handle (and token) for, and the ones it created."""
579
+
580
+ held: dict[str, Sandbox] = field(default_factory=dict)
581
+ created: list[str] = field(default_factory=list)
582
+ #: ``create_sandbox`` calls still running, by idempotency key.
583
+ creating: dict[str, _Create] = field(default_factory=dict)
584
+ lock: threading.Lock = field(default_factory=threading.Lock)
585
+
586
+
587
+ class SandboxTools:
588
+ """The seven tools over one SDK :class:`~devzero_sandbox.Client`.
589
+
590
+ Thread-safe: the server runs each call in a worker thread. The caller owns
591
+ ``client`` and closes it after :meth:`close`.
592
+ """
593
+
594
+ def __init__(self, client: Client, settings: Settings | None = None) -> None:
595
+ self.client = client
596
+ self.settings = settings or Settings()
597
+ self._s = _Session()
598
+ self._closed = False
599
+ # Held for all of close(): a second close (SIGTERM during an EOF
600
+ # shutdown) waits for the first to finish deleting instead of
601
+ # returning early into os._exit.
602
+ self._close_lock = threading.Lock()
603
+ self._handlers: dict[str, Callable[[dict[str, Any]], ToolResult]] = {
604
+ "create_sandbox": self.create_sandbox,
605
+ "run_command": self.run_command,
606
+ "read_file": self.read_file,
607
+ "write_file": self.write_file,
608
+ "list_files": self.list_files,
609
+ "upload": self.upload,
610
+ "delete_sandbox": self.delete_sandbox,
611
+ }
612
+ assert tuple(self._handlers) == TOOL_NAMES
613
+
614
+ @property
615
+ def created(self) -> list[str]:
616
+ """Ids of the sandboxes this session created and has not deleted."""
617
+ with self._s.lock:
618
+ return list(self._s.created)
619
+
620
+ # --- dispatch ------------------------------------------------------------------
621
+
622
+ def call(self, name: str, arguments: Mapping[str, Any] | None) -> ToolResult:
623
+ """Run tool ``name``; raises :class:`ToolError` (never another exception)."""
624
+ spec = _SPECS.get(name)
625
+ if spec is None:
626
+ raise ToolError("unknown_tool", f"no tool named {name!r}")
627
+ try:
628
+ return self._handlers[name](_validate(spec, arguments))
629
+ except Exception as exc: # noqa: BLE001 -- every failure becomes a tool error
630
+ raise tool_error(exc) from None
631
+
632
+ # --- sandboxes -----------------------------------------------------------------
633
+
634
+ def _adopt(self, sbx: Sandbox) -> Sandbox:
635
+ sbx.workspace = self.settings.workspace
636
+ with self._s.lock:
637
+ self._s.held[sbx.id] = sbx
638
+ return sbx
639
+
640
+ def _sandbox(self, sandbox_id: str) -> Sandbox:
641
+ """The handle for ``sandbox_id``: held, or found and given a token now."""
642
+ with self._s.lock:
643
+ sbx = self._s.held.get(sandbox_id)
644
+ if sbx is not None:
645
+ return sbx
646
+ sbx = self.client.sandboxes.get(sandbox_id)
647
+ status = sbx.status
648
+ if status != "ready":
649
+ raise ToolError(
650
+ "sandbox_not_ready" if status == "pending" else f"sandbox_{status}",
651
+ f"sandbox {sandbox_id} is {status}",
652
+ retryable=status in ("pending", "recreating"),
653
+ details={"sandbox_id": sandbox_id, "status": status},
654
+ )
655
+ sbx.tokens.mint(MCP_TOKEN_SCOPES)
656
+ return self._adopt(sbx)
657
+
658
+ def create_sandbox(self, args: dict[str, Any]) -> ToolResult:
659
+ st = self.settings
660
+ policy = args.get("policy") or st.default_policy
661
+ cluster_id = args.get("cluster_id") or st.default_cluster_id
662
+ if not policy:
663
+ return self._list_policies(cluster_id)
664
+ # Registered before the call, so close() can find this sandbox while
665
+ # CreateSandbox is still waiting for it to be ready (see close()).
666
+ create = _Create(
667
+ f"mcp-{uuid.uuid4()}", policy, cluster_id, args.get("ttl_seconds")
668
+ )
669
+ key = create.key
670
+ with self._s.lock:
671
+ if self._closed:
672
+ raise ToolError("session_ended", "the MCP session is ending")
673
+ self._s.creating[key] = create
674
+ try:
675
+ sbx = create.run(self.client, wait=True, timeout_s=st.create_timeout_s)
676
+ except (errors.SandboxWaitTimeout, errors.SandboxFailed) as e:
677
+ # It exists: this session created it, so this session deletes it.
678
+ with self._s.lock:
679
+ self._s.creating.pop(key, None)
680
+ self._s.created.append(e.sandbox_id)
681
+ raise
682
+ except BaseException:
683
+ with self._s.lock:
684
+ self._s.creating.pop(key, None)
685
+ raise
686
+ self._adopt(sbx)
687
+ with self._s.lock:
688
+ self._s.creating.pop(key, None)
689
+ self._s.created.append(sbx.id)
690
+ info = sbx.info
691
+ out: dict[str, Any] = {
692
+ "sandbox_id": sbx.id,
693
+ "policy": info.policy,
694
+ "cluster_id": info.cluster_id,
695
+ "status": sbx.status,
696
+ "workspace": st.workspace,
697
+ "deleted_when_session_ends": st.cleanup_on_exit,
698
+ }
699
+ if info.HasField("shutdown_at"):
700
+ out["shutdown_at"] = info.shutdown_at.ToJsonString()
701
+ return _json_result(out)
702
+
703
+ def _list_policies(self, cluster_id: str) -> ToolResult:
704
+ rows = []
705
+ for p in self.client.policies(cluster_id):
706
+ ready = [c.status == "True" for c in p.conditions if c.type == "Ready"]
707
+ row: dict[str, Any] = {
708
+ "policy": p.name,
709
+ "cluster_id": p.cluster_id,
710
+ "ready": ready[0] if ready else None,
711
+ "active_sandboxes": p.active.sandboxes,
712
+ "max_sandboxes": p.limits.max_sandboxes,
713
+ }
714
+ if p.limits.HasField("default_ttl"):
715
+ row["default_ttl_seconds"] = p.limits.default_ttl.seconds
716
+ if p.limits.HasField("max_ttl"):
717
+ row["max_ttl_seconds"] = p.limits.max_ttl.seconds
718
+ rows.append(row)
719
+ return _json_result(
720
+ {
721
+ "created": False,
722
+ "policies": rows,
723
+ "hint": "No sandbox was created. Call create_sandbox again with one of "
724
+ "these policies (and its cluster_id when the name appears more than once)."
725
+ if rows
726
+ else "No sandbox policy is available to this DevZero credential.",
727
+ }
728
+ )
729
+
730
+ def delete_sandbox(self, args: dict[str, Any]) -> ToolResult:
731
+ sandbox_id: str = args["sandbox_id"]
732
+ with self._s.lock:
733
+ sbx = self._s.held.get(sandbox_id)
734
+ if sbx is None:
735
+ # Deleting is a control-plane call: no sandbox token needed.
736
+ sbx = Sandbox(pb.Sandbox(id=sandbox_id), client=self.client)
737
+ sbx.delete()
738
+ with self._s.lock:
739
+ self._s.held.pop(sandbox_id, None)
740
+ if sandbox_id in self._s.created:
741
+ self._s.created.remove(sandbox_id)
742
+ return _json_result(
743
+ {"sandbox_id": sandbox_id, "status": phase_name(sbx.info.status)}
744
+ )
745
+
746
+ # --- commands --------------------------------------------------------------------
747
+
748
+ def _cwd(self, cwd: str | None) -> str:
749
+ root = self.settings.workspace
750
+ if not cwd:
751
+ return root
752
+ return posixpath.normpath(cwd if cwd.startswith("/") else f"{root}/{cwd}")
753
+
754
+ def run_command(self, args: dict[str, Any]) -> ToolResult:
755
+ st = self.settings
756
+ timeout_s: int = args.get("timeout_s", st.default_timeout_s)
757
+ if timeout_s > st.max_timeout_s:
758
+ raise ToolError(
759
+ "invalid_argument",
760
+ f"timeout_s must be at most {st.max_timeout_s}; start longer work in the "
761
+ "background and poll it",
762
+ )
763
+ sbx = self._sandbox(args["sandbox_id"])
764
+ res: CommandResult = sbx.commands.run(
765
+ args["cmd"], timeout_s=timeout_s, cwd=self._cwd(args.get("cwd"))
766
+ )
767
+ stdout, out_cut = clip(res.stdout, st.max_output_bytes)
768
+ stderr, err_cut = clip(res.stderr, st.max_output_bytes)
769
+ structured = {
770
+ "exit_code": res.exit_code,
771
+ "stdout": stdout,
772
+ "stderr": stderr,
773
+ "stdout_bytes": len(res.stdout),
774
+ "stderr_bytes": len(res.stderr),
775
+ "truncated": out_cut or err_cut,
776
+ }
777
+ parts = [f"exit_code: {res.exit_code}"]
778
+ if stdout:
779
+ parts.append(f"--- stdout ---\n{stdout}")
780
+ if stderr:
781
+ parts.append(f"--- stderr ---\n{stderr}")
782
+ return ToolResult(structured, "\n".join(parts))
783
+
784
+ # --- files -------------------------------------------------------------------------
785
+
786
+ def read_file(self, args: dict[str, Any]) -> ToolResult:
787
+ st = self.settings
788
+ limit = st.max_read_bytes
789
+ sbx = self._sandbox(args["sandbox_id"])
790
+ rel = sbx.files.relative(args["path"])
791
+ tail = args.get("tail_bytes")
792
+ if not rel:
793
+ raise ToolError(
794
+ "is_a_directory", "the sandbox root is a directory; use list_files"
795
+ )
796
+ if tail is None:
797
+ self._check_listing(sbx, rel, limit)
798
+ data = self._read_bounded(
799
+ sbx, rel, limit, tail=min(tail, limit) if tail else None
800
+ )
801
+ raw_len = len(data)
802
+ data = redact_bytes(data)
803
+ out: dict[str, Any] = {"path": rel, "bytes": raw_len}
804
+ try:
805
+ out |= {"encoding": "utf-8", "content": data.decode("utf-8")}
806
+ except UnicodeDecodeError:
807
+ out |= {"encoding": "base64", "content": base64.b64encode(data).decode()}
808
+ out = _redact_all(out)
809
+ text = (
810
+ out["content"]
811
+ if out["encoding"] == "utf-8"
812
+ else json.dumps(out, indent=2, sort_keys=True)
813
+ )
814
+ return ToolResult(out, text)
815
+
816
+ @staticmethod
817
+ def _too_large(rel: str, limit: int, size: int | None) -> ToolError:
818
+ what = f"{size} bytes" if size is not None else f"more than {limit} bytes"
819
+ details: dict[str, Any] = {"limit": limit}
820
+ if size is not None:
821
+ details["size"] = size
822
+ return ToolError(
823
+ "file_too_large",
824
+ f"{rel} is {what}, more than the {limit} this tool returns; pass tail_bytes "
825
+ "for its end, or read a part with run_command (head -c, sed -n, grep)",
826
+ details=details,
827
+ )
828
+
829
+ def _check_listing(self, sbx: Sandbox, rel: str, limit: int) -> None:
830
+ """Refuse a directory, a missing file, or one listed above the limit, before reading.
831
+
832
+ Only an early answer with the size: the listing can be stale (a file
833
+ growing) or the size of a symlink, so the read is bounded on its own.
834
+ """
835
+ parent, name = posixpath.split(rel)
836
+ for e in sbx.files.list(parent):
837
+ if e.name == name:
838
+ if e.type == "directory":
839
+ raise ToolError(
840
+ "is_a_directory", f"{rel} is a directory; use list_files"
841
+ )
842
+ if e.size > limit:
843
+ raise self._too_large(rel, limit, e.size)
844
+ return
845
+ raise ToolError("file_not_found", f"{rel} does not exist")
846
+
847
+ def _read_bounded(
848
+ self, sbx: Sandbox, rel: str, limit: int, *, tail: int | None
849
+ ) -> bytes:
850
+ """At most ``limit`` bytes of the file (its last ``tail`` bytes with ``tail``).
851
+
852
+ Asks for a ``Range`` (the first ``limit + 1`` bytes, or the last
853
+ ``tail``). A head read never reads the response past ``limit + 1``
854
+ bytes, even from a gateway that ignores the range; a tail read from
855
+ one keeps only the last ``tail`` bytes. More than ``limit`` bytes is
856
+ ``file_too_large``.
857
+ """
858
+ url = "/v1/files/" + "/".join(quote(seg, safe="") for seg in rel.split("/"))
859
+ rng = f"bytes=-{tail}" if tail is not None else f"bytes=0-{limit}"
860
+ try:
861
+ with sbx.transport.stream(
862
+ "GET",
863
+ url,
864
+ scope="files",
865
+ params={"type": "file"},
866
+ headers={"Range": rng},
867
+ ) as resp:
868
+ ranged = resp.status_code == 206
869
+ buf = bytearray()
870
+ for chunk in resp.iter_bytes():
871
+ buf += chunk
872
+ if tail is not None and not ranged:
873
+ del buf[: max(0, len(buf) - tail)] # the range was ignored
874
+ elif len(buf) > limit:
875
+ break
876
+ except errors.GatewayError as e:
877
+ if e.status == 416: # an empty file has no last N bytes
878
+ return b""
879
+ raise
880
+ if len(buf) > limit:
881
+ total = resp.headers.get("content-range", "").rpartition("/")[2]
882
+ raise self._too_large(rel, limit, int(total) if total.isdigit() else None)
883
+ return bytes(buf)
884
+
885
+ def write_file(self, args: dict[str, Any]) -> ToolResult:
886
+ sbx = self._sandbox(args["sandbox_id"])
887
+ content: str = args["content"]
888
+ if args.get("encoding") == "base64":
889
+ try:
890
+ data = base64.b64decode(content, validate=True)
891
+ except ValueError as e:
892
+ raise ToolError(
893
+ "invalid_argument", f"content is not base64: {e}"
894
+ ) from None
895
+ else:
896
+ data = content.encode()
897
+ append = bool(args.get("append", False))
898
+ rel = sbx.files.relative(args["path"])
899
+ sbx.files.write(rel, data, append=append)
900
+ return _json_result({"path": rel, "bytes_written": len(data), "append": append})
901
+
902
+ def list_files(self, args: dict[str, Any]) -> ToolResult:
903
+ limit = self.settings.max_list_entries
904
+ sbx = self._sandbox(args["sandbox_id"])
905
+ entries = sbx.files.list(args.get("path", ""))
906
+ rows = [
907
+ {"name": e.name, "path": e.path, "type": e.type, "size": e.size}
908
+ for e in entries[:limit]
909
+ ]
910
+ return _json_result(
911
+ {
912
+ "path": sbx.files.relative(args.get("path", "")) or ".",
913
+ "entries": rows,
914
+ "truncated": len(entries) > limit,
915
+ "total": len(entries),
916
+ }
917
+ )
918
+
919
+ def _local(self, local_path: str) -> Path:
920
+ if not self.settings.upload_root:
921
+ raise ToolError(
922
+ "upload_disabled",
923
+ "uploads are off: the server has no upload directory "
924
+ "(DEVZERO_SANDBOX_MCP_UPLOAD_ROOT); write small files with write_file",
925
+ )
926
+ try:
927
+ root = check_upload_root(self.settings.upload_root)
928
+ except ValueError as e:
929
+ raise ToolError("upload_disabled", str(e)) from None
930
+ p = Path(local_path).expanduser()
931
+ p = (p if p.is_absolute() else root / p).resolve()
932
+ if p != root and root not in p.parents:
933
+ raise ToolError(
934
+ "invalid_argument",
935
+ f"local_path must be inside {root}, the directory uploads are read from",
936
+ )
937
+ if is_credential_path(p):
938
+ raise ToolError(
939
+ "credential_path",
940
+ f"{local_path} is (or is inside) a credential file or directory; "
941
+ "it is never uploaded",
942
+ )
943
+ if not p.is_file():
944
+ raise ToolError("invalid_argument", f"{local_path} is not a regular file")
945
+ return p
946
+
947
+ def upload(self, args: dict[str, Any]) -> ToolResult:
948
+ local = self._local(args["local_path"])
949
+ sbx = self._sandbox(args["sandbox_id"])
950
+ dest = sbx.files.relative(args.get("path") or local.name)
951
+ if not dest:
952
+ raise ToolError(
953
+ "invalid_argument", "path must name a file, not the sandbox root"
954
+ )
955
+ size = local.stat().st_size
956
+ chunk = UPLOAD_CHUNK_BYTES if size >= UPLOAD_CHUNK_BYTES else None
957
+ with local.open("rb") as f:
958
+ # Under 8 MiB: one request with a known length, which the SDK may
959
+ # retry on a 503; from 8 MiB: 8 MiB pieces, read one at a time.
960
+ sbx.files.write(dest, f.read() if chunk is None else f, chunk_size=chunk)
961
+ chunks = -(-size // UPLOAD_CHUNK_BYTES) if chunk else 1
962
+ return _json_result({"path": dest, "bytes": size, "requests": max(1, chunks)})
963
+
964
+ # --- session end ----------------------------------------------------------------------
965
+
966
+ def close(self) -> None:
967
+ """End the session: delete what it created (``cleanup_on_exit``), drop every token.
968
+
969
+ A ``create_sandbox`` still running counts as created: its request is
970
+ replayed under the same idempotency key without waiting, which returns
971
+ the sandbox at once, and that sandbox is deleted too. A second call
972
+ returns only once the first has finished.
973
+ """
974
+ with self._close_lock:
975
+ self._close()
976
+
977
+ def _close(self) -> None:
978
+ with self._s.lock:
979
+ if self._closed:
980
+ return
981
+ self._closed = True
982
+ created, self._s.created = list(self._s.created), []
983
+ creating, self._s.creating = dict(self._s.creating), {}
984
+ held, self._s.held = dict(self._s.held), {}
985
+ if self.settings.cleanup_on_exit:
986
+ for create in creating.values():
987
+ try:
988
+ replayed = create.run(self.client, wait=False)
989
+ except Exception as e: # noqa: BLE001 -- keep deleting the rest
990
+ log.warning("could not find a sandbox still being created: %s", e)
991
+ continue
992
+ held.setdefault(replayed.id, replayed)
993
+ if replayed.id not in created:
994
+ created.append(replayed.id)
995
+ for sandbox_id in created:
996
+ sbx = held.get(sandbox_id) or Sandbox(
997
+ pb.Sandbox(id=sandbox_id), client=self.client
998
+ )
999
+ try:
1000
+ sbx.delete()
1001
+ log.info("deleted sandbox %s at session end", sandbox_id)
1002
+ except errors.NotFound:
1003
+ pass
1004
+ except Exception as e: # noqa: BLE001 -- keep deleting the rest
1005
+ log.warning("could not delete sandbox %s: %s", sandbox_id, e)
1006
+ for sbx in held.values():
1007
+ sbx.close()