@tangle-network/agent-app 0.60.226 → 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/README.md +6 -0
- package/dist/chat-routes/index.js +6 -6
- package/dist/chat-routes/turn-routes.d.ts +2 -0
- package/dist/{chunk-EKV6T4YU.js → chunk-7QZNHBQT.js} +8 -1
- package/dist/chunk-7QZNHBQT.js.map +1 -0
- package/dist/{chunk-ILAQQYVL.js → chunk-BKVDPMFD.js} +2 -2
- package/dist/{chunk-YS2RYZQG.js → chunk-JILHXHJE.js} +789 -745
- package/dist/chunk-JILHXHJE.js.map +1 -0
- package/dist/{chunk-2TJWEFFM.js → chunk-LHGYK5I3.js} +4 -2
- package/dist/chunk-LHGYK5I3.js.map +1 -0
- package/dist/{chunk-EGIVLTLQ.js → chunk-PTB2B2OO.js} +21 -3
- package/dist/chunk-PTB2B2OO.js.map +1 -0
- package/dist/{chunk-XAD4VTP4.js → chunk-TEIKC276.js} +2 -2
- package/dist/{chunk-6XF3T6YD.js → chunk-TVPH5T4F.js} +26 -14
- package/dist/chunk-TVPH5T4F.js.map +1 -0
- package/dist/public-consultation/index.js +3 -3
- package/dist/rollout/d1.d.ts +9 -3
- package/dist/rollout/d1.js +11 -4
- package/dist/rollout/d1.js.map +1 -1
- package/dist/runtime/index.js +3 -3
- package/dist/runtime/router-turn.js +2 -2
- 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/dist/signoff/app-defaults.d.ts +4 -3
- package/dist/signoff/cli.js +1 -1
- package/dist/signoff/index.js +1 -1
- package/dist/turn-trace/index.js +2 -2
- package/dist/turn-trace/recorder.d.ts +4 -0
- package/package.json +1 -1
- package/dist/chunk-2TJWEFFM.js.map +0 -1
- package/dist/chunk-6XF3T6YD.js.map +0 -1
- package/dist/chunk-EGIVLTLQ.js.map +0 -1
- package/dist/chunk-EKV6T4YU.js.map +0 -1
- package/dist/chunk-YS2RYZQG.js.map +0 -1
- /package/dist/{chunk-ILAQQYVL.js.map → chunk-BKVDPMFD.js.map} +0 -0
- /package/dist/{chunk-XAD4VTP4.js.map → chunk-TEIKC276.js.map} +0 -0
|
@@ -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 {};
|