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.
- devzero_sandbox/__init__.py +41 -0
- devzero_sandbox/_bgscript.py +104 -0
- devzero_sandbox/_proto/__init__.py +1 -0
- devzero_sandbox/_proto/sandbox/__init__.py +1 -0
- devzero_sandbox/_proto/sandbox/v1/__init__.py +1 -0
- devzero_sandbox/_proto/sandbox/v1/error_pb2.py +40 -0
- devzero_sandbox/_proto/sandbox/v1/error_pb2.pyi +23 -0
- devzero_sandbox/_proto/sandbox/v1/service_connect.py +381 -0
- devzero_sandbox/_proto/sandbox/v1/service_pb2.py +227 -0
- devzero_sandbox/_proto/sandbox/v1/service_pb2.pyi +898 -0
- devzero_sandbox/auth.py +363 -0
- devzero_sandbox/commands.py +818 -0
- devzero_sandbox/connect.py +381 -0
- devzero_sandbox/errors.py +453 -0
- devzero_sandbox/files.py +217 -0
- devzero_sandbox/incluster.py +42 -0
- devzero_sandbox/mcp/__init__.py +55 -0
- devzero_sandbox/mcp/__main__.py +7 -0
- devzero_sandbox/mcp/config.py +132 -0
- devzero_sandbox/mcp/server.py +259 -0
- devzero_sandbox/mcp/tools.py +1007 -0
- devzero_sandbox/py.typed +0 -0
- devzero_sandbox/redaction.py +78 -0
- devzero_sandbox/sandbox.py +634 -0
- devzero_sandbox/terminal.py +428 -0
- devzero_sandbox/transport.py +546 -0
- devzero_sandbox-0.1.0.dist-info/METADATA +113 -0
- devzero_sandbox-0.1.0.dist-info/RECORD +31 -0
- devzero_sandbox-0.1.0.dist-info/WHEEL +4 -0
- devzero_sandbox-0.1.0.dist-info/entry_points.txt +2 -0
- devzero_sandbox-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -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()
|