@alineo-labs/schema 0.0.0-stage → 0.3.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/README.md +126 -3
- package/dist/agent-spec-BiNRKcYr.mjs +1190 -0
- package/dist/agent-spec-C7UBd_R2.d.mts +576 -0
- package/dist/alineod.d.mts +670 -0
- package/dist/alineod.mjs +310 -0
- package/dist/index-BnrIUYdM.d.mts +507 -0
- package/dist/index.d.mts +3 -0
- package/dist/index.mjs +185 -0
- package/dist/rolldown-runtime-D7D4PA-g.mjs +13 -0
- package/dist/types.d.mts +2 -0
- package/dist/types.mjs +1 -0
- package/package.json +47 -4
|
@@ -0,0 +1,576 @@
|
|
|
1
|
+
import * as z$1 from "zod";
|
|
2
|
+
//#region src/vocabulary.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* The two lists every alineo surface derives its names from.
|
|
5
|
+
*
|
|
6
|
+
* One user meets the CLI, the SDK, the daemon's HTTP API, the MCP tools and the event
|
|
7
|
+
* stream. Each of those is free to pick its own spelling, and historically each did — which
|
|
8
|
+
* is how `spawn` came to mean "create a root agent" in the CLI and "create a child" in the
|
|
9
|
+
* SDK, and how `fork` came to mean three different operations.
|
|
10
|
+
*
|
|
11
|
+
* Making the vocabulary *data* is what lets CI fail a name rather than a reviewer catch it.
|
|
12
|
+
* The checks that consume these lists land with the surfaces they police (CLI and help
|
|
13
|
+
* strings, MCP tools and HTTP routes, event types); this module is only the source of truth.
|
|
14
|
+
*/
|
|
15
|
+
/**
|
|
16
|
+
* The things alineo acts on. A name's first segment is one of these.
|
|
17
|
+
*
|
|
18
|
+
* Ordered by layer rather than alphabetically — control plane, then the agent loop, then the
|
|
19
|
+
* substrate, then the operator-facing objects — because that is how the surfaces group.
|
|
20
|
+
*
|
|
21
|
+
* `event`, `result` and `transcript` are the records a run leaves behind. They joined the list
|
|
22
|
+
* when the HTTP and MCP checks landed and found them already on the wire
|
|
23
|
+
* (`GET /agents/:id/transcript`, `GET /runs/:id/events`): they were vocabulary in use, just not
|
|
24
|
+
* written down.
|
|
25
|
+
*
|
|
26
|
+
* `provider` joined with the `SandboxProvider` interface: the thing a sandbox runs on and is
|
|
27
|
+
* owned by (`sandbox.created` records which one). No event or route is named after it yet; it
|
|
28
|
+
* is registered so the first one is not a surprise.
|
|
29
|
+
*
|
|
30
|
+
* `memory` and `fact` joined with alineod's memory routes (`GET /agents/:id/memory`,
|
|
31
|
+
* `POST /agents/:id/facts`): `memory` is an agent's durable working memory, `fact` one item of
|
|
32
|
+
* its semantic memory.
|
|
33
|
+
*/
|
|
34
|
+
declare const SUBJECTS: readonly ["run", "agent", "sandbox", "provider", "session", "turn", "message", "tool", "handle", "wait", "inbox", "notify", "budget", "exec", "egress", "credential", "permission", "workflow", "step", "compaction", "retry", "extension", "queue", "spec", "environment", "event", "result", "transcript", "memory", "fact"];
|
|
35
|
+
/**
|
|
36
|
+
* What alineo does to a subject. A name's second segment is one of these — in the imperative
|
|
37
|
+
* for a command, method, route or tool, and in the past tense for an event (`agent.spawned`).
|
|
38
|
+
*
|
|
39
|
+
* `branchSession` and `duplicateSession` are camelCase because they exist only as SDK
|
|
40
|
+
* methods; no route, tool or event uses them. They carry `Session` in the name on purpose:
|
|
41
|
+
* unqualified `branch`/`duplicate` read like sandbox operations, and they are not — both stay
|
|
42
|
+
* inside one container and only touch the harness conversation.
|
|
43
|
+
*/
|
|
44
|
+
declare const VERBS: readonly ["start", "spawn", "stop", "pause", "resume", "reattach", "attach", "prompt", "steer", "await", "checkpoint", "fork", "branchSession", "duplicateSession", "add", "list", "remove", "get", "watch", "init", "deliver"];
|
|
45
|
+
type Subject = (typeof SUBJECTS)[number];
|
|
46
|
+
type Verb = (typeof VERBS)[number];
|
|
47
|
+
declare function isSubject(value: string): value is Subject;
|
|
48
|
+
declare function isVerb(value: string): value is Verb;
|
|
49
|
+
/**
|
|
50
|
+
* Split a two-segment name into its subject and verb, or return `null` if either half is not
|
|
51
|
+
* in the lists above.
|
|
52
|
+
*
|
|
53
|
+
* The separator is what distinguishes the surfaces: `_` for an MCP tool (`agent_spawn`), `.`
|
|
54
|
+
* for an event type (`agent.spawned`). Only the first separator splits, so a multi-word verb
|
|
55
|
+
* stays intact.
|
|
56
|
+
*
|
|
57
|
+
* Note for the event check (Track 1): event verbs are past tense and so will not be in
|
|
58
|
+
* `VERBS` literally — `agent.spawned`, not `agent.spawn`. That check needs its own tense
|
|
59
|
+
* rule on top of `isSubject`; this helper is exact-match only.
|
|
60
|
+
*/
|
|
61
|
+
declare function parseName(name: string, separator: "_" | "."): {
|
|
62
|
+
subject: Subject;
|
|
63
|
+
verb: Verb;
|
|
64
|
+
} | null;
|
|
65
|
+
//#endregion
|
|
66
|
+
//#region src/envelope.d.ts
|
|
67
|
+
/**
|
|
68
|
+
* The one record shape an event takes, whichever layer emitted it.
|
|
69
|
+
*
|
|
70
|
+
* Today the same idea is written three ways: the SDK's `LedgerEntry` (keyed by name +
|
|
71
|
+
* sandboxId + stepIndex, ordered by timestamp), alineod's ledger row (`seq`, `run_id`,
|
|
72
|
+
* `agent_id`, `ts`, `event`, `payload`), and the harness's bare `{ type, ...fields }` stream.
|
|
73
|
+
* A consumer reading a run end to end has to know all three.
|
|
74
|
+
*
|
|
75
|
+
* This is mostly a formalisation rather than an invention — alineod's row is already five of
|
|
76
|
+
* these eight fields.
|
|
77
|
+
*/
|
|
78
|
+
/** A pointer back to a persisted event, for `causedBy`. */
|
|
79
|
+
interface EventRef {
|
|
80
|
+
/** The aggregate the referenced event was persisted under — a run, or a sandbox session. */
|
|
81
|
+
aggregate: string;
|
|
82
|
+
seq: number;
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* What a writer stamps on an event once it is persisted.
|
|
86
|
+
*
|
|
87
|
+
* Absent on a stream-only event, and absent on a durable one until it has actually been
|
|
88
|
+
* written — which is the distinction `BusMessage.id` already draws in alineod today ("the
|
|
89
|
+
* ledger `seq` for persisted events, absent otherwise").
|
|
90
|
+
*/
|
|
91
|
+
interface DurableRef {
|
|
92
|
+
/**
|
|
93
|
+
* What the `seq` counts within: the run for alineod, the sandbox session for the SDK.
|
|
94
|
+
*
|
|
95
|
+
* Scoped rather than global on purpose. A monotone sequence needs a single writer, and
|
|
96
|
+
* there are two here — alineod's `bun:sqlite` and the SDK's storage adapter, in different
|
|
97
|
+
* processes. A top-level `seq` would be a promise neither could keep.
|
|
98
|
+
*/
|
|
99
|
+
aggregate: string;
|
|
100
|
+
/** Monotone within `aggregate`. Also what SSE hands back as `Last-Event-ID`. */
|
|
101
|
+
seq: number;
|
|
102
|
+
/** Version of this `type`'s `data` shape, from its definition. */
|
|
103
|
+
version: number;
|
|
104
|
+
}
|
|
105
|
+
interface LedgerEnvelope<T extends string = string, D = unknown> {
|
|
106
|
+
/** Envelope version. Bumped only if these outer fields change, never for a `data` change. */
|
|
107
|
+
v: 1;
|
|
108
|
+
/** Epoch ms. */
|
|
109
|
+
ts: number;
|
|
110
|
+
/** `<subject>.<past-tense verb>` — `agent.spawned`, `exec.completed`. */
|
|
111
|
+
type: T;
|
|
112
|
+
runId?: string;
|
|
113
|
+
agentId?: string;
|
|
114
|
+
/**
|
|
115
|
+
* Reserved. Nothing generates turn ids yet; the field ships unpopulated because adding a
|
|
116
|
+
* field to a persisted envelope later costs a `v` bump and a migration, and adding it now
|
|
117
|
+
* costs one optional property.
|
|
118
|
+
*/
|
|
119
|
+
turnId?: string;
|
|
120
|
+
/** The decision this fact followed from, where the emitter knows it. */
|
|
121
|
+
causedBy?: EventRef;
|
|
122
|
+
/** Present once persisted. See `DurableRef`. */
|
|
123
|
+
durable?: DurableRef;
|
|
124
|
+
data: D;
|
|
125
|
+
}
|
|
126
|
+
/** An envelope that has been persisted, so `durable` is known to be there. */
|
|
127
|
+
type PersistedEnvelope<T extends string = string, D = unknown> = LedgerEnvelope<T, D> & {
|
|
128
|
+
durable: DurableRef;
|
|
129
|
+
};
|
|
130
|
+
declare function isPersisted<T extends string, D>(envelope: LedgerEnvelope<T, D>): envelope is PersistedEnvelope<T, D>;
|
|
131
|
+
//#endregion
|
|
132
|
+
//#region src/permissions.d.ts
|
|
133
|
+
/**
|
|
134
|
+
* Permission-policy shapes.
|
|
135
|
+
*
|
|
136
|
+
* Types only — `normalizePermissions()`, `evaluatePolicy()` and the safe-command lists stay
|
|
137
|
+
* in `@alineo-labs/agent`, because they are behaviour and this package has none. The split is
|
|
138
|
+
* the rule everywhere here: if it does nothing at runtime, it lives in the schema.
|
|
139
|
+
*
|
|
140
|
+
* `@alineo-labs/agent` re-exports all of these, so existing imports keep working.
|
|
141
|
+
*/
|
|
142
|
+
type PermissionMode = "auto" | "ask" | "readonly";
|
|
143
|
+
/**
|
|
144
|
+
* What happens when a rule (or the policy default) matches a tool call:
|
|
145
|
+
* - `allow` — run it, no prompt
|
|
146
|
+
* - `ask` — pause, surface a `permission_request`, wait for a human decision
|
|
147
|
+
* - `deny` — refuse, with a reason the model reads and can adjust to
|
|
148
|
+
* - `rate_limit` — allow up to `limit.count` matching calls per `limit.windowMs`, then deny
|
|
149
|
+
* - `classify` — best-effort read-vs-write triage of the call (today: `bash`/`powershell`
|
|
150
|
+
* only, splitting on `&&`/`||`/`;`/`|`/newline and checking each sub-command against a
|
|
151
|
+
* built-in safe-reader list). All sub-commands look read-only → `allow`; anything
|
|
152
|
+
* unrecognised or a redirect/`sudo`/`rm` → falls through to `ask`. For any other tool,
|
|
153
|
+
* `classify` is treated as `ask`.
|
|
154
|
+
*/
|
|
155
|
+
type PermissionAction = "allow" | "ask" | "deny" | "rate_limit" | "classify";
|
|
156
|
+
interface PermissionRule {
|
|
157
|
+
/** Tool name or glob (`*` = any run of chars, `?` = one), e.g. `"bash"`, `"write"`, `"*"`. */
|
|
158
|
+
tool: string;
|
|
159
|
+
/**
|
|
160
|
+
* Glob matched against a tool-specific target string, extracted from Pi's typed
|
|
161
|
+
* `event.input` — the command for `bash`, the path for `read`/`write`/`edit`, the query
|
|
162
|
+
* for `grep`. Anchored: `"git *"` matches `"git status"` but not `"x && git status"` —
|
|
163
|
+
* use `"*git*"` for a substring match. Omit to match any call to `tool`.
|
|
164
|
+
*/
|
|
165
|
+
pattern?: string;
|
|
166
|
+
action: PermissionAction;
|
|
167
|
+
/** `rate_limit` only: the ceiling and rolling window. */
|
|
168
|
+
limit?: {
|
|
169
|
+
count: number;
|
|
170
|
+
windowMs: number;
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
interface PermissionPolicy {
|
|
174
|
+
/** Action when no rule matches. Default `"ask"`. */
|
|
175
|
+
default?: PermissionAction;
|
|
176
|
+
/** Evaluated in order; the **last** matching rule wins (opencode semantics). */
|
|
177
|
+
rules?: PermissionRule[];
|
|
178
|
+
/**
|
|
179
|
+
* Tools the agent may never call. The gate strips these from the model's tool list at
|
|
180
|
+
* session start (via Pi's `setActiveTools`) so the model never attempts them, and also
|
|
181
|
+
* keeps an unconditional `deny` as a backstop for any tool registered after startup
|
|
182
|
+
* (SDK / MCP tools).
|
|
183
|
+
*/
|
|
184
|
+
disabledTools?: string[];
|
|
185
|
+
/**
|
|
186
|
+
* If set, the ONLY tools the model may see — the gate calls Pi's `setActiveTools` with
|
|
187
|
+
* this list at session start. `"readonly"` mode expands to this (the read-only tools).
|
|
188
|
+
* Distinct from `disabledTools` (a denylist); this is an allowlist for the toolset.
|
|
189
|
+
*/
|
|
190
|
+
restrictToTools?: string[];
|
|
191
|
+
}
|
|
192
|
+
/** The fully-defaulted shape written to `/etc/alineo-pi.json` and read by the gate. */
|
|
193
|
+
interface NormalizedPermissionPolicy {
|
|
194
|
+
default: PermissionAction;
|
|
195
|
+
rules: PermissionRule[];
|
|
196
|
+
disabledTools: string[];
|
|
197
|
+
/** Empty = no restriction. Non-empty = the exact set of tools the model may see. */
|
|
198
|
+
restrictToTools: string[];
|
|
199
|
+
}
|
|
200
|
+
//#endregion
|
|
201
|
+
//#region src/agent-spec.d.ts
|
|
202
|
+
/**
|
|
203
|
+
* Opt-in alternative to a plain `AgentSpec.env` string value — instead of interpolating
|
|
204
|
+
* straight into the container's environment, `credential` is registered with the sandbox's
|
|
205
|
+
* `CredentialBroker` via `sb.credentials.set()` and injected transparently into outbound
|
|
206
|
+
* requests to `host`. The sandbox process never sees the resolved value at all. Requires the
|
|
207
|
+
* agent's sandbox to be created with `credentialProxy: true` — `Alineo.start()`/`.resume()`/
|
|
208
|
+
* `.spawn()` set this automatically whenever `env` contains at least one binding like this.
|
|
209
|
+
*/
|
|
210
|
+
interface CredentialEnvBinding {
|
|
211
|
+
/** Host env var reference to resolve the real value from, e.g. `"${OPENAI_API_KEY}"`. */
|
|
212
|
+
credential: string;
|
|
213
|
+
/** FQDN or wildcard domain this credential is injected for. */
|
|
214
|
+
host: string;
|
|
215
|
+
/** Narrows the binding to requests whose path starts with this prefix. */
|
|
216
|
+
pathPrefix?: string;
|
|
217
|
+
/**
|
|
218
|
+
* How the credential reaches the request. `header` adds `name: <value>`. `substitution`
|
|
219
|
+
* replaces every literal `placeholder` in the listed request surfaces with the value — the
|
|
220
|
+
* request must already contain `placeholder` verbatim (put it in a base URL, say). Mirrors
|
|
221
|
+
* `@alineo-labs/core`'s `CredentialInjection`; `packages/agent/test/schema.test.ts` is the
|
|
222
|
+
* drift check.
|
|
223
|
+
*/
|
|
224
|
+
injection: {
|
|
225
|
+
type: "header";
|
|
226
|
+
name: string;
|
|
227
|
+
} | {
|
|
228
|
+
type: "substitution";
|
|
229
|
+
placeholder: string;
|
|
230
|
+
in: Array<"path" | "query" | "header" | "body">;
|
|
231
|
+
};
|
|
232
|
+
/**
|
|
233
|
+
* `"hold"` gates outbound egress to `host` behind a human decision: the agent's sandbox
|
|
234
|
+
* starts with `host` denied at the egress sidecar, the first request to it pauses and
|
|
235
|
+
* raises an approval request, and the host is allowed only once someone approves. Requires
|
|
236
|
+
* an `onEgressRequest` handler on `Alineo.start()`. Omit for the default (the host is
|
|
237
|
+
* reachable as soon as the credential is bound).
|
|
238
|
+
*/
|
|
239
|
+
approval?: "hold";
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* A single named setup step run inside the sandbox after Pi CLI install,
|
|
243
|
+
* before the snapshot is taken. The step is a bash shell command.
|
|
244
|
+
*/
|
|
245
|
+
interface SetupStep {
|
|
246
|
+
/** Human-readable label shown in logs and included in the setup hash. */
|
|
247
|
+
name: string;
|
|
248
|
+
/** Shell command to run (bash). */
|
|
249
|
+
run: string;
|
|
250
|
+
/** If set, the command runs as `cd <cwd> && <run>`. */
|
|
251
|
+
cwd?: string;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* JSON spec for an agent — typically loaded from an `agent.json` file on disk.
|
|
255
|
+
* Pass it to `Alineo.start(spec)` — read it from disk yourself first (e.g.
|
|
256
|
+
* `await Bun.file(path).json()`) if it's not already an in-memory object.
|
|
257
|
+
*
|
|
258
|
+
* Environment variable references in `env` values are interpolated from
|
|
259
|
+
* `process.env` at load time: `"${MY_API_KEY}"` → `process.env.MY_API_KEY`.
|
|
260
|
+
*/
|
|
261
|
+
interface AgentSpec {
|
|
262
|
+
$schema?: string;
|
|
263
|
+
/** Unique identifier for this agent. Used as the sandbox session name. */
|
|
264
|
+
name: string;
|
|
265
|
+
/** Human-readable display name. */
|
|
266
|
+
title?: string;
|
|
267
|
+
description?: string;
|
|
268
|
+
author?: string;
|
|
269
|
+
categories?: string[];
|
|
270
|
+
/**
|
|
271
|
+
* Agent-loop driver to run inside the sandbox: `"pi"`, `"claude-code"` or `"codex"`.
|
|
272
|
+
*
|
|
273
|
+
* Not `cli`: that said the driver *is* a CLI, which is true of Pi and accidental in
|
|
274
|
+
* general. `claude-code` runs through the Claude Agent SDK, so `cli: "claude-code"` would
|
|
275
|
+
* have read as a category error.
|
|
276
|
+
*/
|
|
277
|
+
harness: "pi" | "claude-code" | "codex";
|
|
278
|
+
/**
|
|
279
|
+
* npm version specifier for the harness, e.g. `"1.2.3"`, `"^1.2.0"`, or a
|
|
280
|
+
* dist-tag like `"latest"`. Passed directly to
|
|
281
|
+
* `npm install -g <harness package>@<harnessVersion>`: Pi's package for `"pi"`, the Claude
|
|
282
|
+
* Agent SDK for `"claude-code"`, `@openai/codex` for `"codex"`. When
|
|
283
|
+
* omitted, `install()` runs the bare package name and npm resolves
|
|
284
|
+
* whatever it considers latest. Included in the setup-hash cache key, so
|
|
285
|
+
* changing it forces a fresh snapshot rebuild.
|
|
286
|
+
*/
|
|
287
|
+
harnessVersion?: string;
|
|
288
|
+
/**
|
|
289
|
+
* AI provider passed to the CLI via `--provider`. For Pi with a direct Google
|
|
290
|
+
* API key, omit this (Pi defaults to the Google Generative AI endpoint).
|
|
291
|
+
*/
|
|
292
|
+
provider?: string;
|
|
293
|
+
/**
|
|
294
|
+
* Model ID passed to the CLI via `--model`. **Required.**
|
|
295
|
+
*
|
|
296
|
+
* This is the model the agent actually runs on, so a spec has to name it. When it was
|
|
297
|
+
* optional the agent silently inherited the harness's own default, which meant a run's
|
|
298
|
+
* results couldn't be attributed to a model after the fact — the same class of problem as
|
|
299
|
+
* a result that reports success without having done the work.
|
|
300
|
+
*
|
|
301
|
+
* For Pi 0.80.x with a free Google AI Studio key, use `"gemini-flash-latest"`
|
|
302
|
+
* (Pi's alias for gemini-3.5-flash via the direct Google Generative AI API).
|
|
303
|
+
*/
|
|
304
|
+
model: string;
|
|
305
|
+
/**
|
|
306
|
+
* APT packages to install in the sandbox before starting the CLI.
|
|
307
|
+
* Example: `["python3", "git"]`. `nodejs_22` and `nodejs` are silently ignored
|
|
308
|
+
* since the base image is `node:22`.
|
|
309
|
+
*/
|
|
310
|
+
packages?: string[];
|
|
311
|
+
/**
|
|
312
|
+
* Environment variables available inside the sandbox.
|
|
313
|
+
* Values may reference host env vars: `{ GEMINI_API_KEY: "${GEMINI_API_KEY}" }`.
|
|
314
|
+
*
|
|
315
|
+
* A value can instead be a `CredentialEnvBinding` to opt that one key out of plain env-var
|
|
316
|
+
* interpolation entirely — the key never becomes a container env var; its value is injected
|
|
317
|
+
* transparently into matching outbound requests instead. See `CredentialEnvBinding`.
|
|
318
|
+
*/
|
|
319
|
+
env?: Record<string, string | CredentialEnvBinding>;
|
|
320
|
+
/**
|
|
321
|
+
* CPU/memory/GPU resource limits for the sandbox container.
|
|
322
|
+
* Falls back to defaults in `alineo.config.json` if omitted.
|
|
323
|
+
*/
|
|
324
|
+
resources?: {
|
|
325
|
+
cpu: string;
|
|
326
|
+
memory: string;
|
|
327
|
+
gpu?: string;
|
|
328
|
+
};
|
|
329
|
+
/** Not read anywhere in `alineo`; has no effect on the sandbox. */
|
|
330
|
+
metadata?: Record<string, string>;
|
|
331
|
+
/**
|
|
332
|
+
* Not read by `alineo` itself — used by `alineo add`, which fetches
|
|
333
|
+
* and saves each dependency spec first, depth-first.
|
|
334
|
+
*/
|
|
335
|
+
registryDependencies?: string[];
|
|
336
|
+
/**
|
|
337
|
+
* Setup steps run inside the sandbox after Pi CLI install, before the snapshot.
|
|
338
|
+
* Baked into the snapshot — any change to a step invalidates the cache automatically.
|
|
339
|
+
* Example: create directories, write seed files, install project dependencies.
|
|
340
|
+
*/
|
|
341
|
+
setup?: SetupStep[];
|
|
342
|
+
/**
|
|
343
|
+
* Remaining budget for `Alineo.spawn()` calls made from inside this agent's sandbox.
|
|
344
|
+
* Translated by `Alineo.start()`/`Alineo.resume()` into the `ALINEO_SPAWN_DEPTH` env var.
|
|
345
|
+
* `Alineo.spawn()` reads that value, refuses unless it's a positive integer, and
|
|
346
|
+
* force-injects `value - 1` into the spawned child — a tamper-resistant counter,
|
|
347
|
+
* not something a spec or the model can hand-propagate. Omit to disable spawning
|
|
348
|
+
* entirely (the default — most agents never need it).
|
|
349
|
+
*/
|
|
350
|
+
spawnDepth?: number;
|
|
351
|
+
/**
|
|
352
|
+
* Remaining budget for total agents this lineage may spawn — a resource
|
|
353
|
+
* ceiling, distinct from `spawnDepth`'s nesting-depth limit. Translated by
|
|
354
|
+
* `Alineo.start()`/`Alineo.resume()` into the `ALINEO_MAX_AGENTS` env var and
|
|
355
|
+
* force-decremented into each spawned child, the same tamper-resistant
|
|
356
|
+
* pattern as `spawnDepth`. Unlike `spawnDepth`, omitting this means
|
|
357
|
+
* "uncapped" for this dimension, not "spawning disabled" — `spawnDepth`
|
|
358
|
+
* alone still gates whether spawning is allowed at all. Enforced
|
|
359
|
+
* per-lineage only: sibling branches spawned in parallel don't share or
|
|
360
|
+
* coordinate this budget with each other.
|
|
361
|
+
*/
|
|
362
|
+
maxAgents?: number;
|
|
363
|
+
/**
|
|
364
|
+
* Durable team identity for this agent's `.resourceRef` — see `@alineo-labs/memory`'s
|
|
365
|
+
* `ResourceRef.teamId`. Unset by default (unlike `resourceId`, which always gets
|
|
366
|
+
* `spec.name` as its own default) — most agents aren't tied to a team-scoped memory.
|
|
367
|
+
* `Alineo.start()`/`.resume()` also thread this into `SandboxOptions.teamId`/
|
|
368
|
+
* `RestoreSnapshotOptions.teamId` so it stays consistent with the ledger, not just
|
|
369
|
+
* `.resourceRef` — otherwise a team-scoped agent's own episodic history would be
|
|
370
|
+
* unreachable through its own `resourceRef`, since `episodicRecall()` enforces `teamId`
|
|
371
|
+
* strictly. `Alineo.spawn()` passes `SandboxHandle.fork()`'s `resourceId`/`teamId` override
|
|
372
|
+
* (see its own doc comment) so a spawned child's ledger record matches its
|
|
373
|
+
* `.resourceRef` too, rather than silently inheriting the parent's.
|
|
374
|
+
*/
|
|
375
|
+
teamId?: string;
|
|
376
|
+
/**
|
|
377
|
+
* Durable resource identity for this agent's `.resourceRef` — see `@alineo-labs/memory`'s
|
|
378
|
+
* `ResourceRef.resourceId`. Defaults to `spec.name` when unset, same as the implicit
|
|
379
|
+
* behavior before this field existed.
|
|
380
|
+
*
|
|
381
|
+
* Exists as its own field, separate from `name`, specifically for `Alineo.spawn()`: a
|
|
382
|
+
* spawned child's `.name` is overwritten to the forked sandbox's auto-generated ledger name
|
|
383
|
+
* (`fork-<parent>-<id>`, used for `alineo agents` display and future fork labeling) — not
|
|
384
|
+
* `childSpec.name`. Without a separate `resourceId` field, a spawned child's memory scope
|
|
385
|
+
* would silently become that auto-generated name instead of the identity the spec author
|
|
386
|
+
* actually declared. `Alineo.spawn()` freezes this to `childSpec.resourceId ?? childSpec.name`
|
|
387
|
+
* before the rename happens, so a spawned child's memory scope is stable and predictable
|
|
388
|
+
* regardless of what the ledger ends up calling the forked sandbox.
|
|
389
|
+
*/
|
|
390
|
+
resourceId?: string;
|
|
391
|
+
/**
|
|
392
|
+
* Human-in-the-loop tool-call policy, enforced by a bundled Pi extension that runs on
|
|
393
|
+
* every tool call before it executes. Either a mode shorthand (`"auto"` — the default,
|
|
394
|
+
* never ask; `"ask"` — ask before every call; `"readonly"` — auto-allow reads, ask before
|
|
395
|
+
* writes/exec) or a full `PermissionPolicy` with ordered per-tool / per-pattern rules
|
|
396
|
+
* (last match wins). When set to anything other than `"auto"`, a `permission_request`
|
|
397
|
+
* event is emitted on the agent stream for each gated call; resolve it with
|
|
398
|
+
* `agent.resolvePermission(requestId, decision)`.
|
|
399
|
+
*/
|
|
400
|
+
permissions?: PermissionMode | PermissionPolicy;
|
|
401
|
+
/**
|
|
402
|
+
* Policy for a turn that didn't finish successfully — a model/tool failure (an upstream API
|
|
403
|
+
* error ending the turn) or alineod restarting mid-turn, unified under one field rather than
|
|
404
|
+
* two separate half-answers to the same question. `"fail"` (the default — unchanged from
|
|
405
|
+
* behavior before this field existed) settles the turn failed immediately, no hold. `"ask"`
|
|
406
|
+
* holds the agent — state `"blocked"` — until an operator resolves it: `alineo prompt` to
|
|
407
|
+
* retry (optionally with corrective text), `alineo stop` to give up. `"retry"` automatically
|
|
408
|
+
* re-prompts up to `maxRetries` times before falling back to an `"ask"`-style hold. Supervision
|
|
409
|
+
* is opt-in: every spec written before this field existed keeps settling failed immediately,
|
|
410
|
+
* and a turn can have real side effects (a sent email, a `git push`), so silent auto-retry is
|
|
411
|
+
* never assumed — a deployment that wants `"ask"` or `"retry"` opts in explicitly.
|
|
412
|
+
*/
|
|
413
|
+
onFailure?: "ask" | "retry" | "fail";
|
|
414
|
+
/** Required in effect when `onFailure` is `"retry"` — how many automatic re-prompts before
|
|
415
|
+
* falling back to `"ask"`. No default: an explicit number is required, not guessed. */
|
|
416
|
+
maxRetries?: number;
|
|
417
|
+
/**
|
|
418
|
+
* Cross-turn circuit breaker, independent of `onFailure`/`maxRetries`: after this many
|
|
419
|
+
* CONSECUTIVE failed turns — however they were triggered, automatic retries or an operator
|
|
420
|
+
* manually re-prompting a blocked agent — the agent is forced to `"blocked"` regardless of
|
|
421
|
+
* what `onFailure` says, so a declared retry budget (or a patient operator) can't turn into an
|
|
422
|
+
* unbounded cost loop. Resets to zero on any turn that succeeds. Default 3.
|
|
423
|
+
*/
|
|
424
|
+
maxConsecutiveFailures?: number;
|
|
425
|
+
/**
|
|
426
|
+
* durability-roadmap M3, 3.2: opt-in turn-level checkpointing — after every turn that ends
|
|
427
|
+
* in `done`, a tarball of the workspace + session file is captured and durably stored, so
|
|
428
|
+
* `Alineo.resume()` can restore from it if the container is later gone entirely (3.3).
|
|
429
|
+
* Unset (the default) matches every spec written before this field existed: no checkpoint is
|
|
430
|
+
* taken, no extra per-turn cost, behavior unchanged. A turn can have real side effects and a
|
|
431
|
+
* checkpoint is extra I/O on every turn, so this is never assumed — a deployment that wants
|
|
432
|
+
* it opts in explicitly, same reasoning as `onFailure`.
|
|
433
|
+
*/
|
|
434
|
+
checkpoint?: boolean;
|
|
435
|
+
}
|
|
436
|
+
/** The harnesses an agent can run on. */
|
|
437
|
+
type HarnessId = "pi" | "claude-code" | "codex";
|
|
438
|
+
/**
|
|
439
|
+
* A harness with its version pinned, as an object. `"pi"` and `{ id: "pi" }` mean the same.
|
|
440
|
+
* `version` is what the top-level `harnessVersion` was.
|
|
441
|
+
*/
|
|
442
|
+
interface HarnessRef {
|
|
443
|
+
id: HarnessId;
|
|
444
|
+
/** npm version specifier for the harness package, e.g. `"1.2.3"` or `"latest"`. */
|
|
445
|
+
version?: string;
|
|
446
|
+
}
|
|
447
|
+
/**
|
|
448
|
+
* A model with the provider that serves it, as an object. `"gpt-5-codex"` and
|
|
449
|
+
* `{ id: "gpt-5-codex" }` mean the same. `provider` is what the top-level `provider` was.
|
|
450
|
+
*/
|
|
451
|
+
interface ModelRef {
|
|
452
|
+
/** For Pi, passed as `--provider`. The other harnesses have one native provider. */
|
|
453
|
+
provider?: string;
|
|
454
|
+
id: string;
|
|
455
|
+
}
|
|
456
|
+
/**
|
|
457
|
+
* What an author may write. Same as {@link AgentSpec}, except `harness` and `model` may each be
|
|
458
|
+
* an object that carries its own version or provider. `validateAgentSpec()` turns this into
|
|
459
|
+
* an `AgentSpec`, which is what the runtime reads.
|
|
460
|
+
*
|
|
461
|
+
* The top-level `provider` and `harnessVersion` still work and are deprecated: they say which
|
|
462
|
+
* harness or model they belong to only by sitting next to it.
|
|
463
|
+
*/
|
|
464
|
+
interface AgentSpecInput extends Omit<AgentSpec, "harness" | "model"> {
|
|
465
|
+
harness: HarnessId | HarnessRef;
|
|
466
|
+
model: string | ModelRef;
|
|
467
|
+
}
|
|
468
|
+
/** Turn an authored spec into the flat shape the runtime reads. Run it on a validated spec. */
|
|
469
|
+
declare function normalizeAgentSpec(input: AgentSpecInput): AgentSpec;
|
|
470
|
+
/** The deprecated top-level fields a spec still uses, and what replaces each. */
|
|
471
|
+
declare function deprecatedSpecFields(input: Pick<AgentSpecInput, "provider" | "harnessVersion">): Array<{
|
|
472
|
+
field: string;
|
|
473
|
+
use: string;
|
|
474
|
+
}>;
|
|
475
|
+
declare const AgentSpecSchema: z$1.ZodObject<{
|
|
476
|
+
$schema: z$1.ZodOptional<z$1.ZodString>;
|
|
477
|
+
name: z$1.ZodString;
|
|
478
|
+
title: z$1.ZodOptional<z$1.ZodString>;
|
|
479
|
+
description: z$1.ZodOptional<z$1.ZodString>;
|
|
480
|
+
author: z$1.ZodOptional<z$1.ZodString>;
|
|
481
|
+
categories: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
|
|
482
|
+
harness: z$1.ZodUnion<readonly [z$1.ZodEnum<{
|
|
483
|
+
pi: "pi";
|
|
484
|
+
"claude-code": "claude-code";
|
|
485
|
+
codex: "codex";
|
|
486
|
+
}>, z$1.ZodObject<{
|
|
487
|
+
id: z$1.ZodEnum<{
|
|
488
|
+
pi: "pi";
|
|
489
|
+
"claude-code": "claude-code";
|
|
490
|
+
codex: "codex";
|
|
491
|
+
}>;
|
|
492
|
+
version: z$1.ZodOptional<z$1.ZodString>;
|
|
493
|
+
}, z$1.core.$strip>]>;
|
|
494
|
+
harnessVersion: z$1.ZodOptional<z$1.ZodString>;
|
|
495
|
+
provider: z$1.ZodOptional<z$1.ZodString>;
|
|
496
|
+
model: z$1.ZodUnion<readonly [z$1.ZodString, z$1.ZodObject<{
|
|
497
|
+
provider: z$1.ZodOptional<z$1.ZodString>;
|
|
498
|
+
id: z$1.ZodString;
|
|
499
|
+
}, z$1.core.$strip>]>;
|
|
500
|
+
packages: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
|
|
501
|
+
env: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodUnion<readonly [z$1.ZodString, z$1.ZodObject<{
|
|
502
|
+
credential: z$1.ZodString;
|
|
503
|
+
host: z$1.ZodString;
|
|
504
|
+
pathPrefix: z$1.ZodOptional<z$1.ZodString>;
|
|
505
|
+
injection: z$1.ZodUnion<readonly [z$1.ZodObject<{
|
|
506
|
+
type: z$1.ZodLiteral<"header">;
|
|
507
|
+
name: z$1.ZodString;
|
|
508
|
+
}, z$1.core.$strip>, z$1.ZodObject<{
|
|
509
|
+
type: z$1.ZodLiteral<"substitution">;
|
|
510
|
+
placeholder: z$1.ZodString;
|
|
511
|
+
in: z$1.ZodArray<z$1.ZodEnum<{
|
|
512
|
+
path: "path";
|
|
513
|
+
header: "header";
|
|
514
|
+
query: "query";
|
|
515
|
+
body: "body";
|
|
516
|
+
}>>;
|
|
517
|
+
}, z$1.core.$strip>]>;
|
|
518
|
+
approval: z$1.ZodOptional<z$1.ZodLiteral<"hold">>;
|
|
519
|
+
}, z$1.core.$loose>]>>>;
|
|
520
|
+
resources: z$1.ZodOptional<z$1.ZodObject<{
|
|
521
|
+
cpu: z$1.ZodString;
|
|
522
|
+
memory: z$1.ZodString;
|
|
523
|
+
gpu: z$1.ZodOptional<z$1.ZodString>;
|
|
524
|
+
}, z$1.core.$strip>>;
|
|
525
|
+
metadata: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
|
|
526
|
+
registryDependencies: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
|
|
527
|
+
setup: z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
|
|
528
|
+
name: z$1.ZodString;
|
|
529
|
+
run: z$1.ZodString;
|
|
530
|
+
cwd: z$1.ZodOptional<z$1.ZodString>;
|
|
531
|
+
}, z$1.core.$loose>>>;
|
|
532
|
+
spawnDepth: z$1.ZodOptional<z$1.ZodNumber>;
|
|
533
|
+
maxAgents: z$1.ZodOptional<z$1.ZodNumber>;
|
|
534
|
+
teamId: z$1.ZodOptional<z$1.ZodString>;
|
|
535
|
+
resourceId: z$1.ZodOptional<z$1.ZodString>;
|
|
536
|
+
permissions: z$1.ZodOptional<z$1.ZodUnion<readonly [z$1.ZodEnum<{
|
|
537
|
+
readonly: "readonly";
|
|
538
|
+
auto: "auto";
|
|
539
|
+
ask: "ask";
|
|
540
|
+
}>, z$1.ZodObject<{
|
|
541
|
+
default: z$1.ZodOptional<z$1.ZodEnum<{
|
|
542
|
+
ask: "ask";
|
|
543
|
+
allow: "allow";
|
|
544
|
+
deny: "deny";
|
|
545
|
+
rate_limit: "rate_limit";
|
|
546
|
+
classify: "classify";
|
|
547
|
+
}>>;
|
|
548
|
+
rules: z$1.ZodOptional<z$1.ZodArray<z$1.ZodObject<{
|
|
549
|
+
tool: z$1.ZodString;
|
|
550
|
+
pattern: z$1.ZodOptional<z$1.ZodString>;
|
|
551
|
+
action: z$1.ZodEnum<{
|
|
552
|
+
ask: "ask";
|
|
553
|
+
allow: "allow";
|
|
554
|
+
deny: "deny";
|
|
555
|
+
rate_limit: "rate_limit";
|
|
556
|
+
classify: "classify";
|
|
557
|
+
}>;
|
|
558
|
+
limit: z$1.ZodOptional<z$1.ZodObject<{
|
|
559
|
+
count: z$1.ZodNumber;
|
|
560
|
+
windowMs: z$1.ZodNumber;
|
|
561
|
+
}, z$1.core.$strip>>;
|
|
562
|
+
}, z$1.core.$loose>>>;
|
|
563
|
+
disabledTools: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
|
|
564
|
+
restrictToTools: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
|
|
565
|
+
}, z$1.core.$loose>]>>;
|
|
566
|
+
onFailure: z$1.ZodOptional<z$1.ZodEnum<{
|
|
567
|
+
ask: "ask";
|
|
568
|
+
retry: "retry";
|
|
569
|
+
fail: "fail";
|
|
570
|
+
}>>;
|
|
571
|
+
maxRetries: z$1.ZodOptional<z$1.ZodNumber>;
|
|
572
|
+
maxConsecutiveFailures: z$1.ZodOptional<z$1.ZodNumber>;
|
|
573
|
+
checkpoint: z$1.ZodOptional<z$1.ZodBoolean>;
|
|
574
|
+
}, z$1.core.$loose>;
|
|
575
|
+
//#endregion
|
|
576
|
+
export { VERBS as C, parseName as D, isVerb as E, Subject as S, isSubject as T, EventRef as _, HarnessId as a, isPersisted as b, SetupStep as c, NormalizedPermissionPolicy as d, PermissionAction as f, DurableRef as g, PermissionRule as h, CredentialEnvBinding as i, deprecatedSpecFields as l, PermissionPolicy as m, AgentSpecInput as n, HarnessRef as o, PermissionMode as p, AgentSpecSchema as r, ModelRef as s, AgentSpec as t, normalizeAgentSpec as u, LedgerEnvelope as v, Verb as w, SUBJECTS as x, PersistedEnvelope as y };
|