@tangle-network/agent-app 0.60.227 → 0.60.228
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/chat-routes/index.js +1 -1
- package/dist/{chunk-YS2RYZQG.js → chunk-JILHXHJE.js} +789 -745
- package/dist/chunk-JILHXHJE.js.map +1 -0
- package/dist/sandbox/access.d.ts +46 -0
- package/dist/sandbox/app-tools.d.ts +129 -0
- package/dist/sandbox/box-health.d.ts +8 -0
- package/dist/sandbox/configuration.d.ts +280 -0
- package/dist/sandbox/credentials.d.ts +55 -0
- package/dist/sandbox/exec-failure.d.ts +9 -0
- package/dist/sandbox/existing-box.d.ts +43 -0
- package/dist/sandbox/index.d.ts +32 -950
- package/dist/sandbox/index.js +1 -1
- package/dist/sandbox/lifecycle-errors.d.ts +51 -0
- package/dist/sandbox/payload-limits.d.ts +55 -0
- package/dist/sandbox/product-egress.d.ts +4 -0
- package/dist/sandbox/profile-corpus.d.ts +16 -0
- package/dist/sandbox/profile-files.d.ts +16 -0
- package/dist/sandbox/prompt-dispatch.d.ts +14 -0
- package/dist/sandbox/prompt-events.d.ts +71 -0
- package/dist/sandbox/prompt-options.d.ts +79 -0
- package/dist/sandbox/prompt-profile.d.ts +61 -0
- package/dist/sandbox/prompt-result.d.ts +57 -0
- package/dist/sandbox/runtime-cache.d.ts +43 -0
- package/dist/sandbox/runtime-connection.d.ts +9 -0
- package/dist/sandbox/shell-path.d.ts +2 -0
- package/dist/sandbox/workspace-boxes.d.ts +76 -0
- package/dist/sandbox/workspace-claim.d.ts +13 -0
- package/dist/sandbox/workspace-provision.d.ts +9 -0
- package/package.json +1 -1
- 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 {};
|