@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.
@@ -1,2 +1 @@
1
- import { TangleIntegrationsClient, createTangleIntegrationsClient, parseIntegrationBridgeEnvironment, redactIntegrationBridgePayload } from "@tangle-network/agent-integrations";
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 orchestrator
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 { FleetExecDispatchOptions as $, SnapshotInfo as $n, RunCodeOptions as $t, CreateIntelligenceReportOptions as A, SandboxFleetWorkspaceReconcileResult as An, AgentProfileValidationResult as Ar, PreviewLinkManager as At, DownloadProgress as B, SandboxTraceExport as Bn, SandboxMcpServerEntry as Br, PromptResult as Bt, BatchResult as C, SandboxFleetToken as Cn, AgentProfileMcpServer as Cr, MintScopedTokenOptions as Ct, CheckpointOptions as D, SandboxFleetTraceOptions as Dn, AgentProfileResourceRef as Dr, PermissionLevel as Dt, CheckpointInfo as E, SandboxFleetTraceExport as En, AgentProfilePrompt as Er, NetworkManager as Et, DeleteOptions as F, SandboxPermissionsConfig as Fn, mergeAgentProfiles as Fr, ProcessSignal as Ft, ExecOptions as G, SearchMatch as Gn, PublicTemplateInfo as Gt, DriverInfo as H, SandboxUser as Hn, ProvisionResult as Ht, DirectoryPermission as I, SandboxResources as In, BuildSandboxMcpConfigOptions as Ir, ProcessSpawnOptions as It, FileSystem as J, SecretsManager as Jn, PublishPublicTemplateVersionOptions as Jt, ExecResult as K, SearchOptions as Kn, PublicTemplateVersionInfo as Kt, DispatchPromptOptions as L, SandboxStatus as Ln, SANDBOX_MCP_SERVER_NAME as Lr, ProcessStatus as Lt, CreateSandboxFleetTokenOptions as M, SandboxFleetWorkspaceSnapshotResult as Mn, defineAgentProfile as Mr, ProcessInfo as Mt, CreateSandboxFleetWithCoordinatorOptions as N, SandboxInfo as Nn, defineGitHubResource as Nr, ProcessLogEntry as Nt, CheckpointResult as O, SandboxFleetUsage as On, AgentProfileResources as Or, PermissionsManager as Ot, CreateSandboxOptions as P, SandboxIntelligenceEnvelope as Pn, defineInlineResource as Pr, ProcessManager as Pt, FleetDispatchStreamOptions as Q, SessionStatus as Qn, ReconcileSandboxFleetsResult as Qt, DispatchedSession as R, SandboxTraceBundle as Rn, SandboxMcpConfig as Rr, PromptInputPart as Rt, BatchOptions as S, SandboxFleetPolicy as Sn, AgentProfileFileMount as Sr, McpServerConfig as St, BatchTaskResult as T, SandboxFleetTraceEvent as Tn, AgentProfilePermissionValue as Tr, NetworkConfig as Tt, DriverType as U, ScopedToken as Un, ProvisionStatus as Ut, DriverConfig as V, SandboxTraceOptions as Vn, buildSandboxMcpConfig as Vr, ProvisionEvent as Vt, EventStreamOptions as W, ScopedTokenScope as Wn, ProvisionStep as Wt, FleetDispatchResultBuffer as X, SessionInfo as Xn, ReapExpiredSandboxFleetsResult as Xt, FleetDispatchCancelResult as Y, SessionEventStreamOptions as Yn, ReapExpiredSandboxFleetsOptions as Yt, FleetDispatchResultBufferOptions as Z, SessionListOptions as Zn, ReconcileSandboxFleetsOptions as Zt, BackendInfo as _, SandboxFleetMachineRecord as _n, UsageInfo as _r, IntelligenceReportSubjectType as _t, TraceExportSink as a, SandboxEvent as an, TaskOptions as ar, ForkResult as at, BackendType as b, SandboxFleetManifestMachine as bn, AgentProfileCapabilities as br, ListSandboxFleetOptions as bt, otelTraceIdForTangleTrace as c, SandboxFleetCostEstimate as cn, TeeAttestationReport as cr, GitCommit as ct, AcceleratorKind as d, SandboxFleetDriverCapability as dn, TeePublicKeyResponse as dr, GitStatus as dt, SSHCommandDescriptor as en, SnapshotOptions as er, FleetExecDispatchResult as et, AccessPolicyRule as f, SandboxFleetDriverTimings as fn, TokenRefreshHandler as fr, GpuType as ft, BackendConfig as g, SandboxFleetMachineMeteredUsage as gn, UploadProgress as gr, IntelligenceReportCompareTo as gt, BackendCapabilities as h, SandboxFleetMachine as hn, UploadOptions as hr, IntelligenceReportBudget as ht, TraceExportResult as i, SandboxEnvironment as in, SubscriptionInfo as ir, ForkOptions as it, CreateSandboxFleetOptions as j, SandboxFleetWorkspaceRestoreResult as jn, AgentSubagentProfile as jr, Process as jt, CodeResult as k, SandboxFleetWorkspace as kn, AgentProfileValidationIssue as kr, PreviewLinkInfo as kt, toOtelJson as l, SandboxFleetDispatchFailureClass as ln, TeeAttestationResponse as lr, GitConfig as lt, AttachSandboxFleetMachineOptions as m, SandboxFleetIntelligenceEnvelope as mn, UpdateUserOptions as mr, IntelligenceReport as mt, SandboxInstance as n, SandboxClientConfig as nn, SshKeysManager as nr, FleetPromptDispatchOptions as nt, buildTraceExportPayload as o, SandboxFleetArtifact as on, TaskResult as or, GitAuth as ot, AddUserOptions as p, SandboxFleetInfo as pn, ToolsConfig as pr, InstalledTool as pt, FileInfo as q, SecretInfo as qn, PublishPublicTemplateOptions as qt, TraceExportFormat as r, SandboxConnection as rn, StorageConfig as rr, FleetPromptDispatchResult as rt, exportTraceBundle as s, SandboxFleetArtifactSpec as sn, TeeAttestationOptions as sr, GitBranch as st, HttpClient as t, SSHCredentials as tn, SnapshotResult as tr, FleetMachineId as tt, SandboxSession as u, SandboxFleetDispatchResponse as un, TeePublicKey as ur, GitDiff as ut, BackendManager as v, SandboxFleetMachineSpec as vn, WaitForOptions as vr, IntelligenceReportWindow as vt, BatchTask as w, SandboxFleetTraceBundle as wn, AgentProfileModelHints as wr, MkdirOptions as wt, BatchEvent as x, SandboxFleetOperationsSummary as xn, AgentProfileConfidential as xr, ListSandboxOptions as xt, BackendStatus as y, SandboxFleetManifest as yn, AgentProfile as yr, ListOptions as yt, DownloadOptions as z, SandboxTraceEvent as zn, SandboxMcpEndpoint as zr, PromptOptions as zt };
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 };