alineo 0.3.0 → 0.5.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 +451 -23
- package/dist/index.mjs +652 -30
- package/dist/pi-bridge.js +238 -5
- package/dist/pi-permission-gate.js +337 -0
- package/package.json +6 -6
package/dist/index.d.mts
CHANGED
|
@@ -1,7 +1,83 @@
|
|
|
1
|
+
import { CredentialBinding, CredentialSource, ExecOptions, ExecResult, IStorageAdapter, SandboxHandle, WorkflowError } from "@alineo-labs/core";
|
|
1
2
|
import { z } from "zod";
|
|
2
|
-
import { IStorageAdapter, SandboxHandle, WorkflowError } from "@alineo-labs/core";
|
|
3
3
|
import { Memory, ResourceRef } from "@alineo-labs/memory";
|
|
4
|
-
|
|
4
|
+
//#endregion
|
|
5
|
+
//#region src/permissions.d.ts
|
|
6
|
+
/**
|
|
7
|
+
* Human-in-the-loop tool-call policy — the host-side half.
|
|
8
|
+
*
|
|
9
|
+
* `AgentSpec.permissions` (a mode string or a full policy) is normalized here into a
|
|
10
|
+
* `NormalizedPermissionPolicy`, written into the sandbox at `/etc/alineo-pi.json`, and read
|
|
11
|
+
* by the bundled Pi gate extension (`adapters/pi-permission-gate.js`), which re-implements
|
|
12
|
+
* the tiny matcher below inline (same duplication tradeoff `pi-bridge.js` already makes —
|
|
13
|
+
* the gate can't import from a published package it runs beside via jiti). Keep the two
|
|
14
|
+
* matchers in sync; `test/permissions.test.ts` covers this one.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Shorthand for the common cases:
|
|
18
|
+
* - `"auto"` — never ask (the default; identical to not setting `permissions` at all)
|
|
19
|
+
* - `"ask"` — ask before every tool call
|
|
20
|
+
* - `"readonly"` — auto-allow the read-only tools (`read`/`grep`/`find`/`ls`), ask before
|
|
21
|
+
* `write`/`edit`/`bash`/`powershell`. Pi has no network tool — an agent reaches the
|
|
22
|
+
* network through `bash`, so `"readonly"` gates that by gating `bash`, not as a category.
|
|
23
|
+
*/
|
|
24
|
+
type PermissionMode = "auto" | "ask" | "readonly";
|
|
25
|
+
/**
|
|
26
|
+
* What happens when a rule (or the policy default) matches a tool call:
|
|
27
|
+
* - `allow` — run it, no prompt
|
|
28
|
+
* - `ask` — pause, surface a `permission_request`, wait for a human decision
|
|
29
|
+
* - `deny` — refuse, with a reason the model reads and can adjust to
|
|
30
|
+
* - `rate_limit` — allow up to `limit.count` matching calls per `limit.windowMs`, then deny
|
|
31
|
+
* - `classify` — best-effort read-vs-write triage of the call (today: `bash`/`powershell`
|
|
32
|
+
* only, splitting on `&&`/`||`/`;`/`|`/newline and checking each sub-command against a
|
|
33
|
+
* built-in safe-reader list). All sub-commands look read-only → `allow`; anything
|
|
34
|
+
* unrecognised or a redirect/`sudo`/`rm` → falls through to `ask`. For any other tool,
|
|
35
|
+
* `classify` is treated as `ask`.
|
|
36
|
+
*/
|
|
37
|
+
type PermissionAction = "allow" | "ask" | "deny" | "rate_limit" | "classify";
|
|
38
|
+
interface PermissionRule {
|
|
39
|
+
/** Tool name or glob (`*` = any run of chars, `?` = one), e.g. `"bash"`, `"write"`, `"*"`. */
|
|
40
|
+
tool: string;
|
|
41
|
+
/**
|
|
42
|
+
* Glob matched against a tool-specific target string, extracted from Pi's typed
|
|
43
|
+
* `event.input` — the command for `bash`, the path for `read`/`write`/`edit`, the query
|
|
44
|
+
* for `grep`. Anchored: `"git *"` matches `"git status"` but not `"x && git status"` —
|
|
45
|
+
* use `"*git*"` for a substring match. Omit to match any call to `tool`.
|
|
46
|
+
*/
|
|
47
|
+
pattern?: string;
|
|
48
|
+
action: PermissionAction;
|
|
49
|
+
/** `rate_limit` only: the ceiling and rolling window. */
|
|
50
|
+
limit?: {
|
|
51
|
+
count: number;
|
|
52
|
+
windowMs: number;
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
interface PermissionPolicy {
|
|
56
|
+
/** Action when no rule matches. Default `"ask"`. */
|
|
57
|
+
default?: PermissionAction;
|
|
58
|
+
/** Evaluated in order; the **last** matching rule wins (opencode semantics). */
|
|
59
|
+
rules?: PermissionRule[];
|
|
60
|
+
/**
|
|
61
|
+
* Tools the agent may never call. The gate strips these from the model's tool list at
|
|
62
|
+
* session start (via Pi's `setActiveTools`) so the model never attempts them, and also
|
|
63
|
+
* keeps an unconditional `deny` as a backstop for any tool registered after startup
|
|
64
|
+
* (SDK / MCP tools).
|
|
65
|
+
*/
|
|
66
|
+
disabledTools?: string[];
|
|
67
|
+
/**
|
|
68
|
+
* If set, the ONLY tools the model may see — the gate calls Pi's `setActiveTools` with
|
|
69
|
+
* this list at session start. `"readonly"` mode expands to this (the read-only tools).
|
|
70
|
+
* Distinct from `disabledTools` (a denylist); this is an allowlist for the toolset.
|
|
71
|
+
*/
|
|
72
|
+
restrictToTools?: string[];
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Best-effort read-vs-write triage of a shell command. `true` = every sub-command is a
|
|
76
|
+
* recognised pure reader with no output redirection; `false` = something needs a human.
|
|
77
|
+
* Mirrored verbatim in `adapters/pi-permission-gate.js`.
|
|
78
|
+
*/
|
|
79
|
+
export declare function isReadOnlyBashCommand(command: string): boolean;
|
|
80
|
+
//#endregion
|
|
5
81
|
//#region src/schema.d.ts
|
|
6
82
|
/**
|
|
7
83
|
* Opt-in alternative to a plain `AgentSpec.env` string value — instead of interpolating
|
|
@@ -18,17 +94,29 @@ interface CredentialEnvBinding {
|
|
|
18
94
|
host: string;
|
|
19
95
|
/** Narrows the binding to requests whose path starts with this prefix. */
|
|
20
96
|
pathPrefix?: string;
|
|
21
|
-
/**
|
|
97
|
+
/**
|
|
98
|
+
* How the credential reaches the request. `header` adds `name: <value>`. `substitution`
|
|
99
|
+
* replaces every literal `placeholder` in the listed request surfaces with the value — the
|
|
100
|
+
* request must already contain `placeholder` verbatim (put it in a base URL, say). Mirrors
|
|
101
|
+
* `@alineo-labs/core`'s `CredentialInjection`; `packages/agent/test/schema.test.ts` is the
|
|
102
|
+
* drift check.
|
|
103
|
+
*/
|
|
22
104
|
injection: {
|
|
23
105
|
type: "header";
|
|
24
106
|
name: string;
|
|
25
107
|
} | {
|
|
26
|
-
type: "
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
type: "path";
|
|
30
|
-
segment: string;
|
|
108
|
+
type: "substitution";
|
|
109
|
+
placeholder: string;
|
|
110
|
+
in: Array<"path" | "query" | "header" | "body">;
|
|
31
111
|
};
|
|
112
|
+
/**
|
|
113
|
+
* `"hold"` gates outbound egress to `host` behind a human decision: the agent's sandbox
|
|
114
|
+
* starts with `host` denied at the egress sidecar, the first request to it pauses and
|
|
115
|
+
* raises an approval request, and the host is allowed only once someone approves. Requires
|
|
116
|
+
* an `onEgressRequest` handler on `Alineo.load()`. Omit for the default (the host is
|
|
117
|
+
* reachable as soon as the credential is bound).
|
|
118
|
+
*/
|
|
119
|
+
approval?: "hold";
|
|
32
120
|
}
|
|
33
121
|
/**
|
|
34
122
|
* A single named setup step run inside the sandbox after Pi CLI install,
|
|
@@ -167,13 +255,23 @@ interface AgentSpec {
|
|
|
167
255
|
* regardless of what the ledger ends up calling the forked sandbox.
|
|
168
256
|
*/
|
|
169
257
|
resourceId?: string;
|
|
258
|
+
/**
|
|
259
|
+
* Human-in-the-loop tool-call policy, enforced by a bundled Pi extension that runs on
|
|
260
|
+
* every tool call before it executes. Either a mode shorthand (`"auto"` — the default,
|
|
261
|
+
* never ask; `"ask"` — ask before every call; `"readonly"` — auto-allow reads, ask before
|
|
262
|
+
* writes/exec) or a full `PermissionPolicy` with ordered per-tool / per-pattern rules
|
|
263
|
+
* (last match wins). When set to anything other than `"auto"`, a `permission_request`
|
|
264
|
+
* event is emitted on the agent stream for each gated call; resolve it with
|
|
265
|
+
* `agent.resolvePermission(requestId, decision)`.
|
|
266
|
+
*/
|
|
267
|
+
permissions?: PermissionMode | PermissionPolicy;
|
|
170
268
|
}
|
|
171
269
|
/**
|
|
172
270
|
* Validate an unknown value as an `AgentSpec`, aggregating every problem found in one pass.
|
|
173
271
|
* Throws `AgentSpecValidationError` (with a pre-formatted `.message` and a structured
|
|
174
272
|
* `.issues` array) rather than a bare `Error` — see #185.
|
|
175
273
|
*/
|
|
176
|
-
declare function validateAgentSpec(data: unknown): AgentSpec;
|
|
274
|
+
export declare function validateAgentSpec(data: unknown): AgentSpec;
|
|
177
275
|
//#endregion
|
|
178
276
|
//#region src/types.d.ts
|
|
179
277
|
/**
|
|
@@ -186,6 +284,11 @@ declare function validateAgentSpec(data: unknown): AgentSpec;
|
|
|
186
284
|
* - `extension_ui` — a Pi extension requested UI interaction; dialog requests are
|
|
187
285
|
* auto-cancelled by the bridge so Pi never stalls, but the event is forwarded so
|
|
188
286
|
* callers can observe what was requested
|
|
287
|
+
* - `permission_request` — the permission gate paused a tool call for human approval
|
|
288
|
+
* (only when `AgentSpec.permissions` is set to something other than `"auto"`); resolve
|
|
289
|
+
* it with `agent.resolvePermission(requestId, decision)`
|
|
290
|
+
* - `permission_resolved` — a `permission_request` was answered (by a caller, a batched
|
|
291
|
+
* "always"/"reject" decision, or the timeout)
|
|
189
292
|
* - `auto_retry_start` — Pi is about to retry after a transient error (429, 5xx)
|
|
190
293
|
* - `auto_retry_end` — Pi's retry sequence completed (success or exhausted)
|
|
191
294
|
* - `agent_start` — Pi began processing the prompt
|
|
@@ -226,6 +329,20 @@ type AgentEvent = {
|
|
|
226
329
|
params: unknown;
|
|
227
330
|
isDialog: boolean;
|
|
228
331
|
requestId?: string;
|
|
332
|
+
} | {
|
|
333
|
+
type: "permission_request";
|
|
334
|
+
/** Pass to `agent.resolvePermission()`. */
|
|
335
|
+
requestId: string;
|
|
336
|
+
/** The tool Pi is about to run, e.g. `"bash"`. */
|
|
337
|
+
tool: string;
|
|
338
|
+
/** Tool-specific target: the command for `bash`, the path for file tools. */
|
|
339
|
+
target: string;
|
|
340
|
+
/** Human-readable one-line summary for a prompt. */
|
|
341
|
+
title: string;
|
|
342
|
+
} | {
|
|
343
|
+
type: "permission_resolved";
|
|
344
|
+
requestId: string;
|
|
345
|
+
decision: PermissionDecision;
|
|
229
346
|
} | {
|
|
230
347
|
type: "auto_retry_start";
|
|
231
348
|
attempt: number;
|
|
@@ -286,6 +403,38 @@ type AgentEvent = {
|
|
|
286
403
|
event: string;
|
|
287
404
|
error: string;
|
|
288
405
|
};
|
|
406
|
+
/**
|
|
407
|
+
* A human's answer to a `permission_request`, passed to `agent.resolvePermission()`.
|
|
408
|
+
* - `once` — allow this one call
|
|
409
|
+
* - `always` — allow this call and auto-allow every other still-pending request for the
|
|
410
|
+
* same tool (opencode's batch-clear); does not persist past the session
|
|
411
|
+
* - `reject` — block the call; `feedback` (if given) becomes the reason the model reads,
|
|
412
|
+
* and every other still-pending request for the same tool is rejected too
|
|
413
|
+
*/
|
|
414
|
+
type PermissionDecision = {
|
|
415
|
+
kind: "once";
|
|
416
|
+
} | {
|
|
417
|
+
kind: "always";
|
|
418
|
+
} | {
|
|
419
|
+
kind: "reject";
|
|
420
|
+
feedback?: string;
|
|
421
|
+
};
|
|
422
|
+
/** The payload of a `permission_request`, as handed to a `prompt()` `onPermission` handler. */
|
|
423
|
+
interface PermissionRequest {
|
|
424
|
+
requestId: string;
|
|
425
|
+
tool: string;
|
|
426
|
+
target: string;
|
|
427
|
+
title: string;
|
|
428
|
+
}
|
|
429
|
+
/** One entry from `agent.listPendingPermissions()` — a tool call paused awaiting a decision. */
|
|
430
|
+
interface PendingPermission {
|
|
431
|
+
requestId: string;
|
|
432
|
+
tool: string;
|
|
433
|
+
target: string;
|
|
434
|
+
title: string;
|
|
435
|
+
/** Unix ms when the gate raised this request. */
|
|
436
|
+
since: number;
|
|
437
|
+
}
|
|
289
438
|
/**
|
|
290
439
|
* Async iterable of structured agent events. Returned by `Alineo.prompt()` and `Alineo.bash()`.
|
|
291
440
|
*
|
|
@@ -309,7 +458,7 @@ type AgentEvent = {
|
|
|
309
458
|
*/
|
|
310
459
|
type AgentStream = AsyncIterable<AgentEvent>;
|
|
311
460
|
/** Filter an `AgentStream` down to just text chunks. */
|
|
312
|
-
declare function textOnly(stream: AgentStream): AsyncIterable<string>;
|
|
461
|
+
export declare function textOnly(stream: AgentStream): AsyncIterable<string>;
|
|
313
462
|
/**
|
|
314
463
|
* @deprecated Use `AgentStream`. `PromptStream` will be removed in a future minor.
|
|
315
464
|
*/
|
|
@@ -384,6 +533,13 @@ interface PiSessionState {
|
|
|
384
533
|
}
|
|
385
534
|
//#endregion
|
|
386
535
|
//#region src/adapters/pi.d.ts
|
|
536
|
+
/** The subset of `SandboxHandle` that `PiAdapter` calls. `exec` only needs to be awaitable, so
|
|
537
|
+
* callers (and tests) don't have to supply a full `ExecHandle`. */
|
|
538
|
+
interface PiSandbox {
|
|
539
|
+
exec(cmd: string, opts?: ExecOptions): PromiseLike<ExecResult>;
|
|
540
|
+
proxy: SandboxHandle["proxy"];
|
|
541
|
+
writeFile: SandboxHandle["writeFile"];
|
|
542
|
+
}
|
|
387
543
|
declare class PiAdapter {
|
|
388
544
|
private _bridgeUrl;
|
|
389
545
|
/**
|
|
@@ -420,12 +576,12 @@ declare class PiAdapter {
|
|
|
420
576
|
*/
|
|
421
577
|
disposeConnections(): void;
|
|
422
578
|
/** Install Pi CLI and any spec packages. Slow — result is captured by checkpoint(). */
|
|
423
|
-
install(sb:
|
|
579
|
+
install(sb: PiSandbox, spec: AgentSpec): Promise<void>;
|
|
424
580
|
/**
|
|
425
581
|
* Write config files and the bridge script. Always runs on every start (fresh install
|
|
426
582
|
* and snapshot resume alike) so env values, model/provider, and bridge code stay current.
|
|
427
583
|
*/
|
|
428
|
-
configure(sb:
|
|
584
|
+
configure(sb: PiSandbox, spec: AgentSpec, resolvedEnv: Record<string, string>, opts?: {
|
|
429
585
|
resume?: boolean;
|
|
430
586
|
}): Promise<void>;
|
|
431
587
|
/**
|
|
@@ -439,7 +595,18 @@ declare class PiAdapter {
|
|
|
439
595
|
* be part of the exact command that spawns the bridge process so the bridge (and
|
|
440
596
|
* everything it in turn spawns, including Pi itself) inherits the already-clean env.
|
|
441
597
|
*/
|
|
442
|
-
startBridge(sb:
|
|
598
|
+
startBridge(sb: PiSandbox, unsetVars?: string[]): Promise<void>;
|
|
599
|
+
/**
|
|
600
|
+
* Rebind to a bridge that's already running (as opposed to `startBridge()`, which execs a
|
|
601
|
+
* fresh `node /alineo-bridge.js`). `sb.proxy(port)` is a pure URL lookup against the
|
|
602
|
+
* sandbox's control plane — it starts nothing — so this has zero effect on the sandbox
|
|
603
|
+
* itself: no killed process, no dropped in-flight turn, no reset Pi conversation state.
|
|
604
|
+
*
|
|
605
|
+
* Call `waitReady()` afterwards to confirm the bridge is actually still there before relying
|
|
606
|
+
* on it — the container can be alive while the bridge process inside it isn't (e.g. it
|
|
607
|
+
* crashed independently), and this method alone can't tell the difference.
|
|
608
|
+
*/
|
|
609
|
+
reattachBridge(sb: SandboxHandle): Promise<void>;
|
|
443
610
|
waitReady(timeoutMs?: number): Promise<void>;
|
|
444
611
|
prompt(message: string, opts?: {
|
|
445
612
|
streamingBehavior?: "steer" | "followUp";
|
|
@@ -448,6 +615,10 @@ declare class PiAdapter {
|
|
|
448
615
|
bash(command: string): AgentStream;
|
|
449
616
|
steer(message: string): Promise<void>;
|
|
450
617
|
abort(): Promise<void>;
|
|
618
|
+
/** Resolve a pending `permission_request` (see `AgentEvent`'s `permission_request`). */
|
|
619
|
+
resolvePermission(requestId: string, decision: PermissionDecision): Promise<void>;
|
|
620
|
+
/** Tool calls currently paused awaiting a human decision. */
|
|
621
|
+
listPendingPermissions(): Promise<PendingPermission[]>;
|
|
451
622
|
followUp(message: string): Promise<void>;
|
|
452
623
|
newSession(): Promise<void>;
|
|
453
624
|
setThinkingLevel(level: ThinkingLevel): Promise<void>;
|
|
@@ -508,11 +679,11 @@ interface AgentSnapshotRecord {
|
|
|
508
679
|
* setup: cli, cliVersion, packages, and setup. Excludes env (hot-reloadable),
|
|
509
680
|
* model/provider (CLI flags only), and cosmetic fields.
|
|
510
681
|
*/
|
|
511
|
-
declare function computeSetupHash(spec: AgentSpec): string;
|
|
682
|
+
export declare function computeSetupHash(spec: AgentSpec): string;
|
|
512
683
|
/** Derive the agent-snapshots.json path from the ledger adapter path. */
|
|
513
|
-
declare function snapshotsPath(adapterPath: string): string;
|
|
684
|
+
export declare function snapshotsPath(adapterPath: string): string;
|
|
514
685
|
/** File-backed store for agent snapshot records, keyed by specName + setupHash. */
|
|
515
|
-
declare class AgentSnapshotStore {
|
|
686
|
+
export declare class AgentSnapshotStore {
|
|
516
687
|
private readonly path;
|
|
517
688
|
constructor(path: string);
|
|
518
689
|
private _read;
|
|
@@ -525,6 +696,176 @@ declare class AgentSnapshotStore {
|
|
|
525
696
|
list(): Promise<AgentSnapshotRecord[]>;
|
|
526
697
|
}
|
|
527
698
|
//#endregion
|
|
699
|
+
//#region src/agent/egress-approval.d.ts
|
|
700
|
+
/** The subset of `SandboxHandle` the gate calls. */
|
|
701
|
+
type EgressApprovalSandbox = Pick<SandboxHandle, "egress" | "credentials" | "emit">;
|
|
702
|
+
/**
|
|
703
|
+
* Human-in-the-loop gate for a sandboxed agent's outbound network access.
|
|
704
|
+
*
|
|
705
|
+
* Credential env bindings marked `approval: "hold"` in `AgentSpec.env` start with their host
|
|
706
|
+
* *denied* at the egress sidecar (the sandbox is `defaultAction: "allow"` with an explicit
|
|
707
|
+
* `deny` rule per held host, so everything else — including the agent's own model traffic —
|
|
708
|
+
* keeps working) and their credential **not registered in the vault at all** (the vault
|
|
709
|
+
* refuses a binding whose host isn't allowed).
|
|
710
|
+
*
|
|
711
|
+
* The sidecar POSTs a fire-and-forget webhook when the sandbox is denied a DNS query. This
|
|
712
|
+
* gate listens for that, calls the caller's handler, and on approval:
|
|
713
|
+
* 1. flips the sidecar rule to `allow` for that host (`sb.egress.patch`), then
|
|
714
|
+
* 2. registers the held credential(s) for it (`sb.credentials.set`) — so the credential
|
|
715
|
+
* literally does not exist inside the sandbox until a human approves.
|
|
716
|
+
*
|
|
717
|
+
* `allow-once` reverses both at the end of the turn; `allow-always` leaves them in place.
|
|
718
|
+
* Enforcement is entirely out-of-process — a compromised in-sandbox agent cannot skip it.
|
|
719
|
+
*
|
|
720
|
+
* The listener binds `0.0.0.0` on an ephemeral port and is torn down with the agent.
|
|
721
|
+
*/
|
|
722
|
+
type EgressDecision = "allow-once" | "allow-always" | "deny";
|
|
723
|
+
/** One egress attempt awaiting a decision. */
|
|
724
|
+
interface EgressRequest {
|
|
725
|
+
/** The hostname the agent's sandbox tried to reach. */
|
|
726
|
+
host: string;
|
|
727
|
+
/** Unix ms when the sidecar reported the denial. */
|
|
728
|
+
since: number;
|
|
729
|
+
}
|
|
730
|
+
type EgressRequestHandler = (req: EgressRequest) => EgressDecision | Promise<EgressDecision>;
|
|
731
|
+
/** A credential whose registration is gated behind egress approval for its host. */
|
|
732
|
+
interface HeldCredential {
|
|
733
|
+
name: string;
|
|
734
|
+
value: string;
|
|
735
|
+
binding: CredentialBinding;
|
|
736
|
+
source?: CredentialSource;
|
|
737
|
+
}
|
|
738
|
+
interface EgressApprovalGateOptions {
|
|
739
|
+
/**
|
|
740
|
+
* Credentials whose host starts denied. The gate allows the host and registers these on
|
|
741
|
+
* approval. (Non-credential held hosts can be passed as `{ name, value: "", binding }` with
|
|
742
|
+
* an empty value — the gate then only manages the egress rule.)
|
|
743
|
+
*/
|
|
744
|
+
heldCredentials: HeldCredential[];
|
|
745
|
+
handler: EgressRequestHandler;
|
|
746
|
+
/**
|
|
747
|
+
* Address the sandbox's egress sidecar can reach this host process at. Defaults to the
|
|
748
|
+
* Docker default-bridge gateway (`172.17.0.1`), which an `alineo init` server's sidecars
|
|
749
|
+
* can reach. Override for other topologies via `ALINEO_EGRESS_APPROVAL_HOST`.
|
|
750
|
+
*/
|
|
751
|
+
webhookHost?: string;
|
|
752
|
+
}
|
|
753
|
+
export declare class EgressApprovalGate {
|
|
754
|
+
private server;
|
|
755
|
+
private port;
|
|
756
|
+
private sandbox;
|
|
757
|
+
private readonly handler;
|
|
758
|
+
private readonly webhookHost;
|
|
759
|
+
/** host → the held credentials bound to it. */
|
|
760
|
+
private readonly byHost;
|
|
761
|
+
/** Hosts still gated — dropped once permanently opened by `allow-always`. */
|
|
762
|
+
private readonly held;
|
|
763
|
+
/** host → last time we raised a request for it (dedup; the webhook fires per DNS query). */
|
|
764
|
+
private readonly seen;
|
|
765
|
+
/** Hosts with a decision currently in flight. */
|
|
766
|
+
private readonly inFlight;
|
|
767
|
+
/** Hosts approved `allow-once` — reversed on `endTurn()`. */
|
|
768
|
+
private readonly onceApproved;
|
|
769
|
+
constructor(opts: EgressApprovalGateOptions);
|
|
770
|
+
/** Attach the sandbox whose egress this gate manages. Called once its handle exists. */
|
|
771
|
+
bind(sandbox: EgressApprovalSandbox): void;
|
|
772
|
+
private sb;
|
|
773
|
+
/** Start the listener. Idempotent. */
|
|
774
|
+
start(): Promise<void>;
|
|
775
|
+
/** Stop the listener. */
|
|
776
|
+
stop(): Promise<void>;
|
|
777
|
+
/** The `OPENSANDBOX_EGRESS_DENY_WEBHOOK` value to put in the sandbox's env. */
|
|
778
|
+
get webhookUrl(): string;
|
|
779
|
+
/** Egress requests currently awaiting a decision. */
|
|
780
|
+
pending(): EgressRequest[];
|
|
781
|
+
/**
|
|
782
|
+
* Reverse every `allow-once` approval — remove its credential(s) and re-deny the host.
|
|
783
|
+
* Call when an agent turn ends so a one-shot grant does not silently persist.
|
|
784
|
+
*/
|
|
785
|
+
endTurn(): Promise<void>;
|
|
786
|
+
private onDenied;
|
|
787
|
+
}
|
|
788
|
+
//#endregion
|
|
789
|
+
//#region src/agent/internal.d.ts
|
|
790
|
+
/**
|
|
791
|
+
* Narrow surface that `session-control.ts`/`model.ts`/`introspection.ts`/
|
|
792
|
+
* `lifecycle.ts` need from `Alineo` — deliberately not exported from the
|
|
793
|
+
* package barrel, so it never becomes public API even though it's a real
|
|
794
|
+
* exported interface within the package.
|
|
795
|
+
*/
|
|
796
|
+
interface AgentInternal {
|
|
797
|
+
readonly adapter: PiAdapter;
|
|
798
|
+
readonly sandbox: SandboxHandle;
|
|
799
|
+
env: Record<string, string>;
|
|
800
|
+
/** Present when the spec has `approval: "hold"` credential bindings. */
|
|
801
|
+
readonly egressGate?: EgressApprovalGate;
|
|
802
|
+
}
|
|
803
|
+
declare namespace session_control_d_exports {
|
|
804
|
+
export { PermissionHandler, abort, abortBash, abortRetry, bash, followUp, listPendingPermissions, newSession, prompt, resolvePermission, setAutoCompaction, setAutoRetry, setFollowUpMode, setSessionName, setSteeringMode, steer };
|
|
805
|
+
}
|
|
806
|
+
/**
|
|
807
|
+
* Called for each `permission_request` on a `prompt()`/`bash()` stream when passed as
|
|
808
|
+
* `opts.onPermission`. Return the decision; the SDK resolves the request for you. The
|
|
809
|
+
* `permission_request` / `permission_resolved` events still flow through the stream.
|
|
810
|
+
*/
|
|
811
|
+
type PermissionHandler = (req: PermissionRequest) => PermissionDecision | Promise<PermissionDecision>;
|
|
812
|
+
/** Send a prompt to Pi and stream the response. Pi manages its own session context. */
|
|
813
|
+
declare function prompt(a: AgentInternal, message: string, opts?: {
|
|
814
|
+
streamingBehavior?: "steer" | "followUp";
|
|
815
|
+
inactivityTimeoutMs?: number;
|
|
816
|
+
/** Auto-resolve each `permission_request` with this handler's decision. */
|
|
817
|
+
onPermission?: PermissionHandler;
|
|
818
|
+
}): AgentStream;
|
|
819
|
+
/**
|
|
820
|
+
* Run a shell command inside Pi's working context. Not incrementally
|
|
821
|
+
* streamed — Pi returns bash output synchronously, so the full output
|
|
822
|
+
* arrives as a single `text` event once the command completes.
|
|
823
|
+
*/
|
|
824
|
+
declare function bash(a: AgentInternal, command: string): AgentStream;
|
|
825
|
+
/** Snapshot of tool calls currently paused awaiting a human decision. */
|
|
826
|
+
declare function listPendingPermissions(a: AgentInternal): Promise<PendingPermission[]>;
|
|
827
|
+
/** Steer Pi's current response mid-flight. Waits for Pi's RPC acknowledgment. */
|
|
828
|
+
declare function steer(a: AgentInternal, message: string): Promise<void>;
|
|
829
|
+
/** Abort Pi's current operation. */
|
|
830
|
+
declare function abort(a: AgentInternal): Promise<void>;
|
|
831
|
+
/**
|
|
832
|
+
* Resolve a pending `permission_request` emitted by the permission gate. `decision` is
|
|
833
|
+
* `{ kind: "once" }`, `{ kind: "always" }`, or `{ kind: "reject", feedback? }`.
|
|
834
|
+
*/
|
|
835
|
+
declare function resolvePermission(a: AgentInternal, requestId: string, decision: PermissionDecision): Promise<void>;
|
|
836
|
+
/** Queue a message to be sent to Pi after it finishes its current task. */
|
|
837
|
+
declare function followUp(a: AgentInternal, message: string): Promise<void>;
|
|
838
|
+
/** Start a fresh Pi session, clearing all prior context. */
|
|
839
|
+
declare function newSession(a: AgentInternal): Promise<void>;
|
|
840
|
+
/** Enable or disable Pi's automatic context compaction. */
|
|
841
|
+
declare function setAutoCompaction(a: AgentInternal, enabled: boolean): Promise<void>;
|
|
842
|
+
/**
|
|
843
|
+
* Enable or disable Pi's automatic retry on transient errors (429, 500, 502, 503, 504).
|
|
844
|
+
* Auto-retry is ON by default: 3 attempts with exponential backoff (2 s / 4 s / 8 s).
|
|
845
|
+
* Disable it when you want to handle errors yourself via `auto_retry_start`/`auto_retry_end`
|
|
846
|
+
* events in the stream.
|
|
847
|
+
*/
|
|
848
|
+
declare function setAutoRetry(a: AgentInternal, enabled: boolean): Promise<void>;
|
|
849
|
+
/**
|
|
850
|
+
* Abort an in-progress auto-retry immediately. Pi stops waiting and fails the current
|
|
851
|
+
* operation, emitting `auto_retry_end` with `success: false`.
|
|
852
|
+
*/
|
|
853
|
+
declare function abortRetry(a: AgentInternal): Promise<void>;
|
|
854
|
+
/** Abort a currently-executing bash command without cancelling the whole prompt. */
|
|
855
|
+
declare function abortBash(a: AgentInternal): Promise<void>;
|
|
856
|
+
/**
|
|
857
|
+
* Control how Pi processes queued steering messages.
|
|
858
|
+
* `"all"` applies all queued steers at once; `"one-at-a-time"` applies them sequentially.
|
|
859
|
+
*/
|
|
860
|
+
declare function setSteeringMode(a: AgentInternal, mode: "all" | "one-at-a-time"): Promise<void>;
|
|
861
|
+
/**
|
|
862
|
+
* Control how Pi processes queued follow-up messages.
|
|
863
|
+
* `"all"` sends all queued follow-ups at once; `"one-at-a-time"` sends them sequentially.
|
|
864
|
+
*/
|
|
865
|
+
declare function setFollowUpMode(a: AgentInternal, mode: "all" | "one-at-a-time"): Promise<void>;
|
|
866
|
+
/** Set a display name for the current Pi session. */
|
|
867
|
+
declare function setSessionName(a: AgentInternal, name: string): Promise<void>;
|
|
868
|
+
//#endregion
|
|
528
869
|
//#region src/agent/agent.d.ts
|
|
529
870
|
/**
|
|
530
871
|
* A live AI coding agent running inside an OpenSandbox container.
|
|
@@ -552,7 +893,7 @@ declare class AgentSnapshotStore {
|
|
|
552
893
|
* }
|
|
553
894
|
* ```
|
|
554
895
|
*/
|
|
555
|
-
declare class Alineo {
|
|
896
|
+
export declare class Alineo {
|
|
556
897
|
/** OpenSandbox container ID for this agent's sandbox. */
|
|
557
898
|
readonly sandboxId: string;
|
|
558
899
|
readonly name: string;
|
|
@@ -609,7 +950,15 @@ declare class Alineo {
|
|
|
609
950
|
* `.memory` methods instead if this agent's resourceId/teamId aren't the identity you want.
|
|
610
951
|
*/
|
|
611
952
|
get resourceRef(): ResourceRef;
|
|
953
|
+
/**
|
|
954
|
+
* Present when the spec has `approval: "hold"` credential bindings — the out-of-process
|
|
955
|
+
* gate that holds the sandbox's egress to those hosts until `onEgressRequest` approves.
|
|
956
|
+
* Stopped by `close()`.
|
|
957
|
+
*/
|
|
958
|
+
readonly egressGate?: EgressApprovalGate;
|
|
612
959
|
private constructor();
|
|
960
|
+
/** Egress requests currently awaiting a decision (see `AgentSpec.env` `approval: "hold"`). */
|
|
961
|
+
pendingEgressRequests(): EgressRequest[];
|
|
613
962
|
/**
|
|
614
963
|
* Validate `spec` and return a fully initialised `Alineo`.
|
|
615
964
|
*
|
|
@@ -640,8 +989,16 @@ declare class Alineo {
|
|
|
640
989
|
rebuild?: boolean;
|
|
641
990
|
spawnDepth?: number;
|
|
642
991
|
maxAgents?: number;
|
|
643
|
-
runId?: string;
|
|
992
|
+
runId?: string;
|
|
993
|
+
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
644
994
|
memory?: Memory;
|
|
995
|
+
/**
|
|
996
|
+
* Required when the spec has `approval: "hold"` credential bindings — decides each
|
|
997
|
+
* first outbound request to a held host: return `"allow-once"` (reverts at turn end),
|
|
998
|
+
* `"allow-always"` (permanent for this agent's life), or `"deny"`. Enforcement is
|
|
999
|
+
* out-of-process at the egress sidecar; a compromised agent cannot skip it.
|
|
1000
|
+
*/
|
|
1001
|
+
onEgressRequest?: EgressRequestHandler;
|
|
645
1002
|
}): Promise<Alineo>;
|
|
646
1003
|
/**
|
|
647
1004
|
* Reconnect to a previously-created agent whose host process has exited.
|
|
@@ -650,6 +1007,12 @@ declare class Alineo {
|
|
|
650
1007
|
* are already present — only the bridge process needs to be restarted.
|
|
651
1008
|
* Pi is started with `--continue` so it resumes the most recent session.
|
|
652
1009
|
*
|
|
1010
|
+
* **Kills and restarts the bridge process** — anything mid-flight when the previous host
|
|
1011
|
+
* process exited (a streaming turn, a tool call parked on a human decision) is dropped.
|
|
1012
|
+
* If the bridge might still be alive and you'd rather preserve that, try `Alineo.reattach()`
|
|
1013
|
+
* first and fall back to this only if it fails (e.g. the whole sandbox — not just this
|
|
1014
|
+
* process — actually restarted).
|
|
1015
|
+
*
|
|
653
1016
|
* @param sandboxId The sandbox ID returned by the original `Alineo.load()`.
|
|
654
1017
|
* @param opts.spec An already-parsed agent spec object — skips file I/O entirely, same as
|
|
655
1018
|
* `load()`. Takes precedence over `opts.specPath` if both are set.
|
|
@@ -679,7 +1042,45 @@ declare class Alineo {
|
|
|
679
1042
|
adapter: IStorageAdapter;
|
|
680
1043
|
spec?: AgentSpec | Record<string, unknown>;
|
|
681
1044
|
specPath?: string;
|
|
682
|
-
runId?: string;
|
|
1045
|
+
runId?: string;
|
|
1046
|
+
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
1047
|
+
memory?: Memory;
|
|
1048
|
+
}): Promise<Alineo>;
|
|
1049
|
+
/**
|
|
1050
|
+
* Reconnect to a previously-created agent WITHOUT restarting its bridge — the crash-only
|
|
1051
|
+
* counterpart to `resume()`. Use this when the caller's own process exited or restarted
|
|
1052
|
+
* (e.g. a control-plane daemon coming back up) but has good reason to believe the sandbox,
|
|
1053
|
+
* and the bridge process inside it, never stopped: nothing here kills or re-execs anything.
|
|
1054
|
+
* `sb.proxy()` is a pure URL lookup, so the only network activity is re-deriving the proxy
|
|
1055
|
+
* URL and one health-check request.
|
|
1056
|
+
*
|
|
1057
|
+
* The returned `Alineo` is fully functional — `.prompt()`/`.bash()` work exactly as they
|
|
1058
|
+
* would have on the original handle, continuing the same Pi conversation, because it's
|
|
1059
|
+
* still the same process.
|
|
1060
|
+
*
|
|
1061
|
+
* **Fails fast (5s) if the bridge doesn't answer** — the container can be `Running` while
|
|
1062
|
+
* the bridge process inside it has independently died, and this can't distinguish that from
|
|
1063
|
+
* a slow-to-respond-but-fine bridge on its own. On failure, fall back to `Alineo.resume()`.
|
|
1064
|
+
*
|
|
1065
|
+
* @param sandboxId The sandbox ID returned by the original `Alineo.load()`/`.spawn()`.
|
|
1066
|
+
* @param opts.spec / opts.specPath Same three-way fallback as `resume()` — see its docs.
|
|
1067
|
+
*
|
|
1068
|
+
* @example
|
|
1069
|
+
* ```ts
|
|
1070
|
+
* let agent: Alineo;
|
|
1071
|
+
* try {
|
|
1072
|
+
* agent = await Alineo.reattach(savedSandboxId, { adapter });
|
|
1073
|
+
* } catch {
|
|
1074
|
+
* agent = await Alineo.resume(savedSandboxId, { adapter }); // bridge really is gone
|
|
1075
|
+
* }
|
|
1076
|
+
* ```
|
|
1077
|
+
*/
|
|
1078
|
+
static reattach(sandboxId: string, opts: {
|
|
1079
|
+
adapter: IStorageAdapter;
|
|
1080
|
+
spec?: AgentSpec | Record<string, unknown>;
|
|
1081
|
+
specPath?: string;
|
|
1082
|
+
runId?: string;
|
|
1083
|
+
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
683
1084
|
memory?: Memory;
|
|
684
1085
|
}): Promise<Alineo>;
|
|
685
1086
|
/**
|
|
@@ -719,7 +1120,8 @@ declare class Alineo {
|
|
|
719
1120
|
cpu: string;
|
|
720
1121
|
memory: string;
|
|
721
1122
|
gpu?: string;
|
|
722
|
-
};
|
|
1123
|
+
};
|
|
1124
|
+
/** Wire a `Memory` instance onto the returned agent — see `Alineo.memory`. */
|
|
723
1125
|
memory?: Memory;
|
|
724
1126
|
}): Promise<Alineo>;
|
|
725
1127
|
/**
|
|
@@ -763,6 +1165,12 @@ declare class Alineo {
|
|
|
763
1165
|
prompt(message: string, opts?: {
|
|
764
1166
|
streamingBehavior?: "steer" | "followUp";
|
|
765
1167
|
inactivityTimeoutMs?: number;
|
|
1168
|
+
/**
|
|
1169
|
+
* Auto-resolve each `permission_request` on this stream with the handler's decision,
|
|
1170
|
+
* instead of the caller wiring `resolvePermission()` by hand. The
|
|
1171
|
+
* `permission_request` / `permission_resolved` events still flow through the stream.
|
|
1172
|
+
*/
|
|
1173
|
+
onPermission?: PermissionHandler;
|
|
766
1174
|
}): AgentStream;
|
|
767
1175
|
/**
|
|
768
1176
|
* Run a shell command inside Pi's working context. Not incrementally
|
|
@@ -774,6 +1182,26 @@ declare class Alineo {
|
|
|
774
1182
|
steer(message: string): Promise<void>;
|
|
775
1183
|
/** Abort Pi's current operation. */
|
|
776
1184
|
abort(): Promise<void>;
|
|
1185
|
+
/**
|
|
1186
|
+
* Resolve a pending `permission_request` from the agent stream — emitted for each gated
|
|
1187
|
+
* tool call when `AgentSpec.permissions` is set to something other than `"auto"`.
|
|
1188
|
+
*
|
|
1189
|
+
* @example
|
|
1190
|
+
* ```ts
|
|
1191
|
+
* for await (const ev of agent.prompt("Refactor auth")) {
|
|
1192
|
+
* if (ev.type === "permission_request") {
|
|
1193
|
+
* await agent.resolvePermission(ev.requestId, { kind: "once" });
|
|
1194
|
+
* }
|
|
1195
|
+
* }
|
|
1196
|
+
* ```
|
|
1197
|
+
*/
|
|
1198
|
+
resolvePermission(requestId: string, decision: PermissionDecision): Promise<void>;
|
|
1199
|
+
/**
|
|
1200
|
+
* Tool calls currently paused awaiting a human decision — useful after reconnecting to a
|
|
1201
|
+
* session to discover approvals still outstanding. Each entry is resolvable with
|
|
1202
|
+
* `resolvePermission(entry.requestId, …)`.
|
|
1203
|
+
*/
|
|
1204
|
+
listPendingPermissions(): Promise<PendingPermission[]>;
|
|
777
1205
|
/** Queue a message to be sent to Pi after it finishes its current task. */
|
|
778
1206
|
followUp(message: string): Promise<void>;
|
|
779
1207
|
/** Start a fresh Pi session, clearing all prior context. */
|
|
@@ -892,7 +1320,7 @@ declare class Alineo {
|
|
|
892
1320
|
* every caller up the chain -- `Alineo.prompt()`, `collectReply()`, `alineo fork --prompt` --
|
|
893
1321
|
* forever, with no error and no partial output.
|
|
894
1322
|
*/
|
|
895
|
-
declare class PromptTimeoutError extends WorkflowError {
|
|
1323
|
+
export declare class PromptTimeoutError extends WorkflowError {
|
|
896
1324
|
readonly timeoutMs: number;
|
|
897
1325
|
readonly bridgeUrl: string;
|
|
898
1326
|
constructor(timeoutMs: number, bridgeUrl: string);
|
|
@@ -904,9 +1332,9 @@ declare class PromptTimeoutError extends WorkflowError {
|
|
|
904
1332
|
* multi-line summary (via `z.prettifyError()`) suitable for printing as-is; `.issues` is for
|
|
905
1333
|
* callers that want to handle failures programmatically (e.g. highlight specific fields in a UI).
|
|
906
1334
|
*/
|
|
907
|
-
declare class AgentSpecValidationError extends WorkflowError {
|
|
1335
|
+
export declare class AgentSpecValidationError extends WorkflowError {
|
|
908
1336
|
readonly issues: readonly Pick<z.core.$ZodIssue, "path" | "message" | "code">[];
|
|
909
1337
|
constructor(message: string, issues: readonly Pick<z.core.$ZodIssue, "path" | "message" | "code">[]);
|
|
910
1338
|
}
|
|
911
1339
|
//#endregion
|
|
912
|
-
export {
|
|
1340
|
+
export type { AgentEvent, AgentSnapshotRecord, AgentSpec, AgentStream, CompactResult, EgressApprovalGateOptions, EgressDecision, EgressRequest, EgressRequestHandler, HeldCredential, PendingPermission, PermissionAction, PermissionDecision, PermissionHandler, PermissionMode, PermissionPolicy, PermissionRequest, PermissionRule, PiMessage, PiModel, PiSessionState, PiSlashCommand, PromptStream, SessionStats, SetupStep, ThinkingLevel };
|