@tangle-network/sandbox 0.0.0-develop.20260519182220.e7047bf → 0.0.0-develop.20260530132002.87cf9f6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +449 -16
- package/dist/agent/index.d.ts +433 -0
- package/dist/agent/index.js +1 -0
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.js +1 -1
- package/dist/client-CygjzF3v.js +1 -0
- package/dist/{errors-DiKmk2CM.d.ts → client-DM2pIli7.d.ts} +66 -134
- package/dist/collaboration/index.d.ts +1 -1
- package/dist/collaboration/index.js +1 -1
- package/dist/collaboration-CRyb5e8F.js +1 -1
- package/dist/core.d.ts +3 -2
- package/dist/core.js +1 -1
- package/dist/errors-1Se5ATyZ.d.ts +128 -0
- package/dist/errors-CljiGR__.js +1 -1
- package/dist/{index-CLZs55w_.d.ts → index-CTj81tF9.d.ts} +1 -1
- package/dist/index.d.ts +256 -7
- package/dist/index.js +1 -1
- package/dist/openai/index.d.ts +21 -6
- package/dist/openai/index.js +1 -1
- package/dist/{sandbox-B7-dr4K1.d.ts → sandbox-CBmfYqMQ.d.ts} +366 -121
- package/dist/sandbox-DTup2jzz.js +1 -0
- package/dist/session-gateway/index.js +1 -1
- package/dist/tangle/index.d.ts +1 -1
- package/dist/tangle/index.js +1 -1
- package/dist/tangle-CnYnTRi6.js +1 -0
- package/package.json +17 -8
- package/dist/client-DFFqzEf3.js +0 -1
- package/dist/platform-integrations.d.ts +0 -2
- package/dist/platform-integrations.js +0 -1
- package/dist/sandbox-CHsHtmjx.js +0 -1
- package/dist/tangle-DwLVHGvt.js +0 -1
- /package/dist/{index-Dpj1oB5i.d.ts → index-D-2pH_70.d.ts} +0 -0
- /package/dist/{index-CCsA3S0D.d.ts → index-D7bwmNs8.d.ts} +0 -0
|
@@ -1,87 +1,3 @@
|
|
|
1
|
-
import { IntegrationActor, IntegrationManifest } from "@tangle-network/agent-integrations";
|
|
2
|
-
|
|
3
|
-
//#region src/mcp.d.ts
|
|
4
|
-
/**
|
|
5
|
-
* MCP (Model Context Protocol) helpers for sandbox capabilities.
|
|
6
|
-
*
|
|
7
|
-
* The sandbox exposes capabilities (currently `computer_use`, more
|
|
8
|
-
* later) as MCP tools over Streamable HTTP. Any MCP-capable client —
|
|
9
|
-
* Claude Desktop, Cursor, claude-code, codex, opencode, raw
|
|
10
|
-
* `@modelcontextprotocol/sdk` apps — can consume this surface by
|
|
11
|
-
* pasting the JSON returned from `Sandbox#getMcpEndpoint()` (or
|
|
12
|
-
* `buildSandboxMcpConfig` if you already have the URL + token) into
|
|
13
|
-
* the client's MCP config.
|
|
14
|
-
*
|
|
15
|
-
* Security model:
|
|
16
|
-
* - Tokens are capability-scoped JWTs (claim `cap: ["computer_use"]`).
|
|
17
|
-
* - Full sandbox runtime tokens are rejected on `/mcp`; only
|
|
18
|
-
* capability-scoped tokens work there.
|
|
19
|
-
* - A scoped token cannot pivot to admin endpoints (`/exec`, `/files`,
|
|
20
|
-
* etc.) — those routes reject scoped tokens.
|
|
21
|
-
* - Tokens are short-lived. Rotate via `Sandbox#getMcpEndpoint()`,
|
|
22
|
-
* which mints a fresh token each call.
|
|
23
|
-
*/
|
|
24
|
-
/** Default name of the MCP server entry — surfaces in the host UI. */
|
|
25
|
-
declare const SANDBOX_MCP_SERVER_NAME = "tangle-sandbox";
|
|
26
|
-
/**
|
|
27
|
-
* MCP HTTP server entry — matches the Anthropic MCP HTTP transport
|
|
28
|
-
* schema (`type: "http"`, `url`, optional `headers`). Compatible with
|
|
29
|
-
* every MCP host that implements the spec.
|
|
30
|
-
*/
|
|
31
|
-
interface SandboxMcpServerEntry {
|
|
32
|
-
type: "http";
|
|
33
|
-
url: string;
|
|
34
|
-
headers: Record<string, string>;
|
|
35
|
-
}
|
|
36
|
-
/**
|
|
37
|
-
* `.mcp.json`-shaped config any MCP host accepts. Drop the contents of
|
|
38
|
-
* `mcpServers` into your host's `mcpServers` block (Claude Desktop,
|
|
39
|
-
* Cursor, claude-code's `--mcp-config`, etc.) — no host-specific
|
|
40
|
-
* fields, no provider lock-in.
|
|
41
|
-
*/
|
|
42
|
-
interface SandboxMcpConfig {
|
|
43
|
-
mcpServers: Record<string, SandboxMcpServerEntry>;
|
|
44
|
-
}
|
|
45
|
-
/**
|
|
46
|
-
* Endpoint payload returned by `GET /v1/sandboxes/:id/mcp`. Includes
|
|
47
|
-
* the canonical config plus token expiry so callers can plan
|
|
48
|
-
* refreshes.
|
|
49
|
-
*/
|
|
50
|
-
interface SandboxMcpEndpoint {
|
|
51
|
-
/** MCP host config — paste this into Cursor/Claude Desktop/etc. */
|
|
52
|
-
config: SandboxMcpConfig;
|
|
53
|
-
/** Server entry name used inside `config.mcpServers`. */
|
|
54
|
-
serverName: string;
|
|
55
|
-
/** Reachable URL for the MCP HTTP transport. */
|
|
56
|
-
url: string;
|
|
57
|
-
/** Bearer token sent by the MCP host on every request. */
|
|
58
|
-
authToken: string;
|
|
59
|
-
/** ISO-8601 expiry — the host should refresh before this. */
|
|
60
|
-
expiresAt: string;
|
|
61
|
-
/** Capabilities the token is scoped to. */
|
|
62
|
-
capabilities: ReadonlyArray<"computer_use">;
|
|
63
|
-
}
|
|
64
|
-
interface BuildSandboxMcpConfigOptions {
|
|
65
|
-
/** Public sandbox URL where `/mcp` is reachable. No trailing slash. */
|
|
66
|
-
sandboxUrl: string;
|
|
67
|
-
/** Capability-scoped JWT minted by the Sandbox API. */
|
|
68
|
-
authToken: string;
|
|
69
|
-
/** Override the entry name. Defaults to SANDBOX_MCP_SERVER_NAME. */
|
|
70
|
-
serverName?: string;
|
|
71
|
-
}
|
|
72
|
-
/**
|
|
73
|
-
* Build the canonical `mcpServers` config for a sandbox MCP endpoint.
|
|
74
|
-
* Pure function — no I/O, no crypto. Use this when you already have a
|
|
75
|
-
* `{ url, authToken }` pair from the API and just want the JSON shape
|
|
76
|
-
* to paste into a host. Most callers should use
|
|
77
|
-
* `Sandbox#getMcpEndpoint()` instead, which fetches a freshly-minted
|
|
78
|
-
* token from the API.
|
|
79
|
-
*/
|
|
80
|
-
declare function buildSandboxMcpConfig(options: BuildSandboxMcpConfigOptions): {
|
|
81
|
-
serverName: string;
|
|
82
|
-
config: SandboxMcpConfig;
|
|
83
|
-
};
|
|
84
|
-
//#endregion
|
|
85
1
|
//#region src/agent-profile.d.ts
|
|
86
2
|
/**
|
|
87
3
|
* Provider-neutral agent profile types for public SDK consumers.
|
|
@@ -776,37 +692,6 @@ interface CreateSandboxOptions {
|
|
|
776
692
|
resources?: SandboxResources;
|
|
777
693
|
/** Environment variables injected into the sandbox */
|
|
778
694
|
env?: Record<string, string>;
|
|
779
|
-
/**
|
|
780
|
-
* Integration requirements the sandbox app needs at launch.
|
|
781
|
-
*
|
|
782
|
-
* The sandbox API resolves this manifest through id.tangle.tools,
|
|
783
|
-
* creates owner-scoped grants, and injects only a short-lived
|
|
784
|
-
* `TANGLE_INTEGRATION_BUNDLE` capability payload. Raw provider OAuth
|
|
785
|
-
* tokens and API keys never enter the sandbox environment.
|
|
786
|
-
*/
|
|
787
|
-
integrationManifest?: IntegrationManifest;
|
|
788
|
-
/**
|
|
789
|
-
* Existing platform grant ids to bind to this launch.
|
|
790
|
-
*
|
|
791
|
-
* Use this for installed templates or pre-consented apps where the
|
|
792
|
-
* installer owns the connection. The sandbox API still requires
|
|
793
|
-
* `integrationManifest` so platform can fail closed if a grant does not
|
|
794
|
-
* match the declared requirements.
|
|
795
|
-
*/
|
|
796
|
-
integrationGrantIds?: string[];
|
|
797
|
-
/**
|
|
798
|
-
* Grant durability for `integrationManifest`.
|
|
799
|
-
*
|
|
800
|
-
* `preview` scopes consent to this sandbox preview/session,
|
|
801
|
-
* `durable-app` is for installed/generated app instances, and
|
|
802
|
-
* `one-shot` is for a single workflow run.
|
|
803
|
-
*/
|
|
804
|
-
integrationGrantMode?: "preview" | "durable-app" | "one-shot";
|
|
805
|
-
/**
|
|
806
|
-
* Logical app/agent subject receiving the grant. When omitted, the
|
|
807
|
-
* sandbox itself is the grantee and runtime subject.
|
|
808
|
-
*/
|
|
809
|
-
integrationSubject?: IntegrationActor;
|
|
810
695
|
/**
|
|
811
696
|
* Maximum lifetime in seconds.
|
|
812
697
|
* Sandbox is automatically deleted after this time.
|
|
@@ -1157,7 +1042,7 @@ interface ExecOptions {
|
|
|
1157
1042
|
*
|
|
1158
1043
|
* @example Search TypeScript files
|
|
1159
1044
|
* ```typescript
|
|
1160
|
-
* const matches = await box.search("
|
|
1045
|
+
* const matches = await box.search("export function", {
|
|
1161
1046
|
* glob: "**\/*.ts",
|
|
1162
1047
|
* maxResults: 100,
|
|
1163
1048
|
* });
|
|
@@ -1332,6 +1217,31 @@ interface PromptOptions {
|
|
|
1332
1217
|
context?: Record<string, unknown>;
|
|
1333
1218
|
/** AbortSignal for cancellation */
|
|
1334
1219
|
signal?: AbortSignal;
|
|
1220
|
+
/**
|
|
1221
|
+
* Stable execution id for cross-process reconnect. When passed, the same
|
|
1222
|
+
* id on a retry lands on the same substrate execution — the platform
|
|
1223
|
+
* replays its buffered event stream instead of spawning a duplicate run.
|
|
1224
|
+
* Forwarded as the `X-Execution-ID` header. Omit to let the SDK extract
|
|
1225
|
+
* one from the response stream's `execution.started` event (in-call
|
|
1226
|
+
* reconnect only).
|
|
1227
|
+
*/
|
|
1228
|
+
executionId?: string;
|
|
1229
|
+
/**
|
|
1230
|
+
* Last event id the caller has already acknowledged. The substrate
|
|
1231
|
+
* replays strictly after this id on reconnect. Forwarded as the
|
|
1232
|
+
* `Last-Event-ID` header. Omit on first attempt.
|
|
1233
|
+
*/
|
|
1234
|
+
lastEventId?: string;
|
|
1235
|
+
/**
|
|
1236
|
+
* Caller-supplied turn idempotency key. When set, a retry with the
|
|
1237
|
+
* same `turnId` on the same `sessionId` short-circuits to the cached
|
|
1238
|
+
* result instead of re-issuing the upstream LLM call. Generate a
|
|
1239
|
+
* fresh `turnId` per logical attempt (a different user message gets
|
|
1240
|
+
* a new id) and reuse it only for retries of the same intent
|
|
1241
|
+
* (Stripe-style idempotency). Combine with `box.findCompletedTurn`
|
|
1242
|
+
* to check completion before re-dispatching.
|
|
1243
|
+
*/
|
|
1244
|
+
turnId?: string;
|
|
1335
1245
|
}
|
|
1336
1246
|
/**
|
|
1337
1247
|
* SSE event from sandbox streaming.
|
|
@@ -1403,12 +1313,22 @@ interface SandboxTraceOptions {
|
|
|
1403
1313
|
*/
|
|
1404
1314
|
includeIntelligence?: boolean;
|
|
1405
1315
|
}
|
|
1406
|
-
|
|
1316
|
+
/**
|
|
1317
|
+
* Subject types for an Intelligence Report.
|
|
1318
|
+
*
|
|
1319
|
+
* - `sandbox`: one container's run.
|
|
1320
|
+
* - `fleet`: one managed grouping of sandboxes. Add `subject.dispatchId`
|
|
1321
|
+
* to narrow to a single coordinated command within the fleet
|
|
1322
|
+
* (previously a standalone `dispatch` subject type — now expressed
|
|
1323
|
+
* as a fleet refinement).
|
|
1324
|
+
*/
|
|
1325
|
+
type IntelligenceReportSubjectType = "sandbox" | "fleet";
|
|
1407
1326
|
interface IntelligenceReport {
|
|
1408
1327
|
jobId: string;
|
|
1409
1328
|
subject: {
|
|
1410
1329
|
type: IntelligenceReportSubjectType;
|
|
1411
|
-
id: string;
|
|
1330
|
+
id: string; /** Present when the report was narrowed to a single fleet dispatch. */
|
|
1331
|
+
dispatchId?: string;
|
|
1412
1332
|
};
|
|
1413
1333
|
mode: "deterministic" | "agentic";
|
|
1414
1334
|
status: "queued" | "running" | "completed" | "failed";
|
|
@@ -1429,10 +1349,41 @@ interface IntelligenceReportBudget {
|
|
|
1429
1349
|
maxUsd?: number;
|
|
1430
1350
|
billTo?: "customer" | "platform";
|
|
1431
1351
|
}
|
|
1352
|
+
/**
|
|
1353
|
+
* Time window for an intelligence report. Both bounds are millisecond
|
|
1354
|
+
* epochs. Omit `since` to mean "from the subject's first observation";
|
|
1355
|
+
* omit `until` to mean "now". `since` must be <= `until` when both are
|
|
1356
|
+
* set; the server enforces this at the schema layer.
|
|
1357
|
+
*/
|
|
1358
|
+
interface IntelligenceReportWindow {
|
|
1359
|
+
since?: number;
|
|
1360
|
+
until?: number;
|
|
1361
|
+
}
|
|
1362
|
+
/**
|
|
1363
|
+
* Comparison baseline. When present, the report includes an explicit
|
|
1364
|
+
* delta between the primary subject and this baseline. Must be the
|
|
1365
|
+
* same `type` as the primary subject — the analyzer rejects mixed
|
|
1366
|
+
* subject-type comparisons because the delta would be meaningless.
|
|
1367
|
+
*
|
|
1368
|
+
* `dispatchId` is only valid when `type === "fleet"`.
|
|
1369
|
+
*/
|
|
1370
|
+
interface IntelligenceReportCompareTo {
|
|
1371
|
+
type: IntelligenceReportSubjectType;
|
|
1372
|
+
id: string;
|
|
1373
|
+
/** Narrow the baseline to a single dispatch within the fleet. */
|
|
1374
|
+
dispatchId?: string;
|
|
1375
|
+
}
|
|
1432
1376
|
interface CreateIntelligenceReportOptions {
|
|
1433
1377
|
subject: {
|
|
1434
1378
|
type: IntelligenceReportSubjectType;
|
|
1435
1379
|
id: string;
|
|
1380
|
+
/**
|
|
1381
|
+
* Narrow the analysis to a single coordinated command within a
|
|
1382
|
+
* fleet. Only valid when `type === "fleet"`.
|
|
1383
|
+
*/
|
|
1384
|
+
dispatchId?: string; /** Bound the analysis to a time window. */
|
|
1385
|
+
window?: IntelligenceReportWindow; /** Compare the primary subject against a same-type baseline. */
|
|
1386
|
+
compareTo?: IntelligenceReportCompareTo;
|
|
1436
1387
|
};
|
|
1437
1388
|
mode?: "deterministic" | "agentic";
|
|
1438
1389
|
acknowledgeCost?: boolean;
|
|
@@ -1706,6 +1657,67 @@ interface DispatchPromptOptions extends PromptOptions {
|
|
|
1706
1657
|
* by construction. */
|
|
1707
1658
|
sessionId?: string;
|
|
1708
1659
|
}
|
|
1660
|
+
/**
|
|
1661
|
+
* Options for `box.messages()` — list messages on a session including
|
|
1662
|
+
* mid-turn partial assistant content.
|
|
1663
|
+
*/
|
|
1664
|
+
interface ListMessagesOptions {
|
|
1665
|
+
/** Session id whose messages to return (required). */
|
|
1666
|
+
sessionId: string;
|
|
1667
|
+
/** Max entries, default 100. Server caps at 1000. */
|
|
1668
|
+
limit?: number;
|
|
1669
|
+
/** Skip this many entries from the start. */
|
|
1670
|
+
offset?: number;
|
|
1671
|
+
/** Only return messages newer than this Unix-ms timestamp. */
|
|
1672
|
+
since?: number;
|
|
1673
|
+
}
|
|
1674
|
+
/**
|
|
1675
|
+
* One message on a session — user, assistant, or system. The metadata
|
|
1676
|
+
* field carries the durability marker set by the sidecar:
|
|
1677
|
+
* - `status: "streaming"` and no `completed`/`interrupted` flag → turn
|
|
1678
|
+
* is in flight, OR the sidecar died before stamping a marker
|
|
1679
|
+
* (SIGKILL, OOM). The partial parts are the partial assistant
|
|
1680
|
+
* content the recorder flushed before death.
|
|
1681
|
+
* - `completed: true` + `completedAt` → turn finished normally. If a
|
|
1682
|
+
* `turnId` was supplied, its result is cached for idempotent retry.
|
|
1683
|
+
* - `interrupted: true` + `interruptedAt` + `interruptReason` → graceful
|
|
1684
|
+
* abort, timeout, or upstream error. Partial content is preserved
|
|
1685
|
+
* but not billable as a completion.
|
|
1686
|
+
*/
|
|
1687
|
+
interface SessionMessage {
|
|
1688
|
+
id: string;
|
|
1689
|
+
role: "user" | "assistant" | "system";
|
|
1690
|
+
/** ISO timestamp string. */
|
|
1691
|
+
timestamp: string;
|
|
1692
|
+
/** Message parts (text, tool calls, reasoning, files). Same shape as
|
|
1693
|
+
* events emitted by `streamPrompt`. */
|
|
1694
|
+
parts: unknown[];
|
|
1695
|
+
/** Durability + idempotency metadata. See class doc above. */
|
|
1696
|
+
metadata?: {
|
|
1697
|
+
status?: "streaming" | "completed" | "interrupted";
|
|
1698
|
+
completed?: boolean;
|
|
1699
|
+
completedAt?: string;
|
|
1700
|
+
interrupted?: boolean;
|
|
1701
|
+
interruptedAt?: string;
|
|
1702
|
+
interruptReason?: string;
|
|
1703
|
+
turnId?: string;
|
|
1704
|
+
startedAt?: string;
|
|
1705
|
+
[extra: string]: unknown;
|
|
1706
|
+
};
|
|
1707
|
+
}
|
|
1708
|
+
/**
|
|
1709
|
+
* Returned by `box.findCompletedTurn()` — the cached result of a
|
|
1710
|
+
* previously-completed turn, keyed on the caller's `turnId`.
|
|
1711
|
+
*/
|
|
1712
|
+
interface CompletedTurnResult {
|
|
1713
|
+
turnId: string;
|
|
1714
|
+
sessionId: string;
|
|
1715
|
+
/** ISO timestamp when the turn finished. */
|
|
1716
|
+
completedAt: string;
|
|
1717
|
+
/** The cached AgentExecutionResult-shape payload (text, toolInvocations,
|
|
1718
|
+
* sessionId, tokenUsage, etc.). */
|
|
1719
|
+
result: Record<string, unknown>;
|
|
1720
|
+
}
|
|
1709
1721
|
/**
|
|
1710
1722
|
* Returned by `box.dispatchPrompt()` — minimum the caller needs to track
|
|
1711
1723
|
* the session afterward. The sandbox keeps running the prompt; use
|
|
@@ -3882,8 +3894,183 @@ interface FileSystem {
|
|
|
3882
3894
|
*/
|
|
3883
3895
|
exists(path: string): Promise<boolean>;
|
|
3884
3896
|
}
|
|
3897
|
+
/** Languages supported by the persistent code kernel. */
|
|
3898
|
+
type CodeLanguage = "python" | "node" | "typescript" | "bash";
|
|
3899
|
+
/**
|
|
3900
|
+
* One structured result produced by a runCode() call. The kernel emits these
|
|
3901
|
+
* alongside stdout — matplotlib figures arrive as `image`, pandas DataFrames
|
|
3902
|
+
* as `dataframe`, explicit `display(value)` calls as `json` or `html`, and
|
|
3903
|
+
* uncaught exceptions as `error` plus an `error` field on the result.
|
|
3904
|
+
*/
|
|
3905
|
+
type CodeResultPart = {
|
|
3906
|
+
type: "text";
|
|
3907
|
+
value: string;
|
|
3908
|
+
} | {
|
|
3909
|
+
type: "json";
|
|
3910
|
+
value: unknown;
|
|
3911
|
+
} | {
|
|
3912
|
+
type: "image";
|
|
3913
|
+
format: "png" | "jpeg" | "svg"; /** base64-encoded image bytes (no `data:` prefix). */
|
|
3914
|
+
data: string;
|
|
3915
|
+
} | {
|
|
3916
|
+
type: "html";
|
|
3917
|
+
value: string;
|
|
3918
|
+
} | {
|
|
3919
|
+
type: "dataframe";
|
|
3920
|
+
columns: {
|
|
3921
|
+
name: string;
|
|
3922
|
+
dtype: string;
|
|
3923
|
+
}[];
|
|
3924
|
+
rows: unknown[][];
|
|
3925
|
+
truncated: boolean;
|
|
3926
|
+
} | {
|
|
3927
|
+
type: "error";
|
|
3928
|
+
name: string;
|
|
3929
|
+
message: string;
|
|
3930
|
+
traceback?: string;
|
|
3931
|
+
};
|
|
3932
|
+
/**
|
|
3933
|
+
* Outcome of a single runCode() call.
|
|
3934
|
+
*
|
|
3935
|
+
* `stdout`/`stderr` are the user-visible streams with frame markers stripped.
|
|
3936
|
+
* `results` is the structured-result list. `error` is set when user code
|
|
3937
|
+
* raised; the kernel itself stays alive and the next call reuses its state.
|
|
3938
|
+
*/
|
|
3939
|
+
interface CodeExecutionResult {
|
|
3940
|
+
exitCode: number;
|
|
3941
|
+
stdout: string;
|
|
3942
|
+
stderr: string;
|
|
3943
|
+
durationMs: number;
|
|
3944
|
+
results: CodeResultPart[];
|
|
3945
|
+
error?: {
|
|
3946
|
+
name: string;
|
|
3947
|
+
message: string;
|
|
3948
|
+
traceback?: string;
|
|
3949
|
+
};
|
|
3950
|
+
}
|
|
3951
|
+
/** Options for `box.runCode()`. */
|
|
3952
|
+
interface CodeExecutionOptions {
|
|
3953
|
+
/** Session scope: kernels persist variables across calls with the same id. */
|
|
3954
|
+
sessionId?: string;
|
|
3955
|
+
/** Per-call timeout in ms. 0 disables. Default 60_000. */
|
|
3956
|
+
timeoutMs?: number;
|
|
3957
|
+
/** Extra env vars merged in for this call only. */
|
|
3958
|
+
env?: Record<string, string>;
|
|
3959
|
+
/** Working directory override (honored on kernel creation only). */
|
|
3960
|
+
cwd?: string;
|
|
3961
|
+
/**
|
|
3962
|
+
* Caller-supplied dedup key. Two `runCode` calls with the same key and
|
|
3963
|
+
* the same `sessionId` within a 15-minute window return the same result
|
|
3964
|
+
* without re-executing — including the case where the second call arrives
|
|
3965
|
+
* while the first is still running (it awaits the in-flight result).
|
|
3966
|
+
*
|
|
3967
|
+
* Scoped per `sessionId` so two sessions reusing the same key stay
|
|
3968
|
+
* isolated. A failed execution is not cached; a retry with the same key
|
|
3969
|
+
* gets a fresh attempt.
|
|
3970
|
+
*
|
|
3971
|
+
* For exactly-once across an outer agent loop (multi-turn tool use), pair
|
|
3972
|
+
* with `box.dispatchPrompt({ sessionId, turnId })` — the agent layer
|
|
3973
|
+
* dedups the whole loop, this one dedups a single code-exec call.
|
|
3974
|
+
*/
|
|
3975
|
+
idempotencyKey?: string;
|
|
3976
|
+
}
|
|
3977
|
+
//#endregion
|
|
3978
|
+
//#region src/mcp.d.ts
|
|
3979
|
+
/**
|
|
3980
|
+
* MCP (Model Context Protocol) helpers for sandbox capabilities.
|
|
3981
|
+
*
|
|
3982
|
+
* The sandbox exposes capabilities (currently `computer_use`, more
|
|
3983
|
+
* later) as MCP tools over Streamable HTTP. Any MCP-capable client —
|
|
3984
|
+
* Claude Desktop, Cursor, claude-code, codex, opencode, raw
|
|
3985
|
+
* `@modelcontextprotocol/sdk` apps — can consume this surface by
|
|
3986
|
+
* pasting the JSON returned from `Sandbox#getMcpEndpoint()` (or
|
|
3987
|
+
* `buildSandboxMcpConfig` if you already have the URL + token) into
|
|
3988
|
+
* the client's MCP config.
|
|
3989
|
+
*
|
|
3990
|
+
* Security model:
|
|
3991
|
+
* - Tokens are capability-scoped JWTs (claim `cap: ["computer_use"]`).
|
|
3992
|
+
* - Full sandbox runtime tokens are rejected on `/mcp`; only
|
|
3993
|
+
* capability-scoped tokens work there.
|
|
3994
|
+
* - A scoped token cannot pivot to admin endpoints (`/exec`, `/files`,
|
|
3995
|
+
* etc.) — those routes reject scoped tokens.
|
|
3996
|
+
* - Tokens are short-lived. Rotate via `Sandbox#getMcpEndpoint()`,
|
|
3997
|
+
* which mints a fresh token each call.
|
|
3998
|
+
*/
|
|
3999
|
+
/** Default name of the MCP server entry — surfaces in the host UI. */
|
|
4000
|
+
declare const SANDBOX_MCP_SERVER_NAME = "tangle-sandbox";
|
|
4001
|
+
/**
|
|
4002
|
+
* MCP HTTP server entry — matches the Anthropic MCP HTTP transport
|
|
4003
|
+
* schema (`type: "http"`, `url`, optional `headers`). Compatible with
|
|
4004
|
+
* every MCP host that implements the spec.
|
|
4005
|
+
*/
|
|
4006
|
+
interface SandboxMcpServerEntry {
|
|
4007
|
+
type: "http";
|
|
4008
|
+
url: string;
|
|
4009
|
+
headers: Record<string, string>;
|
|
4010
|
+
}
|
|
4011
|
+
/**
|
|
4012
|
+
* `.mcp.json`-shaped config any MCP host accepts. Drop the contents of
|
|
4013
|
+
* `mcpServers` into your host's `mcpServers` block (Claude Desktop,
|
|
4014
|
+
* Cursor, claude-code's `--mcp-config`, etc.) — no host-specific
|
|
4015
|
+
* fields, no provider lock-in.
|
|
4016
|
+
*/
|
|
4017
|
+
interface SandboxMcpConfig {
|
|
4018
|
+
mcpServers: Record<string, SandboxMcpServerEntry>;
|
|
4019
|
+
}
|
|
4020
|
+
/**
|
|
4021
|
+
* Endpoint payload returned by `GET /v1/sandboxes/:id/mcp`. Includes
|
|
4022
|
+
* the canonical config plus token expiry so callers can plan
|
|
4023
|
+
* refreshes.
|
|
4024
|
+
*/
|
|
4025
|
+
interface SandboxMcpEndpoint {
|
|
4026
|
+
/** MCP host config — paste this into Cursor/Claude Desktop/etc. */
|
|
4027
|
+
config: SandboxMcpConfig;
|
|
4028
|
+
/** Server entry name used inside `config.mcpServers`. */
|
|
4029
|
+
serverName: string;
|
|
4030
|
+
/** Reachable URL for the MCP HTTP transport. */
|
|
4031
|
+
url: string;
|
|
4032
|
+
/** Bearer token sent by the MCP host on every request. */
|
|
4033
|
+
authToken: string;
|
|
4034
|
+
/** ISO-8601 expiry — the host should refresh before this. */
|
|
4035
|
+
expiresAt: string;
|
|
4036
|
+
/** Capabilities the token is scoped to. */
|
|
4037
|
+
capabilities: ReadonlyArray<"computer_use">;
|
|
4038
|
+
}
|
|
4039
|
+
interface BuildSandboxMcpConfigOptions {
|
|
4040
|
+
/** Public sandbox URL where `/mcp` is reachable. No trailing slash. */
|
|
4041
|
+
sandboxUrl: string;
|
|
4042
|
+
/** Capability-scoped JWT minted by the Sandbox API. */
|
|
4043
|
+
authToken: string;
|
|
4044
|
+
/** Override the entry name. Defaults to SANDBOX_MCP_SERVER_NAME. */
|
|
4045
|
+
serverName?: string;
|
|
4046
|
+
}
|
|
4047
|
+
/**
|
|
4048
|
+
* Build the canonical `mcpServers` config for a sandbox MCP endpoint.
|
|
4049
|
+
* Pure function — no I/O, no crypto. Use this when you already have a
|
|
4050
|
+
* `{ url, authToken }` pair from the API and just want the JSON shape
|
|
4051
|
+
* to paste into a host. Most callers should use
|
|
4052
|
+
* `Sandbox#getMcpEndpoint()` instead, which fetches a freshly-minted
|
|
4053
|
+
* token from the API.
|
|
4054
|
+
*/
|
|
4055
|
+
declare function buildSandboxMcpConfig(options: BuildSandboxMcpConfigOptions): {
|
|
4056
|
+
serverName: string;
|
|
4057
|
+
config: SandboxMcpConfig;
|
|
4058
|
+
};
|
|
3885
4059
|
//#endregion
|
|
3886
4060
|
//#region src/session.d.ts
|
|
4061
|
+
/**
|
|
4062
|
+
* The subset of `SandboxInstance` a `SandboxSession` drives. Declared here
|
|
4063
|
+
* (rather than importing the concrete class) so `session.ts` stays a leaf
|
|
4064
|
+
* of `sandbox.ts` — `sandbox.ts` constructs `SandboxSession`, so the reverse
|
|
4065
|
+
* import would form a cycle. `SandboxInstance` satisfies this structurally.
|
|
4066
|
+
*/
|
|
4067
|
+
interface SandboxSessionHost {
|
|
4068
|
+
prompt(message: string | PromptInputPart[], options?: PromptOptions): Promise<PromptResult>;
|
|
4069
|
+
_sessionStatus(id: string): Promise<SessionInfo | null>;
|
|
4070
|
+
_sessionEvents(id: string, opts?: SessionEventStreamOptions): AsyncGenerator<SandboxEvent>;
|
|
4071
|
+
_sessionResult(id: string): Promise<PromptResult>;
|
|
4072
|
+
_sessionCancel(id: string): Promise<void>;
|
|
4073
|
+
}
|
|
3887
4074
|
/**
|
|
3888
4075
|
* A single agent session inside a sandbox. Created via
|
|
3889
4076
|
* `box.session(id)` — does not hit the network until a method is called.
|
|
@@ -3895,7 +4082,7 @@ declare class SandboxSession {
|
|
|
3895
4082
|
/**
|
|
3896
4083
|
* @internal SDK-internal constructor — apps should call `box.session(id)`.
|
|
3897
4084
|
*/
|
|
3898
|
-
constructor(box:
|
|
4085
|
+
constructor(box: SandboxSessionHost, /** Stable session id assigned by the sandbox runtime. */
|
|
3899
4086
|
|
|
3900
4087
|
id: string);
|
|
3901
4088
|
/**
|
|
@@ -4166,6 +4353,34 @@ declare class SandboxInstance {
|
|
|
4166
4353
|
* Execute a command in the sandbox.
|
|
4167
4354
|
*/
|
|
4168
4355
|
exec(command: string, options?: ExecOptions): Promise<ExecResult>;
|
|
4356
|
+
/**
|
|
4357
|
+
* Run code in a persistent language kernel.
|
|
4358
|
+
*
|
|
4359
|
+
* Each `(sessionId, language)` pair gets its own long-lived kernel that
|
|
4360
|
+
* keeps variable state across calls — like Jupyter cells. Without a
|
|
4361
|
+
* `sessionId`, calls share a process-wide kernel per language.
|
|
4362
|
+
*
|
|
4363
|
+
* Returns typed results: stdout/stderr text plus a `results` array of
|
|
4364
|
+
* structured outputs (matplotlib images as base64 PNG, pandas DataFrames,
|
|
4365
|
+
* explicit `display(value)` calls as JSON/HTML, errors with traceback).
|
|
4366
|
+
*
|
|
4367
|
+
* @example Persistent Python session
|
|
4368
|
+
* ```ts
|
|
4369
|
+
* await box.runCode("python", "import pandas as pd; df = pd.DataFrame({'x': range(5)})", { sessionId: "s1" });
|
|
4370
|
+
* const r = await box.runCode("python", "df.describe()", { sessionId: "s1" });
|
|
4371
|
+
* // r.results[0] is a `dataframe` part with columns + rows from the describe()
|
|
4372
|
+
* ```
|
|
4373
|
+
*
|
|
4374
|
+
* @example Matplotlib chart
|
|
4375
|
+
* ```ts
|
|
4376
|
+
* const r = await box.runCode("python",
|
|
4377
|
+
* "import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.show()",
|
|
4378
|
+
* { sessionId: "s1" });
|
|
4379
|
+
* const png = r.results.find(p => p.type === "image");
|
|
4380
|
+
* // png.data is a base64 PNG ready to render or hand back to an LLM
|
|
4381
|
+
* ```
|
|
4382
|
+
*/
|
|
4383
|
+
runCode(language: CodeLanguage, source: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
|
|
4169
4384
|
/**
|
|
4170
4385
|
* Read a file from the sandbox.
|
|
4171
4386
|
*
|
|
@@ -4221,7 +4436,9 @@ declare class SandboxInstance {
|
|
|
4221
4436
|
mode?: "deterministic" | "agentic";
|
|
4222
4437
|
acknowledgeCost?: boolean;
|
|
4223
4438
|
budget?: IntelligenceReportBudget;
|
|
4224
|
-
metadata?: Record<string, unknown>;
|
|
4439
|
+
metadata?: Record<string, unknown>; /** Bound the analysis to a time window. */
|
|
4440
|
+
window?: IntelligenceReportWindow; /** Compare this sandbox against a same-type baseline sandbox. */
|
|
4441
|
+
compareTo?: IntelligenceReportCompareTo;
|
|
4225
4442
|
}): Promise<IntelligenceReport>;
|
|
4226
4443
|
createAgenticIntelligenceReport(options: {
|
|
4227
4444
|
maxUsd: number;
|
|
@@ -4850,6 +5067,34 @@ declare class SandboxInstance {
|
|
|
4850
5067
|
* construction.
|
|
4851
5068
|
*/
|
|
4852
5069
|
dispatchPrompt(message: string | PromptInputPart[], opts?: DispatchPromptOptions): Promise<DispatchedSession>;
|
|
5070
|
+
/**
|
|
5071
|
+
* List messages for a session, including in-flight assistant content
|
|
5072
|
+
* the agent is still streaming. Each entry's `metadata` carries the
|
|
5073
|
+
* durability marker — `status: "streaming" | "completed" | "interrupted"`,
|
|
5074
|
+
* `completed/interrupted` booleans, and the caller-supplied `turnId`
|
|
5075
|
+
* when one was set. See `SessionMessage` for the full contract.
|
|
5076
|
+
*
|
|
5077
|
+
* Polling this is the right way to detect "did the sidecar die mid-
|
|
5078
|
+
* turn?" — a SIGKILL leaves the assistant message with `status:
|
|
5079
|
+
* "streaming"` and no `completed`/`interrupted` marker; a graceful
|
|
5080
|
+
* abort stamps `interrupted: true` explicitly.
|
|
5081
|
+
*/
|
|
5082
|
+
messages(opts: ListMessagesOptions): Promise<SessionMessage[]>;
|
|
5083
|
+
/**
|
|
5084
|
+
* Look up a cached turn result by idempotency key. Returns the cached
|
|
5085
|
+
* payload if a turn with this `turnId` previously completed on the
|
|
5086
|
+
* given session; returns `null` if no such turn has finished yet
|
|
5087
|
+
* (either it never started, or it interrupted before completion).
|
|
5088
|
+
*
|
|
5089
|
+
* Call this before re-issuing a `streamPrompt` / `prompt` / `task`
|
|
5090
|
+
* that you might be retrying — a non-null result means the original
|
|
5091
|
+
* attempt finished and you can return that to your caller instead of
|
|
5092
|
+
* running the agent a second time. Only turns that reach the
|
|
5093
|
+
* `completed` terminal state are cached; interrupted turns are not.
|
|
5094
|
+
*/
|
|
5095
|
+
findCompletedTurn(turnId: string, opts: {
|
|
5096
|
+
sessionId: string;
|
|
5097
|
+
}): Promise<CompletedTurnResult | null>;
|
|
4853
5098
|
/**
|
|
4854
5099
|
* Mint a scoped, time-bounded JWT for direct browser access to this
|
|
4855
5100
|
* sandbox (Issue #913 Gap 1). Authority is the caller's
|
|
@@ -4872,4 +5117,4 @@ declare class SandboxInstance {
|
|
|
4872
5117
|
_sessionCancel(id: string): Promise<void>;
|
|
4873
5118
|
}
|
|
4874
5119
|
//#endregion
|
|
4875
|
-
export {
|
|
5120
|
+
export { DriverInfo as $, SandboxTraceOptions as $n, ProvisionEvent as $t, BatchTask as A, SandboxFleetMachineSpec as An, UsageInfo as Ar, ListMessagesOptions as At, CompletedTurnResult as B, SandboxFleetUsage as Bn, AgentProfileResourceRef as Br, PermissionsManager as Bt, BackendInfo as C, SandboxFleetDriverCapability as Cn, TeePublicKey as Cr, GpuType as Ct, BatchEvent as D, SandboxFleetMachine as Dn, UpdateUserOptions as Dr, IntelligenceReportCompareTo as Dt, BackendType as E, SandboxFleetIntelligenceEnvelope as En, ToolsConfig as Er, IntelligenceReportBudget as Et, CodeExecutionOptions as F, SandboxFleetToken as Fn, AgentProfileFileMount as Fr, MintScopedTokenOptions as Ft, CreateSandboxOptions as G, SandboxInfo as Gn, defineAgentProfile as Gr, ProcessLogEntry as Gt, CreateSandboxFleetOptions as H, SandboxFleetWorkspaceReconcileResult as Hn, AgentProfileValidationIssue as Hr, PreviewLinkManager as Ht, CodeExecutionResult as I, SandboxFleetTraceBundle as In, AgentProfileMcpServer as Ir, MkdirOptions as It, DispatchPromptOptions as J, SandboxResources as Jn, mergeAgentProfiles as Jr, ProcessSpawnOptions as Jt, DeleteOptions as K, SandboxIntelligenceEnvelope as Kn, defineGitHubResource as Kr, ProcessManager as Kt, CodeLanguage as L, SandboxFleetTraceEvent as Ln, AgentProfileModelHints as Lr, NetworkConfig as Lt, CheckpointInfo as M, SandboxFleetManifestMachine as Mn, AgentProfile as Mr, ListSandboxFleetOptions as Mt, CheckpointOptions as N, SandboxFleetOperationsSummary as Nn, AgentProfileCapabilities as Nr, ListSandboxOptions as Nt, BatchOptions as O, SandboxFleetMachineMeteredUsage as On, UploadOptions as Or, IntelligenceReportSubjectType as Ot, CheckpointResult as P, SandboxFleetPolicy as Pn, AgentProfileConfidential as Pr, McpServerConfig as Pt, DriverConfig as Q, SandboxTraceExport as Qn, PromptResult as Qt, CodeResult as R, SandboxFleetTraceExport as Rn, AgentProfilePermissionValue as Rr, NetworkManager as Rt, BackendConfig as S, SandboxFleetDispatchResponse as Sn, TeeAttestationResponse as Sr, GitStatus as St, BackendStatus as T, SandboxFleetInfo as Tn, TokenRefreshHandler as Tr, IntelligenceReport as Tt, CreateSandboxFleetTokenOptions as U, SandboxFleetWorkspaceRestoreResult as Un, AgentProfileValidationResult as Ur, Process as Ut, CreateIntelligenceReportOptions as V, SandboxFleetWorkspace as Vn, AgentProfileResources as Vr, PreviewLinkInfo as Vt, CreateSandboxFleetWithCoordinatorOptions as W, SandboxFleetWorkspaceSnapshotResult as Wn, AgentSubagentProfile as Wr, ProcessInfo as Wt, DownloadOptions as X, SandboxTraceBundle as Xn, PromptInputPart as Xt, DispatchedSession as Y, SandboxStatus as Yn, ProcessStatus as Yt, DownloadProgress as Z, SandboxTraceEvent as Zn, PromptOptions as Zt, AcceleratorKind as _, SandboxEvent as _n, SubscriptionInfo as _r, GitAuth as _t, TraceExportSink as a, PublishPublicTemplateOptions as an, SecretInfo as ar, FileSystem as at, AttachSandboxFleetMachineOptions as b, SandboxFleetCostEstimate as bn, TeeAttestationOptions as br, GitConfig as bt, otelTraceIdForTangleTrace as c, ReapExpiredSandboxFleetsResult as cn, SessionInfo as cr, FleetDispatchResultBufferOptions as ct, BuildSandboxMcpConfigOptions as d, RunCodeOptions as dn, SessionStatus as dr, FleetExecDispatchResult as dt, ProvisionResult as en, SandboxUser as er, DriverType as et, SANDBOX_MCP_SERVER_NAME as f, SSHCommandDescriptor as fn, SnapshotInfo as fr, FleetMachineId as ft, buildSandboxMcpConfig as g, SandboxEnvironment as gn, StorageConfig as gr, ForkResult as gt, SandboxMcpServerEntry as h, SandboxConnection as hn, SshKeysManager as hr, ForkOptions as ht, TraceExportResult as i, PublicTemplateVersionInfo as in, SearchOptions as ir, FileInfo as it, BatchTaskResult as j, SandboxFleetManifest as jn, WaitForOptions as jr, ListOptions as jt, BatchResult as k, SandboxFleetMachineRecord as kn, UploadProgress as kr, IntelligenceReportWindow as kt, toOtelJson as l, ReconcileSandboxFleetsOptions as ln, SessionListOptions as lr, FleetDispatchStreamOptions as lt, SandboxMcpEndpoint as m, SandboxClientConfig as mn, SnapshotResult as mr, FleetPromptDispatchResult as mt, SandboxInstance as n, ProvisionStep as nn, ScopedTokenScope as nr, ExecOptions as nt, buildTraceExportPayload as o, PublishPublicTemplateVersionOptions as on, SecretsManager as or, FleetDispatchCancelResult as ot, SandboxMcpConfig as p, SSHCredentials as pn, SnapshotOptions as pr, FleetPromptDispatchOptions as pt, DirectoryPermission as q, SandboxPermissionsConfig as qn, defineInlineResource as qr, ProcessSignal as qt, TraceExportFormat as r, PublicTemplateInfo as rn, SearchMatch as rr, ExecResult as rt, exportTraceBundle as s, ReapExpiredSandboxFleetsOptions as sn, SessionEventStreamOptions as sr, FleetDispatchResultBuffer as st, HttpClient as t, ProvisionStatus as tn, ScopedToken as tr, EventStreamOptions as tt, SandboxSession as u, ReconcileSandboxFleetsResult as un, SessionMessage as ur, FleetExecDispatchOptions as ut, AccessPolicyRule as v, SandboxFleetArtifact as vn, TaskOptions as vr, GitBranch as vt, BackendManager as w, SandboxFleetDriverTimings as wn, TeePublicKeyResponse as wr, InstalledTool as wt, BackendCapabilities as x, SandboxFleetDispatchFailureClass as xn, TeeAttestationReport as xr, GitDiff as xt, AddUserOptions as y, SandboxFleetArtifactSpec as yn, TaskResult as yr, GitCommit as yt, CodeResultPart as z, SandboxFleetTraceOptions as zn, AgentProfilePrompt as zr, PermissionLevel as zt };
|