@tangle-network/sandbox 0.0.0-develop.20260519182220.e7047bf → 0.0.0-develop.20260530132002.87cf9f6

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