@alineo-labs/core 0.3.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 CHANGED
@@ -1,4 +1,4 @@
1
- import { CodeContext, CodeLanguage, ControlClient, DiagnosticEvent, DiagnosticEvent as DiagnosticEvent$1, DiagnosticLog, DiagnosticLog as DiagnosticLog$1, ExecClient, FileInfo, FileInfo as FileInfo$1, Metrics, Metrics as Metrics$1, NetworkPolicy, 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. */
@@ -93,6 +93,27 @@ declare enum LedgerEvent {
93
93
  CredentialBound = "credential_bound",
94
94
  /** Emitted by `sb.credentials.remove()`. */
95
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",
96
117
  /** Emitted once when a workflow run starts, before any steps execute. */
97
118
  RunStarted = "run_started",
98
119
  /** Emitted at the beginning of each step. */
@@ -222,6 +243,26 @@ declare class ConsoleLogger implements ILogger {
222
243
  declare const noopLogger: ILogger;
223
244
  //#endregion
224
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
+ };
225
266
  /**
226
267
  * Where and how a credential is injected into outbound requests. Matched by `host` (an FQDN
227
268
  * or wildcard domain, e.g. `"api.github.com"` or `"*.openai.com"`) and, optionally, a
@@ -233,16 +274,7 @@ interface CredentialBinding {
233
274
  /** Narrows the binding to requests whose path starts with this prefix. */
234
275
  pathPrefix?: string;
235
276
  /** How the credential reaches the request. */
236
- injection: {
237
- type: "header";
238
- name: string;
239
- } | {
240
- type: "query";
241
- param: string;
242
- } | {
243
- type: "path";
244
- segment: string;
245
- };
277
+ injection: CredentialInjection;
246
278
  }
247
279
  /**
248
280
  * Where a credential's *value* comes from — orthogonal to `CredentialBinding` (which only
@@ -313,6 +345,33 @@ interface BoundCredential {
313
345
  */
314
346
  declare function reconstructBoundCredentials(entries: LedgerEntry[]): Map<string, BoundCredential>;
315
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
316
375
  //#region src/exec-handle.d.ts
317
376
  interface ExecResult {
318
377
  stdout: string;
@@ -822,6 +881,27 @@ declare class SandboxHandle extends SandboxCore {
822
881
  binding: CredentialBinding;
823
882
  }>>;
824
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
+ };
825
905
  /**
826
906
  * Stream real-time CPU and memory metrics from execd via SSE.
827
907
  *
@@ -1017,4 +1097,4 @@ declare class StepTimeoutError extends WorkflowError {
1017
1097
  constructor(stepId: string, timeoutMs: number);
1018
1098
  }
1019
1099
  //#endregion
1020
- export { type AttachableSource, BashSession, type BoundCredential, type CheckpointInfo, CommandError, type ComposeHooksOptions, ConsoleLogger, type CredentialBinding, type CredentialBroker, 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 SandboxDeps, type SandboxDetails, SandboxError, SandboxHandle, type SandboxHooks, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, reconstructBoundCredentials, resolveBoundCredential, 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) {
@@ -31,6 +31,27 @@ let LedgerEvent = /* @__PURE__ */ function(LedgerEvent) {
31
31
  LedgerEvent["CredentialBound"] = "credential_bound";
32
32
  /** Emitted by `sb.credentials.remove()`. */
33
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";
34
55
  /** Emitted once when a workflow run starts, before any steps execute. */
35
56
  LedgerEvent["RunStarted"] = "run_started";
36
57
  /** Emitted at the beginning of each step. */
@@ -200,6 +221,41 @@ function reconstructBoundCredentials(entries) {
200
221
  return result;
201
222
  }
202
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
203
259
  //#region src/exec-handle.ts
204
260
  /**
205
261
  * Returned by `SandboxHandle.exec()` and `SandboxHandle.execCode()`.
@@ -1116,7 +1172,7 @@ async function set(sb, name, value, binding, source) {
1116
1172
  * source-only change against, so changing `source` alone requires re-passing the (possibly
1117
1173
  * unchanged) `binding` too.
1118
1174
  */
1119
- async function patch(sb, name, changes) {
1175
+ async function patch$1(sb, name, changes) {
1120
1176
  await requireBroker(sb).patch(sb.sandboxId, name, {
1121
1177
  value: changes.value,
1122
1178
  binding: changes.binding
@@ -1131,7 +1187,7 @@ async function patch(sb, name, changes) {
1131
1187
  }
1132
1188
  }
1133
1189
  /** Revoke a credential — subsequent matching requests are no longer injected. */
1134
- async function remove(sb, name) {
1190
+ async function remove$1(sb, name) {
1135
1191
  await requireBroker(sb).remove(sb.sandboxId, name);
1136
1192
  await sb.emit("credential_revoked", -1, { name });
1137
1193
  }
@@ -1140,6 +1196,34 @@ async function listBindings(sb) {
1140
1196
  return requireBroker(sb).listBindings(sb.sandboxId);
1141
1197
  }
1142
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
1143
1227
  //#region src/sandbox/sandbox.ts
1144
1228
  /**
1145
1229
  * A live sandbox container. Returned by `Sandbox.sandbox()` and `Sandbox.resume()`.
@@ -1258,11 +1342,32 @@ var SandboxHandle = class extends SandboxCore {
1258
1342
  */
1259
1343
  credentials = {
1260
1344
  set: (name, value, binding, source) => set(this, name, value, binding, source),
1261
- patch: (name, changes) => patch(this, name, changes),
1262
- remove: (name) => remove(this, name),
1345
+ patch: (name, changes) => patch$1(this, name, changes),
1346
+ remove: (name) => remove$1(this, name),
1263
1347
  listBindings: () => listBindings(this)
1264
1348
  };
1265
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
+ /**
1266
1371
  * Stream real-time CPU and memory metrics from execd via SSE.
1267
1372
  *
1268
1373
  * Holds a long-lived connection — break out of the loop when done to avoid
@@ -1476,4 +1581,4 @@ function composeHooks(hooks, opts = {}) {
1476
1581
  };
1477
1582
  }
1478
1583
  //#endregion
1479
- export { BashSession, CommandError, ConsoleLogger, ExecConnectionError, ExecHandle, InteractiveExecHandle, LedgerEvent, LogLevel, SandboxError, SandboxHandle, SandboxStatus, StepTimeoutError, WorkflowError, composeHooks, noopLogger, reconstructBoundCredentials, resolveBoundCredential, 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.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.2.0"
32
+ "@alineo-labs/opensandbox": "0.3.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "bun-types": "1.3.14",