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