@tangle-network/sandbox 0.2.1 → 0.4.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/LICENSE +11 -0
- package/README.md +71 -0
- 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 -271
- package/dist/client-CygjzF3v.js +1 -0
- package/dist/{errors-BI75IXOM.d.ts → client-DM2pIli7.d.ts} +2 -129
- 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-CTj81tF9.d.ts} +1 -1
- package/dist/index.d.ts +256 -7
- package/dist/index.js +1 -825
- package/dist/openai/index.d.ts +21 -6
- package/dist/openai/index.js +1 -1721
- package/dist/{sandbox-aBpWqler.d.ts → sandbox-CBmfYqMQ.d.ts} +291 -117
- 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 +50 -78
- package/dist/client-Uve6A5C6.js +0 -2280
- package/dist/platform-integrations.d.ts +0 -2
- package/dist/platform-integrations.js +0 -2
- 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,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.
|
|
@@ -1334,7 +1219,7 @@ interface PromptOptions {
|
|
|
1334
1219
|
signal?: AbortSignal;
|
|
1335
1220
|
/**
|
|
1336
1221
|
* Stable execution id for cross-process reconnect. When passed, the same
|
|
1337
|
-
* id on a retry lands on the same substrate execution — the
|
|
1222
|
+
* id on a retry lands on the same substrate execution — the platform
|
|
1338
1223
|
* replays its buffered event stream instead of spawning a duplicate run.
|
|
1339
1224
|
* Forwarded as the `X-Execution-ID` header. Omit to let the SDK extract
|
|
1340
1225
|
* one from the response stream's `execution.started` event (in-call
|
|
@@ -1347,6 +1232,16 @@ interface PromptOptions {
|
|
|
1347
1232
|
* `Last-Event-ID` header. Omit on first attempt.
|
|
1348
1233
|
*/
|
|
1349
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;
|
|
1350
1245
|
}
|
|
1351
1246
|
/**
|
|
1352
1247
|
* SSE event from sandbox streaming.
|
|
@@ -1762,6 +1657,67 @@ interface DispatchPromptOptions extends PromptOptions {
|
|
|
1762
1657
|
* by construction. */
|
|
1763
1658
|
sessionId?: string;
|
|
1764
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
|
+
}
|
|
1765
1721
|
/**
|
|
1766
1722
|
* Returned by `box.dispatchPrompt()` — minimum the caller needs to track
|
|
1767
1723
|
* the session afterward. The sandbox keeps running the prompt; use
|
|
@@ -3938,6 +3894,168 @@ interface FileSystem {
|
|
|
3938
3894
|
*/
|
|
3939
3895
|
exists(path: string): Promise<boolean>;
|
|
3940
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
|
+
};
|
|
3941
4059
|
//#endregion
|
|
3942
4060
|
//#region src/session.d.ts
|
|
3943
4061
|
/**
|
|
@@ -4235,6 +4353,34 @@ declare class SandboxInstance {
|
|
|
4235
4353
|
* Execute a command in the sandbox.
|
|
4236
4354
|
*/
|
|
4237
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>;
|
|
4238
4384
|
/**
|
|
4239
4385
|
* Read a file from the sandbox.
|
|
4240
4386
|
*
|
|
@@ -4921,6 +5067,34 @@ declare class SandboxInstance {
|
|
|
4921
5067
|
* construction.
|
|
4922
5068
|
*/
|
|
4923
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>;
|
|
4924
5098
|
/**
|
|
4925
5099
|
* Mint a scoped, time-bounded JWT for direct browser access to this
|
|
4926
5100
|
* sandbox (Issue #913 Gap 1). Authority is the caller's
|
|
@@ -4943,4 +5117,4 @@ declare class SandboxInstance {
|
|
|
4943
5117
|
_sessionCancel(id: string): Promise<void>;
|
|
4944
5118
|
}
|
|
4945
5119
|
//#endregion
|
|
4946
|
-
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 };
|