@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.
@@ -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 };