@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
package/README.md
CHANGED
|
@@ -1,4 +1,127 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @alineo-labs/schema
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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.
|