@tangle-network/agent-app 0.60.227 → 0.60.229

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.
Files changed (46) hide show
  1. package/dist/chat-routes/index.js +1 -1
  2. package/dist/{chunk-YS2RYZQG.js → chunk-JILHXHJE.js} +789 -745
  3. package/dist/chunk-JILHXHJE.js.map +1 -0
  4. package/dist/chunk-NMZUW6VJ.js +29 -0
  5. package/dist/chunk-NMZUW6VJ.js.map +1 -0
  6. package/dist/design-canvas/index.js +42 -32
  7. package/dist/design-canvas/index.js.map +1 -1
  8. package/dist/design-canvas/mcp-context.d.ts +51 -0
  9. package/dist/design-canvas/mcp-elements-tools.d.ts +3 -0
  10. package/dist/design-canvas/mcp-input.d.ts +35 -0
  11. package/dist/design-canvas/mcp-pages-tools.d.ts +3 -0
  12. package/dist/design-canvas/mcp-read-tools.d.ts +3 -0
  13. package/dist/design-canvas/mcp-templates-tools.d.ts +3 -0
  14. package/dist/design-canvas/mcp-tools.d.ts +3 -9
  15. package/dist/public-consultation/index.d.ts +2 -2
  16. package/dist/sandbox/access.d.ts +46 -0
  17. package/dist/sandbox/app-tools.d.ts +129 -0
  18. package/dist/sandbox/box-health.d.ts +8 -0
  19. package/dist/sandbox/configuration.d.ts +280 -0
  20. package/dist/sandbox/credentials.d.ts +55 -0
  21. package/dist/sandbox/exec-failure.d.ts +9 -0
  22. package/dist/sandbox/existing-box.d.ts +43 -0
  23. package/dist/sandbox/index.d.ts +32 -950
  24. package/dist/sandbox/index.js +1 -1
  25. package/dist/sandbox/lifecycle-errors.d.ts +51 -0
  26. package/dist/sandbox/payload-limits.d.ts +55 -0
  27. package/dist/sandbox/product-egress.d.ts +4 -0
  28. package/dist/sandbox/profile-corpus.d.ts +16 -0
  29. package/dist/sandbox/profile-files.d.ts +16 -0
  30. package/dist/sandbox/prompt-dispatch.d.ts +14 -0
  31. package/dist/sandbox/prompt-events.d.ts +71 -0
  32. package/dist/sandbox/prompt-options.d.ts +79 -0
  33. package/dist/sandbox/prompt-profile.d.ts +61 -0
  34. package/dist/sandbox/prompt-result.d.ts +57 -0
  35. package/dist/sandbox/runtime-cache.d.ts +43 -0
  36. package/dist/sandbox/runtime-connection.d.ts +9 -0
  37. package/dist/sandbox/shell-path.d.ts +2 -0
  38. package/dist/sandbox/workspace-boxes.d.ts +76 -0
  39. package/dist/sandbox/workspace-claim.d.ts +13 -0
  40. package/dist/sandbox/workspace-provision.d.ts +9 -0
  41. package/dist/sequences/index.js +6 -20
  42. package/dist/sequences/index.js.map +1 -1
  43. package/dist/sequences/mcp-tools.d.ts +0 -18
  44. package/dist/tools/mcp-arguments.d.ts +4 -0
  45. package/package.json +1 -1
  46. package/dist/chunk-YS2RYZQG.js.map +0 -1
@@ -0,0 +1,46 @@
1
+ import type { SandboxInstance, ScopedTokenScope, MintScopedTokenOptions } from '@tangle-network/sandbox';
2
+ import { type Outcome } from './outcome';
3
+ import type { SandboxRuntimeConfig } from './configuration';
4
+ /** Define permission levels for sandbox access and control */
5
+ export type SandboxPermissionLevel = 'owner' | 'admin' | 'developer' | 'viewer';
6
+ /** Map workspace roles to corresponding sandbox permission levels */
7
+ export interface MemberSyncSeam {
8
+ roleToSandboxRole: (workspaceRole: string) => SandboxPermissionLevel;
9
+ }
10
+ /** Resolve adding a user with a specific role to a sandbox and return the operation outcome */
11
+ export declare function syncSandboxMemberAdd(box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string): Promise<Outcome<void>>;
12
+ /** Remove a member from the sandbox while preserving their home directory and handle the outcome */
13
+ export declare function syncSandboxMemberRemove(box: SandboxInstance, userId: string): Promise<Outcome<void>>;
14
+ /** Synchronize a sandbox member's role by updating permissions based on the provided role mapping */
15
+ export declare function syncSandboxMemberRole(box: SandboxInstance, seam: MemberSyncSeam, userId: string, role: string): Promise<Outcome<void>>;
16
+ /**
17
+ * Write-only secret port: create, replace, and delete a secret by name.
18
+ *
19
+ * There is no read method. The platform's secrets API returns names and
20
+ * timestamps only — a stored value is never served back, it is injected into
21
+ * the sandbox as an environment variable. A `get` here could only ever return
22
+ * a value this process already held, so the port does not offer one.
23
+ */
24
+ export interface SecretStore {
25
+ create: (name: string, value: string) => Promise<void>;
26
+ update: (name: string, value: string) => Promise<void>;
27
+ delete: (name: string) => Promise<void>;
28
+ }
29
+ /** Resolve a SecretStore interface using the provided SandboxRuntimeConfig shell */
30
+ export declare function secretStoreFromClient(shell: SandboxRuntimeConfig): SecretStore;
31
+ /** Resolve storing a secret by creating it, or replacing it when it exists */
32
+ export declare function storeSecret(store: SecretStore, name: string, value: string): Promise<Outcome<void>>;
33
+ /** Delete a secret by name from the given secret store and return the operation outcome */
34
+ export declare function deleteSecret(store: SecretStore, name: string): Promise<Outcome<void>>;
35
+ /** Represent a token with its expiration date and associated scope */
36
+ export interface ScopedTokenResult {
37
+ token: string;
38
+ expiresAt: Date;
39
+ scope: ScopedTokenScope;
40
+ }
41
+ /**
42
+ * Mint a scoped token for an already-provisioned box (e.g. to hand a terminal
43
+ * proxy a narrowed credential). Uses the SDK's native `box.mintScopedToken`,
44
+ * which normalizes `expiresAt` to a Date — no hand-rolled wire call.
45
+ */
46
+ export declare function mintSandboxScopedToken(box: SandboxInstance, options: MintScopedTokenOptions): Promise<Outcome<ScopedTokenResult>>;
@@ -0,0 +1,129 @@
1
+ import { type AppToolName, type AppToolContext, type ToolHeaderNames } from '../tools/index';
2
+ import type { AgentProfileMcpServer, AgentProfileFileMount } from '@tangle-network/agent-interface';
3
+ import type { SandboxInstance } from '@tangle-network/sandbox';
4
+ import { type Outcome } from './outcome';
5
+ /** Describe an application tool with its name, unique key, and description */
6
+ export interface AppToolDescriptor {
7
+ tool: AppToolName;
8
+ key: string;
9
+ description: string;
10
+ }
11
+ /** Define options for building MCP server configurations in the app tool environment */
12
+ export interface BuildAppToolMcpServersOptions {
13
+ tools: AppToolDescriptor[];
14
+ baseUrl: string;
15
+ /**
16
+ * NAME of the box-environment variable holding the capability token — never
17
+ * the token itself. Every emitted `Authorization` header is a `secret-ref` to
18
+ * this key, which the sandbox resolves privately; see
19
+ * `BuildHttpMcpServerOptions.tokenEnvKey` in `../tools/mcp`.
20
+ *
21
+ * The key must name a variable the box carries — placed by
22
+ * {@link SandboxRuntimeConfig.env} at creation, refreshed by
23
+ * {@link SandboxRuntimeConfig.runtimeEnv} before retained-box bootstrap, or
24
+ * injected from the platform secret store via
25
+ * {@link SandboxRuntimeConfig.secrets}.
26
+ */
27
+ tokenEnvKey: string;
28
+ ctx: AppToolContext;
29
+ headerNames?: ToolHeaderNames;
30
+ }
31
+ /** Build a mapping of MCP server profiles keyed by tool identifiers from provided options */
32
+ export declare function buildAppToolMcpServers(options: BuildAppToolMcpServersOptions): Record<string, AgentProfileMcpServer>;
33
+ /** Define the specification for a sandbox tool including its name, content, and optional executability */
34
+ export interface SandboxToolSpec {
35
+ name: string;
36
+ content: string;
37
+ executable?: boolean;
38
+ }
39
+ /** Define options for resolving sandbox tool paths including appName, baseDir, and binDir */
40
+ export interface SandboxToolPathOptions {
41
+ appName: string;
42
+ baseDir?: string;
43
+ binDir?: string;
44
+ }
45
+ /** Define options for building sandbox tool file mounts including tool specifications and paths */
46
+ export interface BuildSandboxToolFileMountsOptions extends SandboxToolPathOptions {
47
+ tools: readonly SandboxToolSpec[];
48
+ }
49
+ /** Resolve the root directory path for a sandbox tool based on provided options */
50
+ export declare function sandboxToolRootDir(options: SandboxToolPathOptions): string;
51
+ /** Resolve the binary directory path for a sandbox tool based on provided options */
52
+ export declare function sandboxToolBinDir(options: SandboxToolPathOptions): string;
53
+ /** Resolve the file system path to a specified sandbox tool based on given options */
54
+ export declare function sandboxToolPath(options: SandboxToolPathOptions & {
55
+ toolName: string;
56
+ }): string;
57
+ /** Build file mounts for sandbox tools based on provided options and tool configurations */
58
+ export declare function buildSandboxToolFileMounts(options: BuildSandboxToolFileMountsOptions): AgentProfileFileMount[];
59
+ /**
60
+ * Build the `SANDBOX_TOOL_BIN_DIRS` entry that puts these apps' tool bin dirs on
61
+ * a sandbox PATH. Declare it in the same box env as the mounts from
62
+ * {@link buildSandboxToolFileMounts}: the mounts place the executables, this
63
+ * places the directory that makes a bare tool name resolve.
64
+ *
65
+ * Every sandbox PATH builder appends these directories at the TAIL, after the
66
+ * Nix, npm, and image entries, so a tool never shadows a platform or system
67
+ * binary of the same name. That placement is identical for a non-interactive
68
+ * exec, a sidecar-spawned CLI, and an SSH shell, which is why this variable and
69
+ * not a shell rc file is the mechanism: an exec reads no rc file, and the SSH
70
+ * shell environment assigns PATH absolutely.
71
+ *
72
+ * Entries come from {@link sandboxToolBinDir}, so the value can never name a
73
+ * directory the mounts did not use — a caller that hand-writes the literal
74
+ * instead drifts silently the moment a base dir changes. Order is preserved,
75
+ * and two apps that resolve to one directory collapse to the FIRST position it
76
+ * appeared in.
77
+ *
78
+ * A `:` in a resolved bin dir throws here. The character separates entries both
79
+ * in this variable and in PATH itself, so such a directory is unrepresentable
80
+ * rather than merely awkward: joining it would split one absolute path into a
81
+ * leading path and a relative remainder, and the runtime rejects a relative
82
+ * segment by failing the whole box. Throwing names the offending directory
83
+ * instead.
84
+ *
85
+ * The consuming half lives in agent-container: `resolveSandboxToolBinDirs`
86
+ * parses this value and every PATH builder appends it at the tail — sidecar
87
+ * exec and PTY through `packages/shared/src/cache-env.ts`, an SSH session
88
+ * through `packages/shared/src/ssh-bootstrap.ts`, and a spawned CLI through
89
+ * `packages/sdk-cli-runner/src/cli-process.ts`, each with its own tests. This
90
+ * package has no sandbox runtime, so tail placement is pinned there, not here.
91
+ */
92
+ export declare function buildSandboxToolBinDirsEnv(apps: readonly SandboxToolPathOptions[]): {
93
+ SANDBOX_TOOL_BIN_DIRS: string;
94
+ };
95
+ /**
96
+ * Build a shell script that creates the sandbox tool binary directory.
97
+ * {@link buildSandboxToolBinDirsEnv}, not this script, puts that directory on a
98
+ * sandbox PATH.
99
+ *
100
+ * The `mkdir -p` makes the directory exist before a tool mount lands in it.
101
+ */
102
+ export declare function buildSandboxToolBinDirScript(options: SandboxToolPathOptions): string;
103
+ /** Build a shell script that creates the sandbox tool binary directory.
104
+ *
105
+ * @deprecated Renamed to {@link buildSandboxToolBinDirScript}, and the script
106
+ * no longer appends the bin dir to PATH in `~/.profile`, `~/.bashrc` and
107
+ * `~/.zshrc`. Those edits never reached the contexts that run a tool: an exec
108
+ * and a spawned CLI read no rc file, and the SSH shell assigns PATH
109
+ * absolutely, which discards an appended entry. Put the directory on PATH with
110
+ * {@link buildSandboxToolBinDirsEnv} instead. This name forwards to the new
111
+ * one so an existing import keeps resolving; removal is a major.
112
+ */
113
+ export declare function buildSandboxToolPathSetupScript(options: SandboxToolPathOptions): string;
114
+ /**
115
+ * Create the sandbox tool binary directory in a running box.
116
+ * {@link buildSandboxToolBinDirsEnv}, not this call, puts it on a sandbox PATH.
117
+ */
118
+ export declare function ensureSandboxToolBinDir(box: SandboxInstance, options: SandboxToolPathOptions): Promise<Outcome<void>>;
119
+ /** Create the sandbox tool binary directory in a running box.
120
+ *
121
+ * @deprecated Renamed to {@link ensureSandboxToolBinDir}, and the call no
122
+ * longer appends the bin dir to PATH in `~/.profile`, `~/.bashrc` and
123
+ * `~/.zshrc`. Those edits never reached the contexts that run a tool: an exec
124
+ * and a spawned CLI read no rc file, and the SSH shell assigns PATH
125
+ * absolutely, which discards an appended entry. Put the directory on PATH with
126
+ * {@link buildSandboxToolBinDirsEnv} instead. This name forwards to the new
127
+ * one so an existing import keeps resolving; removal is a major.
128
+ */
129
+ export declare function runSandboxToolPathSetup(box: SandboxInstance, options: SandboxToolPathOptions): Promise<Outcome<void>>;
@@ -0,0 +1,8 @@
1
+ import type { SandboxInstance, ProvisionEvent } from '@tangle-network/sandbox';
2
+ import type { LivenessProbeConfig } from './configuration';
3
+ import { type Outcome } from './outcome';
4
+ import { Sandbox } from '@tangle-network/sandbox/core';
5
+ import { type SandboxExistingBoxStage } from './lifecycle-errors';
6
+ export declare function isReusableBox(box: SandboxInstance, probe: LivenessProbeConfig | undefined): Promise<Outcome<void>>;
7
+ export declare function resumeStoppedBox(box: SandboxInstance, timeoutMs: number, runtimeEnv: Record<string, string>, onProgress?: (event: ProvisionEvent) => void): Promise<Outcome<SandboxInstance>>;
8
+ export declare function recoverUnresponsiveBox(client: Sandbox, box: SandboxInstance, probe: LivenessProbeConfig | undefined, stage: SandboxExistingBoxStage, name: string, resumeTimeout: number, runtimeEnv: Record<string, string>, onProgress?: (event: ProvisionEvent) => void): Promise<SandboxInstance>;
@@ -0,0 +1,280 @@
1
+ import type { SandboxInstance, EgressPolicy, StorageConfig, ProvisionEvent } from '@tangle-network/sandbox';
2
+ import type { SandboxExistingBoxStage } from './lifecycle-errors';
3
+ import type { AgentProfileFileMount, AgentProfileMcpServer, AgentProfile } from '@tangle-network/agent-interface';
4
+ import type { Harness } from '../harness/index';
5
+ import type { SandboxClientCredentials } from './credentials';
6
+ import type { SandboxPermissionLevel } from './access';
7
+ import type { ProviderResolutionConfig } from './model';
8
+ import type { ReuseStateStore } from './reuse-state';
9
+ import type { Outcome } from './outcome';
10
+ import type { ComposeProfileBudget } from '../profile/budget';
11
+ import type { TurnTrace, TurnSpan } from '../turn-trace/recorder';
12
+ /**
13
+ * Configure sandbox resources and lifecycle limits.
14
+ * Set `advisory` for application defaults that the Sandbox API may clamp to account limits.
15
+ * Omit it when the requested allocation must be honored or rejected.
16
+ */
17
+ export interface SandboxResourceConfig {
18
+ image: string;
19
+ cpuCores: number;
20
+ memoryMB: number;
21
+ diskGB: number;
22
+ /** Let the Sandbox API clamp these resource defaults to the account's limits. */
23
+ advisory?: boolean;
24
+ maxLifetimeSeconds: number;
25
+ idleTimeoutSeconds: number;
26
+ }
27
+ /** Define the context for building a sandbox including workspace, integrations, and optional user ID */
28
+ export interface SandboxBuildContext {
29
+ workspaceId: string;
30
+ connectedIntegrationIds: string[];
31
+ userId?: string;
32
+ }
33
+ /** Define a scope containing workspace and optional user identifiers for sandbox environments */
34
+ export interface SandboxScope {
35
+ workspaceId: string;
36
+ userId?: string;
37
+ }
38
+ /** Define the specification for restoring a sandbox from a snapshot or another sandbox ID */
39
+ export interface SandboxRestoreSpec {
40
+ fromSnapshot: string;
41
+ fromSandboxId: string;
42
+ }
43
+ /** Describe the failure details when resuming a stopped sandbox instance */
44
+ export interface StoppedSandboxResumeFailure {
45
+ box: SandboxInstance;
46
+ error: Error;
47
+ scope: SandboxScope;
48
+ boxKey: string;
49
+ }
50
+ /** Describe a sandbox that disappeared after the platform listed it. */
51
+ export interface MissingSandboxFailure extends StoppedSandboxResumeFailure {
52
+ stage: SandboxExistingBoxStage;
53
+ }
54
+ /** Define the structure for resuming a stopped sandbox with replacement key and optional restore options */
55
+ export interface StoppedSandboxResumeRecovery {
56
+ replacementBoxKey: string;
57
+ restore?: SandboxRestoreSpec | null;
58
+ }
59
+ /** Configure runtime exec verification before reusing a sandbox. */
60
+ export interface LivenessProbeConfig {
61
+ /** Process timeout passed to the Sandbox SDK. Defaults to 5 seconds.
62
+ * SDK readiness and transport deadlines also apply. */
63
+ execTimeoutMs?: number;
64
+ /**
65
+ * Reuse a successful liveness result for this many milliseconds for the
66
+ * same box id and identity (start time and filesystem incarnation). Defaults to 10 minutes; set to 0 to probe on
67
+ * every reuse.
68
+ *
69
+ * Only the exec probe is cached. Runtime readiness, deferred-file
70
+ * materialization, and bootstrap still run on every reuse, and the egress
71
+ * policy and runtime environment are checked as {@link SandboxRuntimeConfig.egressPolicy}
72
+ * and {@link SandboxRuntimeConfig.runtimeEnv} describe. A box that dies during
73
+ * this window is surfaced by the first call on it: a caller whose first call
74
+ * fails passes the box to {@link dropTrustedBox} and ensures once more, which
75
+ * probes it and restarts it in place. The cache never triggers box deletion.
76
+ */
77
+ cacheTtlMs?: number;
78
+ }
79
+ /** Define options for composing a user profile including prompts, files, servers, and name */
80
+ export interface ProfileComposeOptions {
81
+ systemPrompt?: string;
82
+ extraFiles?: AgentProfileFileMount[];
83
+ extraMcp?: Record<string, AgentProfileMcpServer>;
84
+ name?: string;
85
+ /**
86
+ * The harness this profile is being composed for.
87
+ *
88
+ * Where a resource lands is harness-specific — skills resolve to
89
+ * `.opencode/skills/`, `.claude/skills/`, `.pi/skills/`, and so on
90
+ * (`skillDirForHarness`), and some harnesses take no cwd skills at all.
91
+ * Without this, an app composing a profile cannot place a harness-native
92
+ * resource and is pushed into hardcoding one harness's path, which then
93
+ * silently disagrees with the path its own prompt cites: the agent is told
94
+ * to read a directory nothing was written to and its skills are invisible.
95
+ * Prefer declaring `resources.skills` and letting the platform place them;
96
+ * use this when composing paths directly.
97
+ */
98
+ harness: Harness;
99
+ }
100
+ /** Define runtime configuration methods for sandbox environments including credentials, metadata, and permissions */
101
+ export interface SandboxRuntimeConfig {
102
+ credentials: (scope?: SandboxScope) => SandboxClientCredentials | null | Promise<SandboxClientCredentials | null>;
103
+ name: (workspaceId: string) => string;
104
+ metadata: (harness: Harness) => Record<string, unknown>;
105
+ connectedIntegrationIds: (workspaceId: string) => Promise<string[]>;
106
+ /**
107
+ * Creation-only environment. Use runtimeEnv for expiring app credentials.
108
+ * Values remain private; profiles reference their names through secret-ref.
109
+ * Workspace-wide values cannot carry per-user or per-resource authority.
110
+ */
111
+ env: (ctx: SandboxBuildContext) => Promise<Record<string, string>>;
112
+ /**
113
+ * Workspace app credentials resolved on creation and before every reuse,
114
+ * resume, or recovery. Fresh values override env in the creation payload.
115
+ * The SDK updates retained runtimes before bootstrap and refuses runtime-managed keys.
116
+ * A resume receives only the keys the platform names as required to rebuild a runtime.
117
+ * Throw when required credentials cannot be minted; renewal failure preserves
118
+ * the sandbox and prevents dispatch. Requires the matching Sandbox runtime.
119
+ * Values equal to the last ones delivered to the same box identity, within
120
+ * 10 minutes, are resolved again but not sent again.
121
+ */
122
+ runtimeEnv?: (scope: SandboxScope) => Promise<Record<string, string>>;
123
+ files: (ctx: SandboxBuildContext) => Promise<AgentProfileFileMount[]>;
124
+ secrets: (workspaceId: string) => Promise<string[]>;
125
+ profile: (options: ProfileComposeOptions) => AgentProfile;
126
+ permissionRole?: (workspaceRole: string) => SandboxPermissionLevel;
127
+ resources?: SandboxResourceConfig;
128
+ provider?: ProviderResolutionConfig;
129
+ /**
130
+ * Portable directory where the sandbox starts its agent processes.
131
+ *
132
+ * The value is relative to the sandbox workspace. The sandbox platform
133
+ * validates it and applies it when the box is created.
134
+ */
135
+ cwd?: string;
136
+ /**
137
+ * Product-declared outbound network policy. Applied when a sandbox is
138
+ * created. A reused or resumed sandbox is returned only when its explicit
139
+ * policy already matches; existing mismatches are rejected without updating
140
+ * or deleting the sandbox unless migration is explicitly enabled below.
141
+ * A match read within 10 minutes stands for the same box identity, except
142
+ * that a `strict` or `blocked` policy is read again whenever a reuse would send
143
+ * the box credentials (a changed {@link runtimeEnv}, or a {@link bootstrap}).
144
+ */
145
+ egressPolicy?: EgressPolicy;
146
+ /**
147
+ * Update an existing box to {@link egressPolicy} before reuse when its
148
+ * recorded policy is absent or different. This is an explicit fleet
149
+ * migration switch: the updated policy is read back and must match before
150
+ * the box is returned. It never deletes the box.
151
+ */
152
+ migrateEgressPolicy?: boolean;
153
+ /**
154
+ * Where Worker isolates share what a reuse last checked on a box (its id, the
155
+ * exec probe, the egress read, the runtime environment delivered). A request is
156
+ * not promised the isolate that served the last one, so without a shared store
157
+ * a reuse often finds nothing to trust. Default: the runtime's Cache API when
158
+ * it has one; `null` keeps the state in the isolate. Holds ids, times and
159
+ * digests only.
160
+ */
161
+ reuseState?: ReuseStateStore | null;
162
+ storage?: (ctx: SandboxBuildContext) => StorageConfig | undefined;
163
+ restore?: (ctx: SandboxBuildContext) => SandboxRestoreSpec | undefined | Promise<SandboxRestoreSpec | undefined>;
164
+ boxKey?: (scope: SandboxScope) => string;
165
+ childKeyMint?: (scope: SandboxScope) => Promise<Outcome<string>>;
166
+ bootstrap?: (box: SandboxInstance, scope: SandboxScope) => Promise<Outcome<void>>;
167
+ livenessProbe?: LivenessProbeConfig;
168
+ webTerminalEnabled?: boolean;
169
+ resumeStopped?: boolean;
170
+ /**
171
+ * How long to wait for a box to reach `running`, in ms. Default 120_000.
172
+ *
173
+ * Raise it when a cold create legitimately takes longer than that — a large
174
+ * vault restore, a heavy image, a loaded fleet. The failure it prevents is
175
+ * ugly: every attempt burns the full wait, times out, and the NEXT attempt
176
+ * starts the same slow create from scratch, so a workspace whose provision
177
+ * takes 130s never succeeds no matter how many times a user retries.
178
+ */
179
+ provisionTimeoutMs?: number;
180
+ replaceUnbringableBox?: boolean;
181
+ recoverStoppedSandbox?: (failure: StoppedSandboxResumeFailure) => Promise<Outcome<StoppedSandboxResumeRecovery | null>>;
182
+ /**
183
+ * Replace a sandbox resource or backing container that disappears after listing.
184
+ *
185
+ * The shell calls this for a sandbox resource 404 or an exact resume 500 that
186
+ * wraps a host-agent container 404. It excludes runtime 404 and unrelated
187
+ * reuse failures. Return a fresh key without deleting the stale sandbox record.
188
+ */
189
+ recoverMissingSandbox?: (failure: MissingSandboxFailure) => Promise<Outcome<StoppedSandboxResumeRecovery | null>>;
190
+ backendModelAtCreate?: boolean;
191
+ deferProfileFiles?: boolean;
192
+ promptBudget?: ComposeProfileBudget;
193
+ }
194
+ /** Define default resource limits and settings for sandbox environments */
195
+ export declare const DEFAULT_SANDBOX_RESOURCES: SandboxResourceConfig;
196
+ /** Define options for ensuring a workspace sandbox with provisioning and progress handling */
197
+ export interface EnsureWorkspaceSandboxOptions {
198
+ workspaceId: string;
199
+ userId?: string;
200
+ harness: Harness;
201
+ forceNew?: boolean;
202
+ onProgress?: (event: ProvisionEvent) => void;
203
+ billingOwnerId?: string;
204
+ spend?: SandboxSpendHooks;
205
+ /** Optional stage timing for the steps of an ensure (`sandbox.ensure.*`), so a
206
+ * product can see which round trip a slow acquisition spent its time in.
207
+ * Omitted, nothing is measured. */
208
+ measure?: <T>(stage: string, operation: () => Promise<T>) => Promise<T>;
209
+ /**
210
+ * The turn's trace. The ensure is recorded as one `sandbox.claim` span whose children are the
211
+ * `sandbox.ensure.*` steps (`credentials`, `get_running` or `list_running`, `finalize` for a reused box,
212
+ * with `egress` and `liveness` unless a recent check stood in for them; `list_stopped`,
213
+ * `resume` for a stopped one; `create`, `wait_running`, `bootstrap` for a new one), so a slow claim names
214
+ * the step it waited on. The spend seam's two calls are recorded beside the claim as
215
+ * `sandbox.spend.before_provision` and `sandbox.spend.observe`. Omitted, nothing is recorded;
216
+ * `measure` is unchanged and still called.
217
+ */
218
+ trace?: TurnTrace;
219
+ /** The span the claim hangs from. Default: the trace's root. */
220
+ traceParent?: TurnSpan;
221
+ }
222
+ /** What `/sandbox` reports once a box is provisioned, reused, or resumed. */
223
+ export interface SandboxProvisionedObservation {
224
+ readonly workspaceId: string;
225
+ readonly userId?: string;
226
+ /** The platform's sandbox id — the join key to every settlement row. */
227
+ readonly sandboxId: string;
228
+ /** The deterministic box key this workspace resolves to. */
229
+ readonly boxKey?: string | undefined;
230
+ /** The idle timeout this box was asked to run with, seconds. */
231
+ readonly idleTimeoutSeconds: number;
232
+ /** The max lifetime it was asked to run with, seconds, when one was asked for. */
233
+ readonly maxLifetimeSeconds?: number | undefined;
234
+ readonly at: number;
235
+ }
236
+ /**
237
+ * Optional spend-verification seam on `ensureWorkspaceSandbox`.
238
+ *
239
+ * The two halves have deliberately opposite failure contracts.
240
+ * `beforeProvision` is a GATE: it runs before anything is created and its throw
241
+ * propagates, because refusing to provision is the whole point of a budget cap.
242
+ * `onProvisioned` is an OBSERVER: its failures are swallowed, because
243
+ * bookkeeping must never take down the provisioning it is bookkeeping.
244
+ */
245
+ export interface SandboxSpendHooks {
246
+ /**
247
+ * Runs before any create, resume, restart or deletion of a box, and before a
248
+ * reuse unless this isolate probed that box recently (10 minutes by default,
249
+ * {@link LivenessProbeConfig.cacheTtlMs}): a reuse of a box it has been using
250
+ * is gated when its probe expires, not on every turn. Throw to refuse provisioning.
251
+ */
252
+ beforeProvision?(input: {
253
+ workspaceId: string;
254
+ userId?: string;
255
+ }): Promise<void> | void;
256
+ /**
257
+ * Runs after a box is available, except for a reuse that trusted a recent
258
+ * probe: the ensure that ran that probe reported the box, and `onActivity`
259
+ * carries its use since. Throwing here cannot fail the provision.
260
+ */
261
+ onProvisioned?(observation: SandboxProvisionedObservation): Promise<void> | void;
262
+ /**
263
+ * The box is doing work. Fired by the turn primitives at the start of a turn
264
+ * and again when it settles.
265
+ *
266
+ * Deliberately SYNCHRONOUS and unawaited — this sits on the turn path, and a
267
+ * store write must not add latency to it or hold a stream open. An
268
+ * implementation that persists should enqueue and return; errors are
269
+ * swallowed here as they are for `onProvisioned`.
270
+ *
271
+ * Wiring it is what keeps the expectation ceiling honest for long turns:
272
+ * without it, `lastActivityAt` only advances when a box is provisioned, so a
273
+ * three-hour turn leaves the ceiling three hours too tight and manufactures a
274
+ * discrepancy out of the product's own silence.
275
+ */
276
+ onActivity?(input: {
277
+ sandboxId: string;
278
+ at: number;
279
+ }): void;
280
+ }
@@ -0,0 +1,55 @@
1
+ import { type TangleExecutionEnvironment } from '../runtime/model';
2
+ /** Define client credentials for accessing the sandbox environment with API key and base URL */
3
+ export interface SandboxClientCredentials {
4
+ apiKey: string;
5
+ baseUrl: string;
6
+ }
7
+ /**
8
+ * Sandbox credential policy reuses the canonical execution-environment union
9
+ * (development/test/staging/production) so env classification stays in one place
10
+ * (see resolveTangleExecutionEnvironment in runtime/model).
11
+ */
12
+ export type SandboxCredentialEnvironment = TangleExecutionEnvironment;
13
+ /** Resolve options for obtaining sandbox client credentials from environment variables and classification */
14
+ export interface ResolveSandboxClientCredentialsOptions {
15
+ /**
16
+ * Environment object to read from. Defaults to process.env when available.
17
+ */
18
+ env?: Record<string, string | undefined>;
19
+ /**
20
+ * Explicit environment classification. Defaults to APP_ENV/NODE_ENV derived
21
+ * behavior: local/development/test use direct env credentials; staging/prod
22
+ * require the provision callback unless allowDirectEnvCredentials opts in.
23
+ */
24
+ environment?: SandboxCredentialEnvironment;
25
+ /**
26
+ * Env names that may carry a sandbox-compatible bearer. The first non-empty
27
+ * value wins when direct env credentials are allowed.
28
+ */
29
+ directKeyNames?: readonly string[];
30
+ /**
31
+ * Env names that may carry the sandbox gateway URL. The first non-empty value
32
+ * wins, then defaultBaseUrl.
33
+ */
34
+ baseUrlNames?: readonly string[];
35
+ /**
36
+ * Base URL used when none of baseUrlNames are present.
37
+ */
38
+ defaultBaseUrl?: string;
39
+ /**
40
+ * Whether direct env credentials are allowed for this environment. Defaults
41
+ * to true in development/test and false in staging/production.
42
+ */
43
+ allowDirectEnvCredentials?: boolean | ((environment: SandboxCredentialEnvironment) => boolean);
44
+ /**
45
+ * Product-owned provision path, usually minting a per-user sandbox key from a
46
+ * linked platform account. Called before direct env credentials in
47
+ * staging/production and after direct env credentials in development/test.
48
+ */
49
+ provision?: (context: {
50
+ environment: SandboxCredentialEnvironment;
51
+ env: Record<string, string | undefined>;
52
+ }) => SandboxClientCredentials | null | undefined | Promise<SandboxClientCredentials | null | undefined>;
53
+ }
54
+ /** Resolve sandbox client credentials based on environment and provided options asynchronously */
55
+ export declare function resolveSandboxClientCredentials(options?: ResolveSandboxClientCredentialsOptions): Promise<SandboxClientCredentials>;
@@ -0,0 +1,9 @@
1
+ export declare class ProfileWriteExecTimeoutError extends Error {
2
+ constructor(timeoutMs: number);
3
+ }
4
+ export declare function isRuntimeExecAuthError(err: unknown, seen?: Set<object>): boolean;
5
+ export declare function isRuntimeAuthRefreshDenied(err: unknown): boolean;
6
+ export declare function transientExecError(err: unknown): {
7
+ retryable: boolean;
8
+ retryAfterMs?: number;
9
+ };
@@ -0,0 +1,43 @@
1
+ import type { SandboxRuntimeConfig, SandboxScope } from './configuration';
2
+ import type { SandboxInstance } from '@tangle-network/sandbox';
3
+ import { type Outcome } from './outcome';
4
+ import { Sandbox } from '@tangle-network/sandbox/core';
5
+ import { type SandboxExistingBoxStage } from './lifecycle-errors';
6
+ import type { Harness } from '../harness/index';
7
+ export declare function resolveWorkspaceRuntimeEnv(shell: SandboxRuntimeConfig, scope: SandboxScope): Promise<Record<string, string>>;
8
+ type EgressRead = Awaited<ReturnType<SandboxInstance['egress']['get']>>;
9
+ /**
10
+ * Round trips of a reused box that do not depend on its liveness, started with
11
+ * the liveness probe so they overlap it. The egress read and the corpus marker
12
+ * are only reads: the policy is still asserted (and migrated) in finalize, and
13
+ * an unknown marker means the corpus is written as before. The runtime env is
14
+ * sent early only when the egress assertion cannot change where credentials
15
+ * may go (see {@link egressGatesCredentials}); otherwise it waits for it.
16
+ * A read or push this isolate completed within {@link TRUSTED_REUSE_TTL_MS} on
17
+ * the same box identity is not repeated, subject to the credential rule in
18
+ * {@link prefetchExistingBoxReads}.
19
+ */
20
+ interface ExistingBoxPrefetch {
21
+ egress?: Promise<Outcome<EgressRead>>;
22
+ /** The box's egress was verified recently enough that this reuse reads and asserts nothing. */
23
+ egressVerified?: boolean;
24
+ corpusMarker?: Promise<string | null>;
25
+ /** The renewal already sent to the box; finalize waits for it instead of sending another. */
26
+ runtimeEnv?: Promise<Outcome<void>>;
27
+ /** The box already holds this runtime environment, so nothing is sent. */
28
+ envDelivered?: boolean;
29
+ /** Settles when the minted environment has decided the fields above. */
30
+ decided: Promise<void>;
31
+ }
32
+ type ReuseMeasure = <T>(stage: string, operation: () => Promise<T>) => Promise<T>;
33
+ /**
34
+ * Start the reads of a reused box. A recent egress read stands in for a new one
35
+ * when the policy is `open` (a stale verdict can only cost the box its reach) or
36
+ * when this reuse sends the box no credentials: the environment it would send is
37
+ * already there and the shell has no bootstrap. A `strict` or `blocked` verdict
38
+ * never stands in for the read that gates credentials, so a changed environment
39
+ * or a bootstrap waits for a fresh read.
40
+ */
41
+ export declare function prefetchExistingBoxReads(shell: SandboxRuntimeConfig, box: SandboxInstance, runtimeEnv: Promise<Record<string, string>>, measure: ReuseMeasure): ExistingBoxPrefetch;
42
+ export declare function finalizeExistingBox(shell: SandboxRuntimeConfig, client: Sandbox, box: SandboxInstance, stage: SandboxExistingBoxStage, name: string, workspaceId: string, userId: string | undefined, harness: Harness, scope: SandboxScope, runtimeEnv: Record<string, string>, prefetch?: Omit<ExistingBoxPrefetch, 'decided'>): Promise<SandboxInstance>;
43
+ export {};