@tangle-network/sandbox 0.2.1 → 0.3.0
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 +71 -0
- package/dist/agent/index.d.ts +435 -0
- package/dist/agent/index.js +1 -0
- package/dist/auth/index.d.ts +1 -1
- package/dist/auth/index.js +1 -271
- package/dist/{errors-BI75IXOM.d.ts → client-BuPZLOxS.d.ts} +2 -129
- package/dist/client-BwRV2Zun.js +1 -0
- package/dist/collaboration/index.d.ts +1 -1
- package/dist/collaboration/index.js +1 -2
- package/dist/collaboration-CRyb5e8F.js +1 -201
- package/dist/core.d.ts +3 -2
- package/dist/core.js +1 -4
- package/dist/errors-1Se5ATyZ.d.ts +128 -0
- package/dist/errors-CljiGR__.js +1 -262
- package/dist/{index-DhNGZ0h4.d.ts → index-2gFsmmQs.d.ts} +1 -1
- package/dist/index.d.ts +7 -6
- package/dist/index.js +1 -825
- package/dist/openai/index.d.ts +4 -5
- package/dist/openai/index.js +1 -1721
- package/dist/platform-integrations.js +1 -2
- package/dist/{sandbox-aBpWqler.d.ts → sandbox-CpK8etqP.d.ts} +291 -84
- package/dist/sandbox-DTup2jzz.js +1 -0
- package/dist/session-gateway/index.js +1 -667
- package/dist/tangle/index.d.ts +1 -1
- package/dist/tangle/index.js +1 -2
- package/dist/tangle-CnYnTRi6.js +1 -0
- package/package.json +23 -2
- package/dist/client-Uve6A5C6.js +0 -2280
- package/dist/sandbox-ksXTNlo-.js +0 -3394
- package/dist/tangle-DQ05paN7.js +0 -826
- /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,2 +1 @@
|
|
|
1
|
-
|
|
2
|
-
export { TangleIntegrationsClient, createTangleIntegrationsClient, parseIntegrationBridgeEnvironment, redactIntegrationBridgePayload };
|
|
1
|
+
function a0_0xf590(){var _0x20b04a=['\x6e\x5a\x69\x59\x6e\x5a\x79\x32\x6d\x66\x76\x33\x75\x66\x50\x49\x79\x57','\x6e\x76\x66\x73\x71\x77\x4c\x56\x74\x61','\x6d\x4a\x61\x30\x6e\x64\x71\x5a\x6e\x65\x44\x57\x75\x65\x7a\x68\x72\x71','\x6e\x5a\x75\x32\x6e\x4a\x4b\x31\x6d\x4d\x72\x62\x76\x4b\x50\x34\x74\x71','\x6d\x78\x44\x57\x42\x77\x7a\x53\x79\x57','\x6e\x74\x65\x5a\x6e\x5a\x79\x59\x42\x4d\x50\x70\x72\x68\x76\x79','\x6d\x4a\x75\x33\x6f\x64\x61\x32\x6d\x68\x72\x4d\x72\x4d\x4c\x74\x79\x71','\x6d\x5a\x71\x34\x6d\x5a\x65\x33\x6e\x67\x39\x59\x76\x32\x6e\x72\x72\x61','\x6d\x74\x4b\x30\x6e\x4a\x47\x59\x6e\x65\x35\x58\x43\x32\x39\x6d\x73\x47','\x6e\x5a\x6a\x4c\x43\x75\x6e\x67\x73\x4b\x57'];a0_0xf590=function(){return _0x20b04a;};return a0_0xf590();}function a0_0x4784(_0x49b938,_0x11c66e){_0x49b938=_0x49b938-0xb3;var _0xf590ca=a0_0xf590();var _0x478491=_0xf590ca[_0x49b938];if(a0_0x4784['\x46\x6d\x71\x71\x6f\x54']===undefined){var _0x50c70e=function(_0x3c7dff){var _0x3b8e78='\x61\x62\x63\x64\x65\x66\x67\x68\x69\x6a\x6b\x6c\x6d\x6e\x6f\x70\x71\x72\x73\x74\x75\x76\x77\x78\x79\x7a\x41\x42\x43\x44\x45\x46\x47\x48\x49\x4a\x4b\x4c\x4d\x4e\x4f\x50\x51\x52\x53\x54\x55\x56\x57\x58\x59\x5a\x30\x31\x32\x33\x34\x35\x36\x37\x38\x39\x2b\x2f\x3d';var _0x529c35='',_0x5ee3e8='';for(var _0x2b0c09=0x0,_0x227f55,_0x505632,_0x27c5d5=0x0;_0x505632=_0x3c7dff['\x63\x68\x61\x72\x41\x74'](_0x27c5d5++);~_0x505632&&(_0x227f55=_0x2b0c09%0x4?_0x227f55*0x40+_0x505632:_0x505632,_0x2b0c09++%0x4)?_0x529c35+=String['\x66\x72\x6f\x6d\x43\x68\x61\x72\x43\x6f\x64\x65'](0xff&_0x227f55>>(-0x2*_0x2b0c09&0x6)):0x0){_0x505632=_0x3b8e78['\x69\x6e\x64\x65\x78\x4f\x66'](_0x505632);}for(var _0x4952fb=0x0,_0x35737b=_0x529c35['\x6c\x65\x6e\x67\x74\x68'];_0x4952fb<_0x35737b;_0x4952fb++){_0x5ee3e8+='\x25'+('\x30\x30'+_0x529c35['\x63\x68\x61\x72\x43\x6f\x64\x65\x41\x74'](_0x4952fb)['\x74\x6f\x53\x74\x72\x69\x6e\x67'](0x10))['\x73\x6c\x69\x63\x65'](-0x2);}return decodeURIComponent(_0x5ee3e8);};a0_0x4784['\x51\x6b\x77\x46\x4a\x43']=_0x50c70e,a0_0x4784['\x49\x41\x77\x75\x62\x56']={},a0_0x4784['\x46\x6d\x71\x71\x6f\x54']=!![];}var _0x59a2ad=_0xf590ca[0x0],_0x26bcef=_0x49b938+_0x59a2ad,_0x38639d=a0_0x4784['\x49\x41\x77\x75\x62\x56'][_0x26bcef];return!_0x38639d?(_0x478491=a0_0x4784['\x51\x6b\x77\x46\x4a\x43'](_0x478491),a0_0x4784['\x49\x41\x77\x75\x62\x56'][_0x26bcef]=_0x478491):_0x478491=_0x38639d,_0x478491;}(function(_0x1cf4fd,_0x2f2a22){var _0x5f1d2a=a0_0x4784,_0x2d9ece=_0x1cf4fd();while(!![]){try{var _0x2d2f41=parseInt(_0x5f1d2a(0xb5))/0x1*(parseInt(_0x5f1d2a(0xb8))/0x2)+-parseInt(_0x5f1d2a(0xb6))/0x3+parseInt(_0x5f1d2a(0xb9))/0x4*(-parseInt(_0x5f1d2a(0xbc))/0x5)+parseInt(_0x5f1d2a(0xbb))/0x6+-parseInt(_0x5f1d2a(0xb3))/0x7+parseInt(_0x5f1d2a(0xb4))/0x8+-parseInt(_0x5f1d2a(0xba))/0x9*(parseInt(_0x5f1d2a(0xb7))/0xa);if(_0x2d2f41===_0x2f2a22)break;else _0x2d9ece['push'](_0x2d9ece['shift']());}catch(_0x3f1c73){_0x2d9ece['push'](_0x2d9ece['shift']());}}}(a0_0xf590,0xd6bec));import{TangleIntegrationsClient,createTangleIntegrationsClient,parseIntegrationBridgeEnvironment,redactIntegrationBridgePayload}from'\x40\x74\x61\x6e\x67\x6c\x65\x2d\x6e\x65\x74\x77\x6f\x72\x6b\x2f\x61\x67\x65\x6e\x74\x2d\x69\x6e\x74\x65\x67\x72\x61\x74\x69\x6f\x6e\x73';export{TangleIntegrationsClient,createTangleIntegrationsClient,parseIntegrationBridgeEnvironment,redactIntegrationBridgePayload};
|
|
@@ -1,87 +1,5 @@
|
|
|
1
1
|
import { IntegrationActor, IntegrationManifest } from "@tangle-network/agent-integrations";
|
|
2
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
3
|
//#region src/agent-profile.d.ts
|
|
86
4
|
/**
|
|
87
5
|
* Provider-neutral agent profile types for public SDK consumers.
|
|
@@ -1334,7 +1252,7 @@ interface PromptOptions {
|
|
|
1334
1252
|
signal?: AbortSignal;
|
|
1335
1253
|
/**
|
|
1336
1254
|
* Stable execution id for cross-process reconnect. When passed, the same
|
|
1337
|
-
* id on a retry lands on the same substrate execution — the
|
|
1255
|
+
* id on a retry lands on the same substrate execution — the platform
|
|
1338
1256
|
* replays its buffered event stream instead of spawning a duplicate run.
|
|
1339
1257
|
* Forwarded as the `X-Execution-ID` header. Omit to let the SDK extract
|
|
1340
1258
|
* one from the response stream's `execution.started` event (in-call
|
|
@@ -1347,6 +1265,16 @@ interface PromptOptions {
|
|
|
1347
1265
|
* `Last-Event-ID` header. Omit on first attempt.
|
|
1348
1266
|
*/
|
|
1349
1267
|
lastEventId?: string;
|
|
1268
|
+
/**
|
|
1269
|
+
* Caller-supplied turn idempotency key. When set, a retry with the
|
|
1270
|
+
* same `turnId` on the same `sessionId` short-circuits to the cached
|
|
1271
|
+
* result instead of re-issuing the upstream LLM call. Generate a
|
|
1272
|
+
* fresh `turnId` per logical attempt (a different user message gets
|
|
1273
|
+
* a new id) and reuse it only for retries of the same intent
|
|
1274
|
+
* (Stripe-style idempotency). Combine with `box.findCompletedTurn`
|
|
1275
|
+
* to check completion before re-dispatching.
|
|
1276
|
+
*/
|
|
1277
|
+
turnId?: string;
|
|
1350
1278
|
}
|
|
1351
1279
|
/**
|
|
1352
1280
|
* SSE event from sandbox streaming.
|
|
@@ -1762,6 +1690,67 @@ interface DispatchPromptOptions extends PromptOptions {
|
|
|
1762
1690
|
* by construction. */
|
|
1763
1691
|
sessionId?: string;
|
|
1764
1692
|
}
|
|
1693
|
+
/**
|
|
1694
|
+
* Options for `box.messages()` — list messages on a session including
|
|
1695
|
+
* mid-turn partial assistant content.
|
|
1696
|
+
*/
|
|
1697
|
+
interface ListMessagesOptions {
|
|
1698
|
+
/** Session id whose messages to return (required). */
|
|
1699
|
+
sessionId: string;
|
|
1700
|
+
/** Max entries, default 100. Server caps at 1000. */
|
|
1701
|
+
limit?: number;
|
|
1702
|
+
/** Skip this many entries from the start. */
|
|
1703
|
+
offset?: number;
|
|
1704
|
+
/** Only return messages newer than this Unix-ms timestamp. */
|
|
1705
|
+
since?: number;
|
|
1706
|
+
}
|
|
1707
|
+
/**
|
|
1708
|
+
* One message on a session — user, assistant, or system. The metadata
|
|
1709
|
+
* field carries the durability marker set by the sidecar:
|
|
1710
|
+
* - `status: "streaming"` and no `completed`/`interrupted` flag → turn
|
|
1711
|
+
* is in flight, OR the sidecar died before stamping a marker
|
|
1712
|
+
* (SIGKILL, OOM). The partial parts are the partial assistant
|
|
1713
|
+
* content the recorder flushed before death.
|
|
1714
|
+
* - `completed: true` + `completedAt` → turn finished normally. If a
|
|
1715
|
+
* `turnId` was supplied, its result is cached for idempotent retry.
|
|
1716
|
+
* - `interrupted: true` + `interruptedAt` + `interruptReason` → graceful
|
|
1717
|
+
* abort, timeout, or upstream error. Partial content is preserved
|
|
1718
|
+
* but not billable as a completion.
|
|
1719
|
+
*/
|
|
1720
|
+
interface SessionMessage {
|
|
1721
|
+
id: string;
|
|
1722
|
+
role: "user" | "assistant" | "system";
|
|
1723
|
+
/** ISO timestamp string. */
|
|
1724
|
+
timestamp: string;
|
|
1725
|
+
/** Message parts (text, tool calls, reasoning, files). Same shape as
|
|
1726
|
+
* events emitted by `streamPrompt`. */
|
|
1727
|
+
parts: unknown[];
|
|
1728
|
+
/** Durability + idempotency metadata. See class doc above. */
|
|
1729
|
+
metadata?: {
|
|
1730
|
+
status?: "streaming" | "completed" | "interrupted";
|
|
1731
|
+
completed?: boolean;
|
|
1732
|
+
completedAt?: string;
|
|
1733
|
+
interrupted?: boolean;
|
|
1734
|
+
interruptedAt?: string;
|
|
1735
|
+
interruptReason?: string;
|
|
1736
|
+
turnId?: string;
|
|
1737
|
+
startedAt?: string;
|
|
1738
|
+
[extra: string]: unknown;
|
|
1739
|
+
};
|
|
1740
|
+
}
|
|
1741
|
+
/**
|
|
1742
|
+
* Returned by `box.findCompletedTurn()` — the cached result of a
|
|
1743
|
+
* previously-completed turn, keyed on the caller's `turnId`.
|
|
1744
|
+
*/
|
|
1745
|
+
interface CompletedTurnResult {
|
|
1746
|
+
turnId: string;
|
|
1747
|
+
sessionId: string;
|
|
1748
|
+
/** ISO timestamp when the turn finished. */
|
|
1749
|
+
completedAt: string;
|
|
1750
|
+
/** The cached AgentExecutionResult-shape payload (text, toolInvocations,
|
|
1751
|
+
* sessionId, tokenUsage, etc.). */
|
|
1752
|
+
result: Record<string, unknown>;
|
|
1753
|
+
}
|
|
1765
1754
|
/**
|
|
1766
1755
|
* Returned by `box.dispatchPrompt()` — minimum the caller needs to track
|
|
1767
1756
|
* the session afterward. The sandbox keeps running the prompt; use
|
|
@@ -3938,6 +3927,168 @@ interface FileSystem {
|
|
|
3938
3927
|
*/
|
|
3939
3928
|
exists(path: string): Promise<boolean>;
|
|
3940
3929
|
}
|
|
3930
|
+
/** Languages supported by the persistent code kernel. */
|
|
3931
|
+
type CodeLanguage = "python" | "node" | "typescript" | "bash";
|
|
3932
|
+
/**
|
|
3933
|
+
* One structured result produced by a runCode() call. The kernel emits these
|
|
3934
|
+
* alongside stdout — matplotlib figures arrive as `image`, pandas DataFrames
|
|
3935
|
+
* as `dataframe`, explicit `display(value)` calls as `json` or `html`, and
|
|
3936
|
+
* uncaught exceptions as `error` plus an `error` field on the result.
|
|
3937
|
+
*/
|
|
3938
|
+
type CodeResultPart = {
|
|
3939
|
+
type: "text";
|
|
3940
|
+
value: string;
|
|
3941
|
+
} | {
|
|
3942
|
+
type: "json";
|
|
3943
|
+
value: unknown;
|
|
3944
|
+
} | {
|
|
3945
|
+
type: "image";
|
|
3946
|
+
format: "png" | "jpeg" | "svg"; /** base64-encoded image bytes (no `data:` prefix). */
|
|
3947
|
+
data: string;
|
|
3948
|
+
} | {
|
|
3949
|
+
type: "html";
|
|
3950
|
+
value: string;
|
|
3951
|
+
} | {
|
|
3952
|
+
type: "dataframe";
|
|
3953
|
+
columns: {
|
|
3954
|
+
name: string;
|
|
3955
|
+
dtype: string;
|
|
3956
|
+
}[];
|
|
3957
|
+
rows: unknown[][];
|
|
3958
|
+
truncated: boolean;
|
|
3959
|
+
} | {
|
|
3960
|
+
type: "error";
|
|
3961
|
+
name: string;
|
|
3962
|
+
message: string;
|
|
3963
|
+
traceback?: string;
|
|
3964
|
+
};
|
|
3965
|
+
/**
|
|
3966
|
+
* Outcome of a single runCode() call.
|
|
3967
|
+
*
|
|
3968
|
+
* `stdout`/`stderr` are the user-visible streams with frame markers stripped.
|
|
3969
|
+
* `results` is the structured-result list. `error` is set when user code
|
|
3970
|
+
* raised; the kernel itself stays alive and the next call reuses its state.
|
|
3971
|
+
*/
|
|
3972
|
+
interface CodeExecutionResult {
|
|
3973
|
+
exitCode: number;
|
|
3974
|
+
stdout: string;
|
|
3975
|
+
stderr: string;
|
|
3976
|
+
durationMs: number;
|
|
3977
|
+
results: CodeResultPart[];
|
|
3978
|
+
error?: {
|
|
3979
|
+
name: string;
|
|
3980
|
+
message: string;
|
|
3981
|
+
traceback?: string;
|
|
3982
|
+
};
|
|
3983
|
+
}
|
|
3984
|
+
/** Options for `box.runCode()`. */
|
|
3985
|
+
interface CodeExecutionOptions {
|
|
3986
|
+
/** Session scope: kernels persist variables across calls with the same id. */
|
|
3987
|
+
sessionId?: string;
|
|
3988
|
+
/** Per-call timeout in ms. 0 disables. Default 60_000. */
|
|
3989
|
+
timeoutMs?: number;
|
|
3990
|
+
/** Extra env vars merged in for this call only. */
|
|
3991
|
+
env?: Record<string, string>;
|
|
3992
|
+
/** Working directory override (honored on kernel creation only). */
|
|
3993
|
+
cwd?: string;
|
|
3994
|
+
/**
|
|
3995
|
+
* Caller-supplied dedup key. Two `runCode` calls with the same key and
|
|
3996
|
+
* the same `sessionId` within a 15-minute window return the same result
|
|
3997
|
+
* without re-executing — including the case where the second call arrives
|
|
3998
|
+
* while the first is still running (it awaits the in-flight result).
|
|
3999
|
+
*
|
|
4000
|
+
* Scoped per `sessionId` so two sessions reusing the same key stay
|
|
4001
|
+
* isolated. A failed execution is not cached; a retry with the same key
|
|
4002
|
+
* gets a fresh attempt.
|
|
4003
|
+
*
|
|
4004
|
+
* For exactly-once across an outer agent loop (multi-turn tool use), pair
|
|
4005
|
+
* with `box.dispatchPrompt({ sessionId, turnId })` — the agent layer
|
|
4006
|
+
* dedups the whole loop, this one dedups a single code-exec call.
|
|
4007
|
+
*/
|
|
4008
|
+
idempotencyKey?: string;
|
|
4009
|
+
}
|
|
4010
|
+
//#endregion
|
|
4011
|
+
//#region src/mcp.d.ts
|
|
4012
|
+
/**
|
|
4013
|
+
* MCP (Model Context Protocol) helpers for sandbox capabilities.
|
|
4014
|
+
*
|
|
4015
|
+
* The sandbox exposes capabilities (currently `computer_use`, more
|
|
4016
|
+
* later) as MCP tools over Streamable HTTP. Any MCP-capable client —
|
|
4017
|
+
* Claude Desktop, Cursor, claude-code, codex, opencode, raw
|
|
4018
|
+
* `@modelcontextprotocol/sdk` apps — can consume this surface by
|
|
4019
|
+
* pasting the JSON returned from `Sandbox#getMcpEndpoint()` (or
|
|
4020
|
+
* `buildSandboxMcpConfig` if you already have the URL + token) into
|
|
4021
|
+
* the client's MCP config.
|
|
4022
|
+
*
|
|
4023
|
+
* Security model:
|
|
4024
|
+
* - Tokens are capability-scoped JWTs (claim `cap: ["computer_use"]`).
|
|
4025
|
+
* - Full sandbox runtime tokens are rejected on `/mcp`; only
|
|
4026
|
+
* capability-scoped tokens work there.
|
|
4027
|
+
* - A scoped token cannot pivot to admin endpoints (`/exec`, `/files`,
|
|
4028
|
+
* etc.) — those routes reject scoped tokens.
|
|
4029
|
+
* - Tokens are short-lived. Rotate via `Sandbox#getMcpEndpoint()`,
|
|
4030
|
+
* which mints a fresh token each call.
|
|
4031
|
+
*/
|
|
4032
|
+
/** Default name of the MCP server entry — surfaces in the host UI. */
|
|
4033
|
+
declare const SANDBOX_MCP_SERVER_NAME = "tangle-sandbox";
|
|
4034
|
+
/**
|
|
4035
|
+
* MCP HTTP server entry — matches the Anthropic MCP HTTP transport
|
|
4036
|
+
* schema (`type: "http"`, `url`, optional `headers`). Compatible with
|
|
4037
|
+
* every MCP host that implements the spec.
|
|
4038
|
+
*/
|
|
4039
|
+
interface SandboxMcpServerEntry {
|
|
4040
|
+
type: "http";
|
|
4041
|
+
url: string;
|
|
4042
|
+
headers: Record<string, string>;
|
|
4043
|
+
}
|
|
4044
|
+
/**
|
|
4045
|
+
* `.mcp.json`-shaped config any MCP host accepts. Drop the contents of
|
|
4046
|
+
* `mcpServers` into your host's `mcpServers` block (Claude Desktop,
|
|
4047
|
+
* Cursor, claude-code's `--mcp-config`, etc.) — no host-specific
|
|
4048
|
+
* fields, no provider lock-in.
|
|
4049
|
+
*/
|
|
4050
|
+
interface SandboxMcpConfig {
|
|
4051
|
+
mcpServers: Record<string, SandboxMcpServerEntry>;
|
|
4052
|
+
}
|
|
4053
|
+
/**
|
|
4054
|
+
* Endpoint payload returned by `GET /v1/sandboxes/:id/mcp`. Includes
|
|
4055
|
+
* the canonical config plus token expiry so callers can plan
|
|
4056
|
+
* refreshes.
|
|
4057
|
+
*/
|
|
4058
|
+
interface SandboxMcpEndpoint {
|
|
4059
|
+
/** MCP host config — paste this into Cursor/Claude Desktop/etc. */
|
|
4060
|
+
config: SandboxMcpConfig;
|
|
4061
|
+
/** Server entry name used inside `config.mcpServers`. */
|
|
4062
|
+
serverName: string;
|
|
4063
|
+
/** Reachable URL for the MCP HTTP transport. */
|
|
4064
|
+
url: string;
|
|
4065
|
+
/** Bearer token sent by the MCP host on every request. */
|
|
4066
|
+
authToken: string;
|
|
4067
|
+
/** ISO-8601 expiry — the host should refresh before this. */
|
|
4068
|
+
expiresAt: string;
|
|
4069
|
+
/** Capabilities the token is scoped to. */
|
|
4070
|
+
capabilities: ReadonlyArray<"computer_use">;
|
|
4071
|
+
}
|
|
4072
|
+
interface BuildSandboxMcpConfigOptions {
|
|
4073
|
+
/** Public sandbox URL where `/mcp` is reachable. No trailing slash. */
|
|
4074
|
+
sandboxUrl: string;
|
|
4075
|
+
/** Capability-scoped JWT minted by the Sandbox API. */
|
|
4076
|
+
authToken: string;
|
|
4077
|
+
/** Override the entry name. Defaults to SANDBOX_MCP_SERVER_NAME. */
|
|
4078
|
+
serverName?: string;
|
|
4079
|
+
}
|
|
4080
|
+
/**
|
|
4081
|
+
* Build the canonical `mcpServers` config for a sandbox MCP endpoint.
|
|
4082
|
+
* Pure function — no I/O, no crypto. Use this when you already have a
|
|
4083
|
+
* `{ url, authToken }` pair from the API and just want the JSON shape
|
|
4084
|
+
* to paste into a host. Most callers should use
|
|
4085
|
+
* `Sandbox#getMcpEndpoint()` instead, which fetches a freshly-minted
|
|
4086
|
+
* token from the API.
|
|
4087
|
+
*/
|
|
4088
|
+
declare function buildSandboxMcpConfig(options: BuildSandboxMcpConfigOptions): {
|
|
4089
|
+
serverName: string;
|
|
4090
|
+
config: SandboxMcpConfig;
|
|
4091
|
+
};
|
|
3941
4092
|
//#endregion
|
|
3942
4093
|
//#region src/session.d.ts
|
|
3943
4094
|
/**
|
|
@@ -4235,6 +4386,34 @@ declare class SandboxInstance {
|
|
|
4235
4386
|
* Execute a command in the sandbox.
|
|
4236
4387
|
*/
|
|
4237
4388
|
exec(command: string, options?: ExecOptions): Promise<ExecResult>;
|
|
4389
|
+
/**
|
|
4390
|
+
* Run code in a persistent language kernel.
|
|
4391
|
+
*
|
|
4392
|
+
* Each `(sessionId, language)` pair gets its own long-lived kernel that
|
|
4393
|
+
* keeps variable state across calls — like Jupyter cells. Without a
|
|
4394
|
+
* `sessionId`, calls share a process-wide kernel per language.
|
|
4395
|
+
*
|
|
4396
|
+
* Returns typed results: stdout/stderr text plus a `results` array of
|
|
4397
|
+
* structured outputs (matplotlib images as base64 PNG, pandas DataFrames,
|
|
4398
|
+
* explicit `display(value)` calls as JSON/HTML, errors with traceback).
|
|
4399
|
+
*
|
|
4400
|
+
* @example Persistent Python session
|
|
4401
|
+
* ```ts
|
|
4402
|
+
* await box.runCode("python", "import pandas as pd; df = pd.DataFrame({'x': range(5)})", { sessionId: "s1" });
|
|
4403
|
+
* const r = await box.runCode("python", "df.describe()", { sessionId: "s1" });
|
|
4404
|
+
* // r.results[0] is a `dataframe` part with columns + rows from the describe()
|
|
4405
|
+
* ```
|
|
4406
|
+
*
|
|
4407
|
+
* @example Matplotlib chart
|
|
4408
|
+
* ```ts
|
|
4409
|
+
* const r = await box.runCode("python",
|
|
4410
|
+
* "import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.show()",
|
|
4411
|
+
* { sessionId: "s1" });
|
|
4412
|
+
* const png = r.results.find(p => p.type === "image");
|
|
4413
|
+
* // png.data is a base64 PNG ready to render or hand back to an LLM
|
|
4414
|
+
* ```
|
|
4415
|
+
*/
|
|
4416
|
+
runCode(language: CodeLanguage, source: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
|
|
4238
4417
|
/**
|
|
4239
4418
|
* Read a file from the sandbox.
|
|
4240
4419
|
*
|
|
@@ -4921,6 +5100,34 @@ declare class SandboxInstance {
|
|
|
4921
5100
|
* construction.
|
|
4922
5101
|
*/
|
|
4923
5102
|
dispatchPrompt(message: string | PromptInputPart[], opts?: DispatchPromptOptions): Promise<DispatchedSession>;
|
|
5103
|
+
/**
|
|
5104
|
+
* List messages for a session, including in-flight assistant content
|
|
5105
|
+
* the agent is still streaming. Each entry's `metadata` carries the
|
|
5106
|
+
* durability marker — `status: "streaming" | "completed" | "interrupted"`,
|
|
5107
|
+
* `completed/interrupted` booleans, and the caller-supplied `turnId`
|
|
5108
|
+
* when one was set. See `SessionMessage` for the full contract.
|
|
5109
|
+
*
|
|
5110
|
+
* Polling this is the right way to detect "did the sidecar die mid-
|
|
5111
|
+
* turn?" — a SIGKILL leaves the assistant message with `status:
|
|
5112
|
+
* "streaming"` and no `completed`/`interrupted` marker; a graceful
|
|
5113
|
+
* abort stamps `interrupted: true` explicitly.
|
|
5114
|
+
*/
|
|
5115
|
+
messages(opts: ListMessagesOptions): Promise<SessionMessage[]>;
|
|
5116
|
+
/**
|
|
5117
|
+
* Look up a cached turn result by idempotency key. Returns the cached
|
|
5118
|
+
* payload if a turn with this `turnId` previously completed on the
|
|
5119
|
+
* given session; returns `null` if no such turn has finished yet
|
|
5120
|
+
* (either it never started, or it interrupted before completion).
|
|
5121
|
+
*
|
|
5122
|
+
* Call this before re-issuing a `streamPrompt` / `prompt` / `task`
|
|
5123
|
+
* that you might be retrying — a non-null result means the original
|
|
5124
|
+
* attempt finished and you can return that to your caller instead of
|
|
5125
|
+
* running the agent a second time. Only turns that reach the
|
|
5126
|
+
* `completed` terminal state are cached; interrupted turns are not.
|
|
5127
|
+
*/
|
|
5128
|
+
findCompletedTurn(turnId: string, opts: {
|
|
5129
|
+
sessionId: string;
|
|
5130
|
+
}): Promise<CompletedTurnResult | null>;
|
|
4924
5131
|
/**
|
|
4925
5132
|
* Mint a scoped, time-bounded JWT for direct browser access to this
|
|
4926
5133
|
* sandbox (Issue #913 Gap 1). Authority is the caller's
|
|
@@ -4943,4 +5150,4 @@ declare class SandboxInstance {
|
|
|
4943
5150
|
_sessionCancel(id: string): Promise<void>;
|
|
4944
5151
|
}
|
|
4945
5152
|
//#endregion
|
|
4946
|
-
export {
|
|
5153
|
+
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 };
|