@alineo-labs/core 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +273 -7
- package/dist/index.mjs +361 -29
- package/package.json +2 -2
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ControlClient, DiagnosticEvent, DiagnosticEvent as DiagnosticEvent$1, DiagnosticLog, DiagnosticLog as DiagnosticLog$1, ExecClient, FileInfo, FileInfo as FileInfo$1, Metrics, Metrics as Metrics$1, PtyClient, SSEEvent } from "@alineo-labs/opensandbox";
|
|
1
|
+
import { CodeContext, CodeLanguage, ControlClient, DiagnosticEvent, DiagnosticEvent as DiagnosticEvent$1, DiagnosticLog, DiagnosticLog as DiagnosticLog$1, EgressPolicyStatus, ExecClient, FileInfo, FileInfo as FileInfo$1, Metrics, Metrics as Metrics$1, NetworkPolicy, NetworkRule, PtyClient, SSEEvent } from "@alineo-labs/opensandbox";
|
|
2
2
|
|
|
3
3
|
//#region src/ledger.d.ts
|
|
4
4
|
/** Status of a sandbox session derived from its ledger events. */
|
|
@@ -27,6 +27,32 @@ interface SandboxDetails {
|
|
|
27
27
|
* the mechanism `client.sandboxes.list({ runId })` correlates on.
|
|
28
28
|
*/
|
|
29
29
|
runId: string;
|
|
30
|
+
/**
|
|
31
|
+
* Durable resource identity this session's memory should be scoped by — see
|
|
32
|
+
* `@alineo-labs/memory`'s `ResourceRef.resourceId`. Unlike `runId` (present on every
|
|
33
|
+
* session), this is `undefined` unless the caller explicitly set `SandboxOptions.resourceId`.
|
|
34
|
+
* Threaded through the ledger the same way `runId` is (recorded in the `sandbox_created`
|
|
35
|
+
* event's payload, not a dedicated column), and inherited by `resume()`/`fork()`/
|
|
36
|
+
* `restoreSnapshot()` the same way `runId` is.
|
|
37
|
+
*/
|
|
38
|
+
resourceId?: string;
|
|
39
|
+
/**
|
|
40
|
+
* Durable team identity this session's memory should be scoped by — see
|
|
41
|
+
* `@alineo-labs/memory`'s `ResourceRef.teamId`. Threaded through the ledger the same way
|
|
42
|
+
* `resourceId` is (recorded in the `sandbox_created` event's payload, not a dedicated
|
|
43
|
+
* column), and inherited by `resume()`/`fork()`/`restoreSnapshot()` the same way. Exists so
|
|
44
|
+
* `episodicRecall()`/`episodicTree()` can be team-scoped — without this, two different
|
|
45
|
+
* teams' sessions sharing a `resourceId` (plausible: `Alineo.resourceRef` defaults
|
|
46
|
+
* `resourceId` to the agent's own name) would have their ledger histories silently merged,
|
|
47
|
+
* since the ledger otherwise has no team concept at all to filter on.
|
|
48
|
+
*/
|
|
49
|
+
teamId?: string;
|
|
50
|
+
/**
|
|
51
|
+
* `sandboxId` of the session this one was created from via `sb.fork()`, if any — absent
|
|
52
|
+
* for a top-level `client.sandbox()` session. Lets episodic memory (`@alineo-labs/memory`'s
|
|
53
|
+
* `episodicRecall`) walk a fork lineage rather than only seeing one flat session.
|
|
54
|
+
*/
|
|
55
|
+
parentSandboxId?: string;
|
|
30
56
|
}
|
|
31
57
|
/** Options for filtering session listings. */
|
|
32
58
|
interface ListSandboxOptions {
|
|
@@ -37,6 +63,10 @@ interface ListSandboxOptions {
|
|
|
37
63
|
before?: number;
|
|
38
64
|
/** Return only sessions belonging to this run — see `SandboxDetails.runId`. */
|
|
39
65
|
runId?: string;
|
|
66
|
+
/** Return only sessions scoped to this resource — see `SandboxDetails.resourceId`. */
|
|
67
|
+
resourceId?: string;
|
|
68
|
+
/** Return only sessions scoped to this team — see `SandboxDetails.teamId`. */
|
|
69
|
+
teamId?: string;
|
|
40
70
|
}
|
|
41
71
|
/** Events emitted during execution and stored in the ledger. */
|
|
42
72
|
declare enum LedgerEvent {
|
|
@@ -56,6 +86,34 @@ declare enum LedgerEvent {
|
|
|
56
86
|
SandboxPaused = "sandbox_paused",
|
|
57
87
|
/** Emitted when resume() restores the container to Running. */
|
|
58
88
|
SandboxResumed = "sandbox_resumed",
|
|
89
|
+
/**
|
|
90
|
+
* Emitted by `sb.credentials.set()`/`.patch()`. Payload is binding metadata only
|
|
91
|
+
* (name, host, injection type) — the credential value is never written to the ledger.
|
|
92
|
+
*/
|
|
93
|
+
CredentialBound = "credential_bound",
|
|
94
|
+
/** Emitted by `sb.credentials.remove()`. */
|
|
95
|
+
CredentialRevoked = "credential_revoked",
|
|
96
|
+
/**
|
|
97
|
+
* Emitted by `sb.egress.patch()`. Payload is `{ rules: NetworkRule[] }` — the exact rules
|
|
98
|
+
* passed to the sidecar, so `Sandbox.resume()` can fold a still-wanted allowance back into
|
|
99
|
+
* the resumed sandbox's boot policy (egress policy is sidecar-local and does not survive a
|
|
100
|
+
* resume). `sb.fork()` does not carry these.
|
|
101
|
+
*/
|
|
102
|
+
EgressRuleAdded = "egress_rule_added",
|
|
103
|
+
/** Emitted by `sb.egress.delete()`. Payload is `{ targets: string[] }`. */
|
|
104
|
+
EgressRuleRemoved = "egress_rule_removed",
|
|
105
|
+
/**
|
|
106
|
+
* Emitted when the permission gate pauses a tool call for human approval. Payload is
|
|
107
|
+
* `{ requestId, tool, target }` — metadata only; the raw tool arguments (which can carry
|
|
108
|
+
* secrets in a bash command or a file write) are never written to the ledger.
|
|
109
|
+
*/
|
|
110
|
+
PermissionRequested = "permission_requested",
|
|
111
|
+
/**
|
|
112
|
+
* Emitted when a `PermissionRequested` is answered — by a caller, a batched
|
|
113
|
+
* always/reject decision, a timeout, or a session resume dropping it. Payload is
|
|
114
|
+
* `{ requestId, decision }`.
|
|
115
|
+
*/
|
|
116
|
+
PermissionResolved = "permission_resolved",
|
|
59
117
|
/** Emitted once when a workflow run starts, before any steps execute. */
|
|
60
118
|
RunStarted = "run_started",
|
|
61
119
|
/** Emitted at the beginning of each step. */
|
|
@@ -184,6 +242,136 @@ declare class ConsoleLogger implements ILogger {
|
|
|
184
242
|
}
|
|
185
243
|
declare const noopLogger: ILogger;
|
|
186
244
|
//#endregion
|
|
245
|
+
//#region src/credentials.d.ts
|
|
246
|
+
/**
|
|
247
|
+
* How a credential reaches an outbound request.
|
|
248
|
+
*
|
|
249
|
+
* - `header` — the sidecar adds the header `name: <value>` (value unprefixed; use it for
|
|
250
|
+
* `Authorization`, `X-API-Key`, etc.). The common case.
|
|
251
|
+
* - `substitution` — the sidecar replaces every literal occurrence of `placeholder` in the
|
|
252
|
+
* listed request surfaces with the value. **The request must already contain `placeholder`
|
|
253
|
+
* verbatim** — the agent or its config puts it there (e.g. a base URL of
|
|
254
|
+
* `https://api.example.com/v1?key=__API_KEY__`). This is the escape hatch for APIs that
|
|
255
|
+
* only take a key in the URL; `path`/`query` values are URL-encoded, `body` is encoded per
|
|
256
|
+
* content-type.
|
|
257
|
+
*/
|
|
258
|
+
type CredentialInjection = {
|
|
259
|
+
type: "header";
|
|
260
|
+
name: string;
|
|
261
|
+
} | {
|
|
262
|
+
type: "substitution";
|
|
263
|
+
placeholder: string;
|
|
264
|
+
in: Array<"path" | "query" | "header" | "body">;
|
|
265
|
+
};
|
|
266
|
+
/**
|
|
267
|
+
* Where and how a credential is injected into outbound requests. Matched by `host` (an FQDN
|
|
268
|
+
* or wildcard domain, e.g. `"api.github.com"` or `"*.openai.com"`) and, optionally, a
|
|
269
|
+
* `pathPrefix` to further scope the binding within that host.
|
|
270
|
+
*/
|
|
271
|
+
interface CredentialBinding {
|
|
272
|
+
/** FQDN or wildcard domain this credential applies to. */
|
|
273
|
+
host: string;
|
|
274
|
+
/** Narrows the binding to requests whose path starts with this prefix. */
|
|
275
|
+
pathPrefix?: string;
|
|
276
|
+
/** How the credential reaches the request. */
|
|
277
|
+
injection: CredentialInjection;
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* Where a credential's *value* comes from — orthogonal to `CredentialBinding` (which only
|
|
281
|
+
* describes where it gets injected). Persisted in the ledger alongside the binding (metadata
|
|
282
|
+
* only, never the value itself) so `resume()`/`fork()` know how to re-supply it later.
|
|
283
|
+
*
|
|
284
|
+
* `"env"` resolves automatically from `process.env` — no caller code needed. `"external"`
|
|
285
|
+
* means the value isn't re-derivable from anything alineo can see on its own (a one-time
|
|
286
|
+
* minted token, a value generated at call time, ...) — resolving one requires an explicit
|
|
287
|
+
* `CredentialResolver` at resume/fork time, and `resolveBoundCredential()` throws rather than
|
|
288
|
+
* silently proceeding if one isn't supplied.
|
|
289
|
+
*/
|
|
290
|
+
type CredentialSource = {
|
|
291
|
+
type: "env";
|
|
292
|
+
varName: string;
|
|
293
|
+
} | {
|
|
294
|
+
type: "external";
|
|
295
|
+
ref?: string;
|
|
296
|
+
};
|
|
297
|
+
/**
|
|
298
|
+
* Persistence-agnostic contract for registering credentials that get injected into a sandbox's
|
|
299
|
+
* outbound requests without the sandbox process ever holding the real value — mirrors
|
|
300
|
+
* `IStorageAdapter`'s shape. `alineo` ships `OpenSandboxCredentialBroker` (from
|
|
301
|
+
* `@alineo-labs/vault`) as the default/only implementation today.
|
|
302
|
+
*
|
|
303
|
+
* Implementations must never surface the raw `value` passed to `set()`/`patch()` back out of
|
|
304
|
+
* any other method — `listBindings()` in particular returns binding *shape* only, so callers
|
|
305
|
+
* (e.g. `Sandbox.resume()`) can know what to re-register without alineo itself ever needing to
|
|
306
|
+
* persist a secret.
|
|
307
|
+
*/
|
|
308
|
+
interface CredentialBroker {
|
|
309
|
+
/** Register (or replace) a named credential's value and where it gets injected. */
|
|
310
|
+
set(sandboxId: string, name: string, value: string, binding: CredentialBinding): Promise<void>;
|
|
311
|
+
/** Update a binding's injection rule and/or value without needing to resupply both. */
|
|
312
|
+
patch(sandboxId: string, name: string, changes: Partial<{
|
|
313
|
+
value: string;
|
|
314
|
+
binding: CredentialBinding;
|
|
315
|
+
}>): Promise<void>;
|
|
316
|
+
/** Revoke a credential — subsequent matching requests are no longer injected. */
|
|
317
|
+
remove(sandboxId: string, name: string): Promise<void>;
|
|
318
|
+
/** List binding metadata (host/injection shape) for a sandbox — never returns values. */
|
|
319
|
+
listBindings(sandboxId: string): Promise<Array<{
|
|
320
|
+
name: string;
|
|
321
|
+
binding: CredentialBinding;
|
|
322
|
+
}>>;
|
|
323
|
+
}
|
|
324
|
+
/** Resolves a bound credential's real value, given its name and `CredentialSource`, at resume/fork time. */
|
|
325
|
+
type CredentialResolver = (name: string, source: CredentialSource) => string | undefined | Promise<string | undefined>;
|
|
326
|
+
/**
|
|
327
|
+
* Resolves a bound credential's value: `type: "env"` sources resolve automatically from
|
|
328
|
+
* `process.env`; anything else — or an env var that's since become unset — falls back to the
|
|
329
|
+
* caller-supplied `resolver`. Throws `SandboxError` if neither yields a value, rather than
|
|
330
|
+
* silently dropping the credential (the previous behavior when no resolver was supplied at
|
|
331
|
+
* all — see plans/credential-injection.md).
|
|
332
|
+
*/
|
|
333
|
+
declare function resolveBoundCredential(name: string, source: CredentialSource | undefined, resolver: CredentialResolver | undefined, sandboxId: string): Promise<string>;
|
|
334
|
+
/** One credential's reconstructed state, as recovered from ledger history by `reconstructBoundCredentials()`. */
|
|
335
|
+
interface BoundCredential {
|
|
336
|
+
binding: CredentialBinding;
|
|
337
|
+
source?: CredentialSource;
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Reconstructs the latest bound/revoked state per credential name from a session's ledger
|
|
341
|
+
* history — used by both `Sandbox.resume()` and `sb.fork()` to know what to re-register on a
|
|
342
|
+
* new sandbox, since the vault itself (sidecar-runtime-only state) never survives either
|
|
343
|
+
* operation. Scans the *whole* history, not just some replay window — credential bindings
|
|
344
|
+
* aren't tied to specific execs the way exec replay is.
|
|
345
|
+
*/
|
|
346
|
+
declare function reconstructBoundCredentials(entries: LedgerEntry[]): Map<string, BoundCredential>;
|
|
347
|
+
//#endregion
|
|
348
|
+
//#region src/egress.d.ts
|
|
349
|
+
/** The still-live outcome of a session's runtime `sb.egress.*` calls. */
|
|
350
|
+
interface ReconstructedEgress {
|
|
351
|
+
/** Rules to (re-)apply — a later add for the same target supersedes an earlier one. */
|
|
352
|
+
apply: NetworkRule[];
|
|
353
|
+
/**
|
|
354
|
+
* Targets a `sb.egress.delete()` removed and no later `patch()` re-added — these must be
|
|
355
|
+
* dropped from the resumed sandbox's boot policy too, not just from the runtime deltas
|
|
356
|
+
* (a `delete()` of a rule that came from the *original* `networkPolicy` would otherwise be
|
|
357
|
+
* silently undone on resume).
|
|
358
|
+
*/
|
|
359
|
+
remove: string[];
|
|
360
|
+
}
|
|
361
|
+
/**
|
|
362
|
+
* Reconstruct, from a session's ledger history, what its runtime `sb.egress.patch()` /
|
|
363
|
+
* `sb.egress.delete()` calls still amount to. Egress policy is sidecar-local runtime state —
|
|
364
|
+
* it does not survive the sidecar restarting and is not restored by OpenSandbox's
|
|
365
|
+
* snapshot/checkpoint — so `Sandbox.resume()` folds this back into the resumed sandbox's boot
|
|
366
|
+
* `networkPolicy`.
|
|
367
|
+
*
|
|
368
|
+
* Keyed by `target` (the sidecar's own merge key): a later add for a target wins; a later
|
|
369
|
+
* delete removes it (and is reported in `remove` so a boot-policy rule can be dropped too);
|
|
370
|
+
* a re-add after a delete brings it back. Scans the whole history, like
|
|
371
|
+
* `reconstructBoundCredentials`.
|
|
372
|
+
*/
|
|
373
|
+
declare function reconstructEgressRules(entries: LedgerEntry[]): ReconstructedEgress;
|
|
374
|
+
//#endregion
|
|
187
375
|
//#region src/exec-handle.d.ts
|
|
188
376
|
interface ExecResult {
|
|
189
377
|
stdout: string;
|
|
@@ -341,7 +529,7 @@ interface ExecCodeOptions {
|
|
|
341
529
|
/** Execution context (stateful interpreter session). */
|
|
342
530
|
context?: {
|
|
343
531
|
id: string;
|
|
344
|
-
language:
|
|
532
|
+
language: CodeLanguage;
|
|
345
533
|
};
|
|
346
534
|
}
|
|
347
535
|
/** Lifecycle hooks for observability. Pass via `SandboxDeps.hooks`. */
|
|
@@ -354,12 +542,16 @@ interface SandboxHooks {
|
|
|
354
542
|
onSandboxFailed?(sandboxId: string, error: Error): void;
|
|
355
543
|
onSandboxPaused?(sandboxId: string): void;
|
|
356
544
|
onSandboxResumed?(sandboxId: string): void;
|
|
545
|
+
/** Fires on `sb.credentials.set()`/`.patch()` — never carries the credential value. */
|
|
546
|
+
onCredentialInjected?(sandboxId: string, name: string, binding: CredentialBinding): void;
|
|
357
547
|
}
|
|
358
548
|
/** Internal dependencies injected by `Sandbox`. */
|
|
359
549
|
interface SandboxDeps {
|
|
360
550
|
control: ControlClient;
|
|
361
551
|
adapter: IStorageAdapter;
|
|
362
552
|
hooks?: SandboxHooks;
|
|
553
|
+
/** Broker for `sb.credentials.*` — undefined unless the sandbox was created with `credentialProxy: true`. */
|
|
554
|
+
credentialBroker?: CredentialBroker;
|
|
363
555
|
/** Called when `close()` completes — used by `Sandbox` for concurrency accounting. */
|
|
364
556
|
onClose?: () => void;
|
|
365
557
|
/** Default shell for all `exec()` calls on this sandbox. Defaults to `"/bin/sh"`. */
|
|
@@ -368,9 +560,19 @@ interface SandboxDeps {
|
|
|
368
560
|
* Called by `fork()` to create a new SandboxHandle from a snapshot — injected by `Sandbox`.
|
|
369
561
|
* `runId`, if passed, overrides whatever run-correlation ID this closure would otherwise
|
|
370
562
|
* default to (see `fork()`'s own docs in `lifecycle.ts` for why an explicit override is
|
|
371
|
-
* needed across a process boundary).
|
|
563
|
+
* needed across a process boundary). `opts.resourceId`/`opts.teamId` work the same way —
|
|
564
|
+
* absent, the closure falls back to whatever this sandbox's own creation captured (a
|
|
565
|
+
* continuation of the same resource's memory); passed explicitly, the forked child gets a
|
|
566
|
+
* *different* resource/team identity instead of inheriting this sandbox's one. Needed for
|
|
567
|
+
* `Alineo.spawn()`, where the child is a semantically different agent, not a branch of the
|
|
568
|
+
* same one.
|
|
372
569
|
*/
|
|
373
|
-
fork?: (snapshotId: string, tag?: string, runId?: string
|
|
570
|
+
fork?: (snapshotId: string, tag?: string, runId?: string, opts?: {
|
|
571
|
+
networkPolicy?: NetworkPolicy;
|
|
572
|
+
credentialProxy?: boolean;
|
|
573
|
+
resourceId?: string;
|
|
574
|
+
teamId?: string;
|
|
575
|
+
}) => Promise<SandboxHandle>;
|
|
374
576
|
/** Route execd and proxy calls through the OpenSandbox server. Required when the server runs in Docker. */
|
|
375
577
|
useServerProxy?: boolean;
|
|
376
578
|
}
|
|
@@ -535,7 +737,7 @@ declare class SandboxCore implements SandboxInternal {
|
|
|
535
737
|
* await sb.execCode('print(x)', { context: ctx }); // prints 42
|
|
536
738
|
* ```
|
|
537
739
|
*/
|
|
538
|
-
createCodeContext(language:
|
|
740
|
+
createCodeContext(language: CodeLanguage): Promise<CodeContext>;
|
|
539
741
|
/**
|
|
540
742
|
* Execute code via the sandbox's code interpreter (Python, JS, etc.).
|
|
541
743
|
*
|
|
@@ -651,6 +853,55 @@ declare class SandboxHandle extends SandboxCore {
|
|
|
651
853
|
}>;
|
|
652
854
|
/** Return current CPU and memory usage for this sandbox. */
|
|
653
855
|
metrics(): Promise<Metrics$1>;
|
|
856
|
+
/**
|
|
857
|
+
* Register, update, revoke, and list credentials injected into this sandbox's outbound
|
|
858
|
+
* requests without the sandbox process ever holding the real value. Requires the sandbox to
|
|
859
|
+
* have been created with `credentialProxy: true` — every method throws `SandboxError`
|
|
860
|
+
* otherwise.
|
|
861
|
+
*
|
|
862
|
+
* @example
|
|
863
|
+
* ```ts
|
|
864
|
+
* await sb.credentials.set("github", process.env.GH_TOKEN!, {
|
|
865
|
+
* host: "api.github.com",
|
|
866
|
+
* injection: { type: "header", name: "Authorization" },
|
|
867
|
+
* });
|
|
868
|
+
* await sb.credentials.remove("github");
|
|
869
|
+
* ```
|
|
870
|
+
*/
|
|
871
|
+
readonly credentials: {
|
|
872
|
+
set: (name: string, value: string, binding: CredentialBinding, source?: CredentialSource) => Promise<void>;
|
|
873
|
+
patch: (name: string, changes: Partial<{
|
|
874
|
+
value: string;
|
|
875
|
+
binding: CredentialBinding;
|
|
876
|
+
source: CredentialSource;
|
|
877
|
+
}>) => Promise<void>;
|
|
878
|
+
remove: (name: string) => Promise<void>;
|
|
879
|
+
listBindings: () => Promise<Array<{
|
|
880
|
+
name: string;
|
|
881
|
+
binding: CredentialBinding;
|
|
882
|
+
}>>;
|
|
883
|
+
};
|
|
884
|
+
/**
|
|
885
|
+
* Adjust this sandbox's outbound network policy at runtime, via its egress sidecar. Only
|
|
886
|
+
* meaningful when the sandbox was created with a `networkPolicy` (otherwise no sidecar is
|
|
887
|
+
* attached and these calls error).
|
|
888
|
+
*
|
|
889
|
+
* `patch` merges rules in (an incoming rule replaces any rule with the same `target`);
|
|
890
|
+
* `delete` removes rules by `target`. Both take effect on the running sidecar immediately
|
|
891
|
+
* and are recorded to the ledger so `resume()`/`fork()` can re-apply a still-wanted change.
|
|
892
|
+
*
|
|
893
|
+
* @example
|
|
894
|
+
* ```ts
|
|
895
|
+
* await sb.egress.patch([{ action: "allow", target: "api.github.com" }]);
|
|
896
|
+
* // …later
|
|
897
|
+
* await sb.egress.delete(["api.github.com"]);
|
|
898
|
+
* ```
|
|
899
|
+
*/
|
|
900
|
+
readonly egress: {
|
|
901
|
+
patch: (rules: NetworkRule[]) => Promise<void>;
|
|
902
|
+
delete: (targets: string[]) => Promise<void>;
|
|
903
|
+
get: () => Promise<EgressPolicyStatus>;
|
|
904
|
+
};
|
|
654
905
|
/**
|
|
655
906
|
* Stream real-time CPU and memory metrics from execd via SSE.
|
|
656
907
|
*
|
|
@@ -709,8 +960,23 @@ declare class SandboxHandle extends SandboxCore {
|
|
|
709
960
|
*
|
|
710
961
|
* @param runId Override the forked sandbox's run-correlation ID (see `SandboxDetails.runId`)
|
|
711
962
|
* instead of inheriting this sandbox's own default.
|
|
963
|
+
* @param opts.resolveCredential Resolves values for any credentials this sandbox has bound
|
|
964
|
+
* via `sb.credentials.set()` whose source can't be resolved automatically — see
|
|
965
|
+
* `CredentialResolver`. No-op if this sandbox never bound any.
|
|
966
|
+
* @param opts.credentialProxy Force-enables the child's credential proxy even if this
|
|
967
|
+
* sandbox has nothing bound to carry over — for registering brand-new credentials on the
|
|
968
|
+
* child right after `fork()` returns.
|
|
969
|
+
* @param opts.resourceId Override the forked sandbox's resource scope instead of inheriting
|
|
970
|
+
* this sandbox's own — for a fork that's a *different* resource, not a continuation of
|
|
971
|
+
* this one's memory (see `SandboxOptions.resourceId`).
|
|
972
|
+
* @param opts.teamId Same override, for team scope (see `SandboxOptions.teamId`).
|
|
712
973
|
*/
|
|
713
|
-
fork(tag?: string, runId?: string
|
|
974
|
+
fork(tag?: string, runId?: string, opts?: {
|
|
975
|
+
resolveCredential?: CredentialResolver;
|
|
976
|
+
credentialProxy?: boolean;
|
|
977
|
+
resourceId?: string;
|
|
978
|
+
teamId?: string;
|
|
979
|
+
}): Promise<SandboxHandle>;
|
|
714
980
|
/**
|
|
715
981
|
* Capture a snapshot of the sandbox's current filesystem state.
|
|
716
982
|
*
|
|
@@ -831,4 +1097,4 @@ declare class StepTimeoutError extends WorkflowError {
|
|
|
831
1097
|
constructor(stepId: string, timeoutMs: number);
|
|
832
1098
|
}
|
|
833
1099
|
//#endregion
|
|
834
|
-
export { type AttachableSource, BashSession, type CheckpointInfo, CommandError, type ComposeHooksOptions, ConsoleLogger, type DiagnosticEvent, type DiagnosticLog, type EnvironmentRecord, type ExecCodeOptions, ExecConnectionError, ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type ILogger, type IStorageAdapter, InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, LogLevel, type Metrics, type PendingInteractiveExec, type PtyControls, type SandboxDeps, type SandboxDetails, SandboxError, SandboxHandle, type SandboxHooks, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
|
|
1100
|
+
export { type AttachableSource, BashSession, type BoundCredential, type CheckpointInfo, CommandError, type ComposeHooksOptions, ConsoleLogger, type CredentialBinding, type CredentialBroker, type CredentialInjection, type CredentialResolver, type CredentialSource, type DiagnosticEvent, type DiagnosticLog, type EnvironmentRecord, type ExecCodeOptions, ExecConnectionError, ExecHandle, type ExecOptions, type ExecResult, type FileInfo, type ILogger, type IStorageAdapter, InteractiveExecHandle, type LedgerEntry, LedgerEvent, type ListSandboxOptions, LogLevel, type Metrics, type PendingInteractiveExec, type PtyControls, type ReconstructedEgress, type SandboxDeps, type SandboxDetails, SandboxError, SandboxHandle, type SandboxHooks, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, reconstructBoundCredentials, reconstructEgressRules, resolveBoundCredential, resolveExecClient };
|
package/dist/index.mjs
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ExecClient, PtyClient, SSEEventType, SandboxState, SnapshotState } from "@alineo-labs/opensandbox";
|
|
1
|
+
import { EgressClient, ExecClient, PtyClient, SSEEventType, SandboxState, SnapshotState } from "@alineo-labs/opensandbox";
|
|
2
2
|
//#region src/ledger.ts
|
|
3
3
|
/** Status of a sandbox session derived from its ledger events. */
|
|
4
4
|
let SandboxStatus = /* @__PURE__ */ function(SandboxStatus) {
|
|
@@ -24,6 +24,34 @@ let LedgerEvent = /* @__PURE__ */ function(LedgerEvent) {
|
|
|
24
24
|
LedgerEvent["SandboxPaused"] = "sandbox_paused";
|
|
25
25
|
/** Emitted when resume() restores the container to Running. */
|
|
26
26
|
LedgerEvent["SandboxResumed"] = "sandbox_resumed";
|
|
27
|
+
/**
|
|
28
|
+
* Emitted by `sb.credentials.set()`/`.patch()`. Payload is binding metadata only
|
|
29
|
+
* (name, host, injection type) — the credential value is never written to the ledger.
|
|
30
|
+
*/
|
|
31
|
+
LedgerEvent["CredentialBound"] = "credential_bound";
|
|
32
|
+
/** Emitted by `sb.credentials.remove()`. */
|
|
33
|
+
LedgerEvent["CredentialRevoked"] = "credential_revoked";
|
|
34
|
+
/**
|
|
35
|
+
* Emitted by `sb.egress.patch()`. Payload is `{ rules: NetworkRule[] }` — the exact rules
|
|
36
|
+
* passed to the sidecar, so `Sandbox.resume()` can fold a still-wanted allowance back into
|
|
37
|
+
* the resumed sandbox's boot policy (egress policy is sidecar-local and does not survive a
|
|
38
|
+
* resume). `sb.fork()` does not carry these.
|
|
39
|
+
*/
|
|
40
|
+
LedgerEvent["EgressRuleAdded"] = "egress_rule_added";
|
|
41
|
+
/** Emitted by `sb.egress.delete()`. Payload is `{ targets: string[] }`. */
|
|
42
|
+
LedgerEvent["EgressRuleRemoved"] = "egress_rule_removed";
|
|
43
|
+
/**
|
|
44
|
+
* Emitted when the permission gate pauses a tool call for human approval. Payload is
|
|
45
|
+
* `{ requestId, tool, target }` — metadata only; the raw tool arguments (which can carry
|
|
46
|
+
* secrets in a bash command or a file write) are never written to the ledger.
|
|
47
|
+
*/
|
|
48
|
+
LedgerEvent["PermissionRequested"] = "permission_requested";
|
|
49
|
+
/**
|
|
50
|
+
* Emitted when a `PermissionRequested` is answered — by a caller, a batched
|
|
51
|
+
* always/reject decision, a timeout, or a session resume dropping it. Payload is
|
|
52
|
+
* `{ requestId, decision }`.
|
|
53
|
+
*/
|
|
54
|
+
LedgerEvent["PermissionResolved"] = "permission_resolved";
|
|
27
55
|
/** Emitted once when a workflow run starts, before any steps execute. */
|
|
28
56
|
LedgerEvent["RunStarted"] = "run_started";
|
|
29
57
|
/** Emitted at the beginning of each step. */
|
|
@@ -154,6 +182,80 @@ var StepTimeoutError = class extends WorkflowError {
|
|
|
154
182
|
}
|
|
155
183
|
};
|
|
156
184
|
//#endregion
|
|
185
|
+
//#region src/credentials.ts
|
|
186
|
+
/**
|
|
187
|
+
* Resolves a bound credential's value: `type: "env"` sources resolve automatically from
|
|
188
|
+
* `process.env`; anything else — or an env var that's since become unset — falls back to the
|
|
189
|
+
* caller-supplied `resolver`. Throws `SandboxError` if neither yields a value, rather than
|
|
190
|
+
* silently dropping the credential (the previous behavior when no resolver was supplied at
|
|
191
|
+
* all — see plans/credential-injection.md).
|
|
192
|
+
*/
|
|
193
|
+
async function resolveBoundCredential(name, source, resolver, sandboxId) {
|
|
194
|
+
if (source?.type === "env") {
|
|
195
|
+
const fromEnv = process.env[source.varName];
|
|
196
|
+
if (fromEnv !== void 0) return fromEnv;
|
|
197
|
+
}
|
|
198
|
+
const fromResolver = await resolver?.(name, source ?? { type: "external" });
|
|
199
|
+
if (fromResolver !== void 0) return fromResolver;
|
|
200
|
+
throw new SandboxError(`Cannot resolve credential "${name}" for sandbox ${sandboxId}` + (source?.type === "env" ? ` (env var "${source.varName}" is not set)` : ` (source: ${source?.type ?? "unknown"})`) + ` — pass a resolveCredential callback that returns a value for it.`, sandboxId);
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Reconstructs the latest bound/revoked state per credential name from a session's ledger
|
|
204
|
+
* history — used by both `Sandbox.resume()` and `sb.fork()` to know what to re-register on a
|
|
205
|
+
* new sandbox, since the vault itself (sidecar-runtime-only state) never survives either
|
|
206
|
+
* operation. Scans the *whole* history, not just some replay window — credential bindings
|
|
207
|
+
* aren't tied to specific execs the way exec replay is.
|
|
208
|
+
*/
|
|
209
|
+
function reconstructBoundCredentials(entries) {
|
|
210
|
+
const result = /* @__PURE__ */ new Map();
|
|
211
|
+
for (const entry of entries) if (entry.event === "credential_bound") {
|
|
212
|
+
const { name, binding, source } = entry.payload;
|
|
213
|
+
result.set(name, {
|
|
214
|
+
binding,
|
|
215
|
+
source
|
|
216
|
+
});
|
|
217
|
+
} else if (entry.event === "credential_revoked") {
|
|
218
|
+
const { name } = entry.payload;
|
|
219
|
+
result.delete(name);
|
|
220
|
+
}
|
|
221
|
+
return result;
|
|
222
|
+
}
|
|
223
|
+
//#endregion
|
|
224
|
+
//#region src/egress.ts
|
|
225
|
+
/**
|
|
226
|
+
* Reconstruct, from a session's ledger history, what its runtime `sb.egress.patch()` /
|
|
227
|
+
* `sb.egress.delete()` calls still amount to. Egress policy is sidecar-local runtime state —
|
|
228
|
+
* it does not survive the sidecar restarting and is not restored by OpenSandbox's
|
|
229
|
+
* snapshot/checkpoint — so `Sandbox.resume()` folds this back into the resumed sandbox's boot
|
|
230
|
+
* `networkPolicy`.
|
|
231
|
+
*
|
|
232
|
+
* Keyed by `target` (the sidecar's own merge key): a later add for a target wins; a later
|
|
233
|
+
* delete removes it (and is reported in `remove` so a boot-policy rule can be dropped too);
|
|
234
|
+
* a re-add after a delete brings it back. Scans the whole history, like
|
|
235
|
+
* `reconstructBoundCredentials`.
|
|
236
|
+
*/
|
|
237
|
+
function reconstructEgressRules(entries) {
|
|
238
|
+
const byTarget = /* @__PURE__ */ new Map();
|
|
239
|
+
const removed = /* @__PURE__ */ new Set();
|
|
240
|
+
for (const entry of entries) if (entry.event === "egress_rule_added") {
|
|
241
|
+
const { rules } = entry.payload;
|
|
242
|
+
for (const rule of rules) {
|
|
243
|
+
byTarget.set(rule.target, rule);
|
|
244
|
+
removed.delete(rule.target);
|
|
245
|
+
}
|
|
246
|
+
} else if (entry.event === "egress_rule_removed") {
|
|
247
|
+
const { targets } = entry.payload;
|
|
248
|
+
for (const target of targets) {
|
|
249
|
+
byTarget.delete(target);
|
|
250
|
+
removed.add(target);
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
return {
|
|
254
|
+
apply: [...byTarget.values()],
|
|
255
|
+
remove: [...removed]
|
|
256
|
+
};
|
|
257
|
+
}
|
|
258
|
+
//#endregion
|
|
157
259
|
//#region src/exec-handle.ts
|
|
158
260
|
/**
|
|
159
261
|
* Returned by `SandboxHandle.exec()` and `SandboxHandle.execCode()`.
|
|
@@ -207,7 +309,9 @@ var ExecHandle = class {
|
|
|
207
309
|
exitCode
|
|
208
310
|
};
|
|
209
311
|
this._notify();
|
|
210
|
-
driver.onDone(result).then(() =>
|
|
312
|
+
driver.onDone(result).then(() => {
|
|
313
|
+
resolve(result);
|
|
314
|
+
}, (err) => {
|
|
211
315
|
this._err = err;
|
|
212
316
|
this._hasErr = true;
|
|
213
317
|
reject(err);
|
|
@@ -334,7 +438,9 @@ var InteractiveExecHandle = class extends ExecHandle {
|
|
|
334
438
|
* the live remote shell. Resolves when the session ends.
|
|
335
439
|
*/
|
|
336
440
|
async attach(readable, writable) {
|
|
337
|
-
const onData = (chunk) =>
|
|
441
|
+
const onData = (chunk) => {
|
|
442
|
+
this.write(chunk.toString());
|
|
443
|
+
};
|
|
338
444
|
readable.on("data", onData);
|
|
339
445
|
try {
|
|
340
446
|
await this.pipe(writable);
|
|
@@ -483,7 +589,7 @@ var SandboxCore = class {
|
|
|
483
589
|
}
|
|
484
590
|
async getExecClient() {
|
|
485
591
|
if (this._paused) throw new SandboxError("sandbox is paused — call resume() first", this.sandboxId);
|
|
486
|
-
|
|
592
|
+
this._execClient ??= await resolveExecClient(this.deps.control, this.sandboxId, this.deps.useServerProxy);
|
|
487
593
|
return this._execClient;
|
|
488
594
|
}
|
|
489
595
|
/** Resolve a fresh `PtyClient` for a new interactive session. Reuses `getExecClient()`'s readiness wait. */
|
|
@@ -536,9 +642,10 @@ var SandboxCore = class {
|
|
|
536
642
|
exec(cmd, opts = {}) {
|
|
537
643
|
if (opts.interactive) return this._execInteractive(cmd, opts);
|
|
538
644
|
const seq = ++this._seq;
|
|
539
|
-
|
|
645
|
+
const cachedResult = this.replayCache.get(seq);
|
|
646
|
+
if (cachedResult) return new ExecHandle({
|
|
540
647
|
type: "replay",
|
|
541
|
-
result:
|
|
648
|
+
result: cachedResult
|
|
542
649
|
});
|
|
543
650
|
const self = this;
|
|
544
651
|
async function* stream() {
|
|
@@ -579,9 +686,10 @@ var SandboxCore = class {
|
|
|
579
686
|
/** Backs `exec(cmd, { interactive: true })` — see that method's docs. */
|
|
580
687
|
_execInteractive(cmd, opts) {
|
|
581
688
|
const seq = ++this._seq;
|
|
582
|
-
|
|
689
|
+
const cachedResult = this.replayCache.get(seq);
|
|
690
|
+
if (cachedResult) return new InteractiveExecHandle({
|
|
583
691
|
type: "replay",
|
|
584
|
-
result:
|
|
692
|
+
result: cachedResult
|
|
585
693
|
});
|
|
586
694
|
const pending = this.pendingInteractive.get(seq);
|
|
587
695
|
const self = this;
|
|
@@ -614,7 +722,9 @@ var SandboxCore = class {
|
|
|
614
722
|
text: chunk
|
|
615
723
|
});
|
|
616
724
|
push(chunk);
|
|
617
|
-
}, (exitCode) =>
|
|
725
|
+
}, (exitCode) => {
|
|
726
|
+
finish(exitCode);
|
|
727
|
+
});
|
|
618
728
|
closer = async () => {
|
|
619
729
|
if (closer) self.openSessionClosers.delete(closer);
|
|
620
730
|
pty.close();
|
|
@@ -654,16 +764,24 @@ var SandboxCore = class {
|
|
|
654
764
|
type: "stdin",
|
|
655
765
|
text: data
|
|
656
766
|
}));
|
|
657
|
-
ptyPromise.then((pty) =>
|
|
767
|
+
ptyPromise.then((pty) => {
|
|
768
|
+
pty.write(data);
|
|
769
|
+
});
|
|
658
770
|
},
|
|
659
771
|
resize: (cols, rows) => {
|
|
660
|
-
ptyPromise.then((pty) =>
|
|
772
|
+
ptyPromise.then((pty) => {
|
|
773
|
+
pty.resize(cols, rows);
|
|
774
|
+
});
|
|
661
775
|
},
|
|
662
776
|
signal: (name) => {
|
|
663
|
-
ptyPromise.then((pty) =>
|
|
777
|
+
ptyPromise.then((pty) => {
|
|
778
|
+
pty.signal(name);
|
|
779
|
+
});
|
|
664
780
|
},
|
|
665
781
|
close: () => {
|
|
666
|
-
ptyPromise.then((pty) =>
|
|
782
|
+
ptyPromise.then((pty) => {
|
|
783
|
+
pty.close();
|
|
784
|
+
});
|
|
667
785
|
}
|
|
668
786
|
});
|
|
669
787
|
}
|
|
@@ -694,9 +812,10 @@ var SandboxCore = class {
|
|
|
694
812
|
*/
|
|
695
813
|
execCode(code, opts = {}) {
|
|
696
814
|
const seq = ++this._seq;
|
|
697
|
-
|
|
815
|
+
const cachedResult = this.replayCache.get(seq);
|
|
816
|
+
if (cachedResult) return new ExecHandle({
|
|
698
817
|
type: "replay",
|
|
699
|
-
result:
|
|
818
|
+
result: cachedResult
|
|
700
819
|
});
|
|
701
820
|
const self = this;
|
|
702
821
|
async function* stream() {
|
|
@@ -805,7 +924,7 @@ async function readFile(sb, path) {
|
|
|
805
924
|
while (true) {
|
|
806
925
|
const { done, value } = await reader.read();
|
|
807
926
|
if (done) break;
|
|
808
|
-
|
|
927
|
+
chunks.push(value);
|
|
809
928
|
}
|
|
810
929
|
const total = chunks.reduce((n, c) => n + c.length, 0);
|
|
811
930
|
const merged = new Uint8Array(total);
|
|
@@ -919,8 +1038,23 @@ async function checkpoint(sb, name) {
|
|
|
919
1038
|
* no access to the original in-memory closure) — the caller reads the correct value from
|
|
920
1039
|
* `process.env.ALINEO_RUN_ID` and passes it explicitly rather than relying on this sandbox's
|
|
921
1040
|
* own (possibly unknown) default.
|
|
1041
|
+
* @param opts.resolveCredential Resolves values for credentials this sandbox has bound whose
|
|
1042
|
+
* `CredentialSource` isn't `"env"` (or whose env var has since become unset) — the vault is
|
|
1043
|
+
* sidecar-runtime-only, so it never survives the fork on its own. Only relevant if this
|
|
1044
|
+
* sandbox has ever called `sb.credentials.set()`; a no-op otherwise. Throws `SandboxError`
|
|
1045
|
+
* if a bound credential can't be resolved rather than silently omitting it from the child.
|
|
1046
|
+
* @param opts.credentialProxy Force-enables the child's credential proxy even if this sandbox
|
|
1047
|
+
* has no bound credentials of its own to carry over — for a caller that plans to register
|
|
1048
|
+
* brand-new credentials on the child right after `fork()` returns (this sandbox's own bound
|
|
1049
|
+
* credentials, if any, always enable it regardless of this flag).
|
|
1050
|
+
* @param opts.resourceId Override the forked sandbox's resource scope (see
|
|
1051
|
+
* `SandboxOptions.resourceId`) instead of inheriting this sandbox's own default — for a fork
|
|
1052
|
+
* that's a *different* resource, not a continuation of this one's memory (e.g.
|
|
1053
|
+
* `alineo`'s `Alineo.spawn()`, where the child is a semantically different agent).
|
|
1054
|
+
* @param opts.teamId Same override, for team scope (see `SandboxOptions.teamId`). Independent
|
|
1055
|
+
* of `opts.resourceId` — pass either, both, or neither.
|
|
922
1056
|
*/
|
|
923
|
-
async function fork(sb, tag, runId) {
|
|
1057
|
+
async function fork(sb, tag, runId, opts) {
|
|
924
1058
|
if (!sb.deps.fork) throw new SandboxError("fork() is not supported on this sandbox", sb.sandboxId);
|
|
925
1059
|
const snap = await sb.deps.control.createSnapshot(sb.sandboxId);
|
|
926
1060
|
await sb.waitForSnapshot(snap.id);
|
|
@@ -929,7 +1063,23 @@ async function fork(sb, tag, runId) {
|
|
|
929
1063
|
name: tag
|
|
930
1064
|
});
|
|
931
1065
|
sb.deps.hooks?.onCheckpoint?.(sb.sandboxId, snap.id, tag);
|
|
932
|
-
|
|
1066
|
+
const boundCredentials = reconstructBoundCredentials(await sb.deps.adapter.readAll(sb.name, sb.sandboxId));
|
|
1067
|
+
const needsCredentialProxy = boundCredentials.size > 0 || opts?.credentialProxy === true;
|
|
1068
|
+
const networkPolicy = needsCredentialProxy ? {
|
|
1069
|
+
defaultAction: "allow",
|
|
1070
|
+
egress: []
|
|
1071
|
+
} : void 0;
|
|
1072
|
+
const child = await sb.deps.fork(snap.id, tag, runId, {
|
|
1073
|
+
networkPolicy,
|
|
1074
|
+
credentialProxy: needsCredentialProxy,
|
|
1075
|
+
resourceId: opts?.resourceId,
|
|
1076
|
+
teamId: opts?.teamId
|
|
1077
|
+
});
|
|
1078
|
+
for (const [name, { binding, source }] of boundCredentials) {
|
|
1079
|
+
const value = await resolveBoundCredential(name, source, opts?.resolveCredential, sb.sandboxId);
|
|
1080
|
+
await child.credentials.set(name, value, binding, source);
|
|
1081
|
+
}
|
|
1082
|
+
return child;
|
|
933
1083
|
}
|
|
934
1084
|
/**
|
|
935
1085
|
* Delete the sandbox container and release its resources.
|
|
@@ -992,6 +1142,88 @@ async function proxy(sb, port) {
|
|
|
992
1142
|
};
|
|
993
1143
|
}
|
|
994
1144
|
//#endregion
|
|
1145
|
+
//#region src/sandbox/credentials.ts
|
|
1146
|
+
function requireBroker(sb) {
|
|
1147
|
+
const broker = sb.deps.credentialBroker;
|
|
1148
|
+
if (!broker) throw new SandboxError("No CredentialBroker configured — pass credentialProxy: true to client.sandbox() (and ensure the OpenSandbox server has egress.image configured) to use sb.credentials.*", sb.sandboxId);
|
|
1149
|
+
return broker;
|
|
1150
|
+
}
|
|
1151
|
+
/**
|
|
1152
|
+
* Register (or replace) a named credential's value and where it gets injected.
|
|
1153
|
+
*
|
|
1154
|
+
* @param source Where `value` came from — `{ type: "env", varName }` resolves automatically
|
|
1155
|
+
* on `resume()`/`fork()`; anything else (including omitting this) requires an explicit
|
|
1156
|
+
* `resolveCredential` callback there, and `resume()`/`fork()` throw rather than silently
|
|
1157
|
+
* dropping the credential if one isn't supplied. Persisted as metadata only — never `value`.
|
|
1158
|
+
*/
|
|
1159
|
+
async function set(sb, name, value, binding, source) {
|
|
1160
|
+
await requireBroker(sb).set(sb.sandboxId, name, value, binding);
|
|
1161
|
+
await sb.emit("credential_bound", -1, {
|
|
1162
|
+
name,
|
|
1163
|
+
binding,
|
|
1164
|
+
source
|
|
1165
|
+
});
|
|
1166
|
+
sb.deps.hooks?.onCredentialInjected?.(sb.sandboxId, name, binding);
|
|
1167
|
+
}
|
|
1168
|
+
/**
|
|
1169
|
+
* Update a binding's injection rule, source, and/or value without needing to resupply all
|
|
1170
|
+
* three. Note: a ledger entry (needed for `resume()`/`fork()` reconstruction) is only written
|
|
1171
|
+
* when `changes.binding` is provided — this module doesn't track prior state to merge a
|
|
1172
|
+
* source-only change against, so changing `source` alone requires re-passing the (possibly
|
|
1173
|
+
* unchanged) `binding` too.
|
|
1174
|
+
*/
|
|
1175
|
+
async function patch$1(sb, name, changes) {
|
|
1176
|
+
await requireBroker(sb).patch(sb.sandboxId, name, {
|
|
1177
|
+
value: changes.value,
|
|
1178
|
+
binding: changes.binding
|
|
1179
|
+
});
|
|
1180
|
+
if (changes.binding) {
|
|
1181
|
+
await sb.emit("credential_bound", -1, {
|
|
1182
|
+
name,
|
|
1183
|
+
binding: changes.binding,
|
|
1184
|
+
source: changes.source
|
|
1185
|
+
});
|
|
1186
|
+
sb.deps.hooks?.onCredentialInjected?.(sb.sandboxId, name, changes.binding);
|
|
1187
|
+
}
|
|
1188
|
+
}
|
|
1189
|
+
/** Revoke a credential — subsequent matching requests are no longer injected. */
|
|
1190
|
+
async function remove$1(sb, name) {
|
|
1191
|
+
await requireBroker(sb).remove(sb.sandboxId, name);
|
|
1192
|
+
await sb.emit("credential_revoked", -1, { name });
|
|
1193
|
+
}
|
|
1194
|
+
/** List binding metadata (host/injection shape) for this sandbox — never returns values. */
|
|
1195
|
+
async function listBindings(sb) {
|
|
1196
|
+
return requireBroker(sb).listBindings(sb.sandboxId);
|
|
1197
|
+
}
|
|
1198
|
+
//#endregion
|
|
1199
|
+
//#region src/sandbox/egress.ts
|
|
1200
|
+
function client(sb) {
|
|
1201
|
+
return new EgressClient(sb.deps.control, sb.deps.useServerProxy);
|
|
1202
|
+
}
|
|
1203
|
+
/**
|
|
1204
|
+
* Merge allow/deny rules into this sandbox's live egress policy. An incoming rule replaces
|
|
1205
|
+
* any existing rule with the same `target`; every other rule and the `defaultAction` are
|
|
1206
|
+
* untouched. The change is applied to the running sidecar immediately.
|
|
1207
|
+
*
|
|
1208
|
+
* Recorded to the ledger (the rules only, no secrets) so `Sandbox.resume()` can fold a
|
|
1209
|
+
* still-wanted change back into the resumed sandbox's boot policy — egress policy is
|
|
1210
|
+
* sidecar-local and does not survive a resume. (`sb.fork()` does not carry runtime egress
|
|
1211
|
+
* rules: a fork is a fresh branch and gets a wide-open `defaultAction: "allow"` policy.)
|
|
1212
|
+
*/
|
|
1213
|
+
async function patch(sb, rules) {
|
|
1214
|
+
await client(sb).patchRules(sb.sandboxId, rules);
|
|
1215
|
+
await sb.emit("egress_rule_added", -1, { rules });
|
|
1216
|
+
}
|
|
1217
|
+
/** Remove egress rules from this sandbox's live policy, by `target`. Unknown targets are ignored. */
|
|
1218
|
+
async function remove(sb, targets) {
|
|
1219
|
+
await client(sb).deleteRules(sb.sandboxId, targets);
|
|
1220
|
+
await sb.emit("egress_rule_removed", -1, { targets });
|
|
1221
|
+
}
|
|
1222
|
+
/** This sandbox's current egress policy, as the sidecar reports it. */
|
|
1223
|
+
async function get(sb) {
|
|
1224
|
+
return client(sb).getPolicy(sb.sandboxId);
|
|
1225
|
+
}
|
|
1226
|
+
//#endregion
|
|
995
1227
|
//#region src/sandbox/sandbox.ts
|
|
996
1228
|
/**
|
|
997
1229
|
* A live sandbox container. Returned by `Sandbox.sandbox()` and `Sandbox.resume()`.
|
|
@@ -1094,6 +1326,48 @@ var SandboxHandle = class extends SandboxCore {
|
|
|
1094
1326
|
return metrics(this);
|
|
1095
1327
|
}
|
|
1096
1328
|
/**
|
|
1329
|
+
* Register, update, revoke, and list credentials injected into this sandbox's outbound
|
|
1330
|
+
* requests without the sandbox process ever holding the real value. Requires the sandbox to
|
|
1331
|
+
* have been created with `credentialProxy: true` — every method throws `SandboxError`
|
|
1332
|
+
* otherwise.
|
|
1333
|
+
*
|
|
1334
|
+
* @example
|
|
1335
|
+
* ```ts
|
|
1336
|
+
* await sb.credentials.set("github", process.env.GH_TOKEN!, {
|
|
1337
|
+
* host: "api.github.com",
|
|
1338
|
+
* injection: { type: "header", name: "Authorization" },
|
|
1339
|
+
* });
|
|
1340
|
+
* await sb.credentials.remove("github");
|
|
1341
|
+
* ```
|
|
1342
|
+
*/
|
|
1343
|
+
credentials = {
|
|
1344
|
+
set: (name, value, binding, source) => set(this, name, value, binding, source),
|
|
1345
|
+
patch: (name, changes) => patch$1(this, name, changes),
|
|
1346
|
+
remove: (name) => remove$1(this, name),
|
|
1347
|
+
listBindings: () => listBindings(this)
|
|
1348
|
+
};
|
|
1349
|
+
/**
|
|
1350
|
+
* Adjust this sandbox's outbound network policy at runtime, via its egress sidecar. Only
|
|
1351
|
+
* meaningful when the sandbox was created with a `networkPolicy` (otherwise no sidecar is
|
|
1352
|
+
* attached and these calls error).
|
|
1353
|
+
*
|
|
1354
|
+
* `patch` merges rules in (an incoming rule replaces any rule with the same `target`);
|
|
1355
|
+
* `delete` removes rules by `target`. Both take effect on the running sidecar immediately
|
|
1356
|
+
* and are recorded to the ledger so `resume()`/`fork()` can re-apply a still-wanted change.
|
|
1357
|
+
*
|
|
1358
|
+
* @example
|
|
1359
|
+
* ```ts
|
|
1360
|
+
* await sb.egress.patch([{ action: "allow", target: "api.github.com" }]);
|
|
1361
|
+
* // …later
|
|
1362
|
+
* await sb.egress.delete(["api.github.com"]);
|
|
1363
|
+
* ```
|
|
1364
|
+
*/
|
|
1365
|
+
egress = {
|
|
1366
|
+
patch: (rules) => patch(this, rules),
|
|
1367
|
+
delete: (targets) => remove(this, targets),
|
|
1368
|
+
get: () => get(this)
|
|
1369
|
+
};
|
|
1370
|
+
/**
|
|
1097
1371
|
* Stream real-time CPU and memory metrics from execd via SSE.
|
|
1098
1372
|
*
|
|
1099
1373
|
* Holds a long-lived connection — break out of the loop when done to avoid
|
|
@@ -1163,9 +1437,19 @@ var SandboxHandle = class extends SandboxCore {
|
|
|
1163
1437
|
*
|
|
1164
1438
|
* @param runId Override the forked sandbox's run-correlation ID (see `SandboxDetails.runId`)
|
|
1165
1439
|
* instead of inheriting this sandbox's own default.
|
|
1440
|
+
* @param opts.resolveCredential Resolves values for any credentials this sandbox has bound
|
|
1441
|
+
* via `sb.credentials.set()` whose source can't be resolved automatically — see
|
|
1442
|
+
* `CredentialResolver`. No-op if this sandbox never bound any.
|
|
1443
|
+
* @param opts.credentialProxy Force-enables the child's credential proxy even if this
|
|
1444
|
+
* sandbox has nothing bound to carry over — for registering brand-new credentials on the
|
|
1445
|
+
* child right after `fork()` returns.
|
|
1446
|
+
* @param opts.resourceId Override the forked sandbox's resource scope instead of inheriting
|
|
1447
|
+
* this sandbox's own — for a fork that's a *different* resource, not a continuation of
|
|
1448
|
+
* this one's memory (see `SandboxOptions.resourceId`).
|
|
1449
|
+
* @param opts.teamId Same override, for team scope (see `SandboxOptions.teamId`).
|
|
1166
1450
|
*/
|
|
1167
|
-
async fork(tag, runId) {
|
|
1168
|
-
return fork(this, tag, runId);
|
|
1451
|
+
async fork(tag, runId, opts) {
|
|
1452
|
+
return fork(this, tag, runId, opts);
|
|
1169
1453
|
}
|
|
1170
1454
|
/**
|
|
1171
1455
|
* Capture a snapshot of the sandbox's current filesystem state.
|
|
@@ -1223,30 +1507,78 @@ function composeHooks(hooks, opts = {}) {
|
|
|
1223
1507
|
}
|
|
1224
1508
|
return {
|
|
1225
1509
|
onSandboxCreated(sandboxId, name) {
|
|
1226
|
-
active.forEach((h, i) =>
|
|
1510
|
+
active.forEach((h, i) => {
|
|
1511
|
+
const fn = h.onSandboxCreated?.bind(h);
|
|
1512
|
+
if (fn) call("onSandboxCreated", i, () => {
|
|
1513
|
+
fn(sandboxId, name);
|
|
1514
|
+
});
|
|
1515
|
+
});
|
|
1227
1516
|
},
|
|
1228
1517
|
onExecStart(sandboxId, seq, cmd) {
|
|
1229
|
-
active.forEach((h, i) =>
|
|
1518
|
+
active.forEach((h, i) => {
|
|
1519
|
+
const fn = h.onExecStart?.bind(h);
|
|
1520
|
+
if (fn) call("onExecStart", i, () => {
|
|
1521
|
+
fn(sandboxId, seq, cmd);
|
|
1522
|
+
});
|
|
1523
|
+
});
|
|
1230
1524
|
},
|
|
1231
1525
|
onExecComplete(sandboxId, seq, result) {
|
|
1232
|
-
active.forEach((h, i) =>
|
|
1526
|
+
active.forEach((h, i) => {
|
|
1527
|
+
const fn = h.onExecComplete?.bind(h);
|
|
1528
|
+
if (fn) call("onExecComplete", i, () => {
|
|
1529
|
+
fn(sandboxId, seq, result);
|
|
1530
|
+
});
|
|
1531
|
+
});
|
|
1233
1532
|
},
|
|
1234
1533
|
onCheckpoint(sandboxId, snapshotId, name) {
|
|
1235
|
-
active.forEach((h, i) =>
|
|
1534
|
+
active.forEach((h, i) => {
|
|
1535
|
+
const fn = h.onCheckpoint?.bind(h);
|
|
1536
|
+
if (fn) call("onCheckpoint", i, () => {
|
|
1537
|
+
fn(sandboxId, snapshotId, name);
|
|
1538
|
+
});
|
|
1539
|
+
});
|
|
1236
1540
|
},
|
|
1237
1541
|
onSandboxClosed(sandboxId) {
|
|
1238
|
-
active.forEach((h, i) =>
|
|
1542
|
+
active.forEach((h, i) => {
|
|
1543
|
+
const fn = h.onSandboxClosed?.bind(h);
|
|
1544
|
+
if (fn) call("onSandboxClosed", i, () => {
|
|
1545
|
+
fn(sandboxId);
|
|
1546
|
+
});
|
|
1547
|
+
});
|
|
1239
1548
|
},
|
|
1240
1549
|
onSandboxFailed(sandboxId, error) {
|
|
1241
|
-
active.forEach((h, i) =>
|
|
1550
|
+
active.forEach((h, i) => {
|
|
1551
|
+
const fn = h.onSandboxFailed?.bind(h);
|
|
1552
|
+
if (fn) call("onSandboxFailed", i, () => {
|
|
1553
|
+
fn(sandboxId, error);
|
|
1554
|
+
});
|
|
1555
|
+
});
|
|
1242
1556
|
},
|
|
1243
1557
|
onSandboxPaused(sandboxId) {
|
|
1244
|
-
active.forEach((h, i) =>
|
|
1558
|
+
active.forEach((h, i) => {
|
|
1559
|
+
const fn = h.onSandboxPaused?.bind(h);
|
|
1560
|
+
if (fn) call("onSandboxPaused", i, () => {
|
|
1561
|
+
fn(sandboxId);
|
|
1562
|
+
});
|
|
1563
|
+
});
|
|
1245
1564
|
},
|
|
1246
1565
|
onSandboxResumed(sandboxId) {
|
|
1247
|
-
active.forEach((h, i) =>
|
|
1566
|
+
active.forEach((h, i) => {
|
|
1567
|
+
const fn = h.onSandboxResumed?.bind(h);
|
|
1568
|
+
if (fn) call("onSandboxResumed", i, () => {
|
|
1569
|
+
fn(sandboxId);
|
|
1570
|
+
});
|
|
1571
|
+
});
|
|
1572
|
+
},
|
|
1573
|
+
onCredentialInjected(sandboxId, name, binding) {
|
|
1574
|
+
active.forEach((h, i) => {
|
|
1575
|
+
const fn = h.onCredentialInjected?.bind(h);
|
|
1576
|
+
if (fn) call("onCredentialInjected", i, () => {
|
|
1577
|
+
fn(sandboxId, name, binding);
|
|
1578
|
+
});
|
|
1579
|
+
});
|
|
1248
1580
|
}
|
|
1249
1581
|
};
|
|
1250
1582
|
}
|
|
1251
1583
|
//#endregion
|
|
1252
|
-
export { BashSession, CommandError, ConsoleLogger, ExecConnectionError, ExecHandle, InteractiveExecHandle, LedgerEvent, LogLevel, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, resolveExecClient };
|
|
1584
|
+
export { BashSession, CommandError, ConsoleLogger, ExecConnectionError, ExecHandle, InteractiveExecHandle, LedgerEvent, LogLevel, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, reconstructBoundCredentials, reconstructEgressRules, resolveBoundCredential, resolveExecClient };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alineo-labs/core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
"test:watch": "vitest"
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
|
-
"@alineo-labs/opensandbox": "0.
|
|
32
|
+
"@alineo-labs/opensandbox": "0.3.0"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
35
|
"bun-types": "1.3.14",
|