@awebai/oats 0.57.1 → 0.59.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/bin/oats.mjs +24 -11
- package/docs/configuration.md +2 -1
- package/docs/desktop-cli-api.md +105 -17
- package/docs/desktop.md +30 -3
- package/docs/execution-targets.md +15 -0
- package/docs/implementation.md +2 -0
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +4 -4
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.58.0.md +107 -0
- package/docs/release-notes/v0.59.0.md +288 -0
- package/docs/servers.md +4 -1
- package/docs/souls-and-instances.md +30 -0
- package/docs/tui.md +653 -117
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +227 -46
- package/lib/read-ahead-worker.mjs +119 -0
- package/lib/read-ahead.mjs +115 -0
- package/lib/retire-state.mjs +33 -0
- package/lib/servers.mjs +9 -1
- package/lib/session-input.mjs +14 -4
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/instance-acts.mjs +23 -8
- package/packages/client/instance-presentation.mjs +3 -2
- package/packages/client/instance-tree.mjs +84 -39
- package/packages/client/lifecycle-confirmation.mjs +9 -3
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/remote-roster.mjs +4 -1
- package/packages/client/retire-in-flight.mjs +65 -0
- package/packages/client/retire-state.mjs +30 -0
- package/packages/client/spawn-apply-cli.mjs +8 -2
- package/packages/client/spawn-apply.mjs +20 -7
- package/packages/client/spawn-preview-cli.mjs +2 -1
- package/packages/client/spawn-preview.mjs +30 -18
- package/packages/record/lib/directory-identity.mjs +14 -0
- package/packages/record/lib/native-history.mjs +6 -5
- package/packages/tui/README.md +23 -10
- package/packages/tui/lib/actions.mjs +63 -5
- package/packages/tui/lib/client.mjs +12 -1
- package/packages/tui/lib/config.mjs +7 -2
- package/packages/tui/lib/main.mjs +315 -82
- package/packages/tui/lib/model.mjs +523 -56
- package/packages/tui/lib/panel.mjs +519 -144
- package/packages/tui/lib/read.mjs +52 -26
- package/packages/tui/lib/store.mjs +908 -65
- package/packages/tui/lib/term/keys.mjs +9 -2
- package/packages/tui/lib/term/text.mjs +4 -0
- package/packages/tui/lib/term/through.mjs +12 -1
- package/packages/tui/lib/views/frame.mjs +394 -95
- package/packages/tui/lib/views/help.mjs +54 -13
- package/packages/tui/lib/views/instances.mjs +43 -25
- package/packages/tui/lib/views/palette.mjs +61 -0
- package/packages/tui/lib/views/souls.mjs +268 -0
- package/packages/tui/lib/views/spawn.mjs +299 -0
- package/packages/tui/lib/views/split.mjs +29 -0
- package/skills/oats-getting-started/SKILL.md +2 -2
package/bin/oats.mjs
CHANGED
|
@@ -104,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
104
104
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
105
105
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
106
106
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
107
|
-
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key"];
|
|
107
|
+
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size"];
|
|
108
108
|
/** Commands `--server <id>` runs on a registered server. */
|
|
109
109
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
110
110
|
const flag = (name) => {
|
|
@@ -1484,16 +1484,24 @@ function sayReadNotices() {
|
|
|
1484
1484
|
for (const notice of readSession?.notices.splice(0) ?? []) process.stderr.write(`oats: warning: ${notice}\n`);
|
|
1485
1485
|
}
|
|
1486
1486
|
/** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
|
|
1487
|
-
* → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`.
|
|
1488
|
-
|
|
1487
|
+
* → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`.
|
|
1488
|
+
* Write verbs refuse it: a writer acting on a reused observation could persist a fact the workspace no
|
|
1489
|
+
* longer holds. A preview-bound spawn apply is the exception: its fence (--expect-decision) binds it to
|
|
1490
|
+
* the decision the operator confirmed, so a reused head applies nothing beyond that decision. */
|
|
1491
|
+
const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, spawn --expect-decision <revision>, trigger poll, and the read forms of teams and soul teams";
|
|
1489
1492
|
function maxAgeRefusal(command, head) {
|
|
1490
1493
|
const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
|
|
1491
|
-
const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
|
|
1494
|
+
const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs and a preview-bound spawn apply reuse observations (${MAX_AGE_READS})`;
|
|
1492
1495
|
if (head.includes("--server")) return "--max-age cannot be combined with --server: observation reuse is local to this machine";
|
|
1493
1496
|
switch (command) {
|
|
1494
1497
|
case "status": case "souls": case "capabilities": case "inspect": return null;
|
|
1495
|
-
// A preview reads (feature spawn-preview-max-age); an apply
|
|
1496
|
-
|
|
1498
|
+
// A preview reads (feature spawn-preview-max-age); an apply only when a confirmed decision binds it
|
|
1499
|
+
// (feature spawn-apply-max-age), with a value as spawn reads it: a bare --expect-decision binds nothing.
|
|
1500
|
+
case "spawn": {
|
|
1501
|
+
const expected = flag("expect-decision");
|
|
1502
|
+
if (head.includes("--preview") || (expected !== undefined && expected !== true)) return null;
|
|
1503
|
+
return "--max-age is not accepted by `oats spawn` without --expect-decision: a spawn apply reuses observations only with --expect-decision <revision>, which binds it to the decision a preview showed";
|
|
1504
|
+
}
|
|
1497
1505
|
case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
|
|
1498
1506
|
case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
|
|
1499
1507
|
// `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
|
|
@@ -2686,8 +2694,8 @@ async function status() {
|
|
|
2686
2694
|
const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
|
|
2687
2695
|
/** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
|
|
2688
2696
|
* `--instance` is refused by a local spawn (with its replacement) but still travels to an older
|
|
2689
|
-
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview
|
|
2690
|
-
* dispatch allow-list (maxAgeRefusal) refuses it
|
|
2697
|
+
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
|
|
2698
|
+
* apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
|
|
2691
2699
|
const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
|
|
2692
2700
|
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
|
|
2693
2701
|
/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
|
|
@@ -4803,7 +4811,8 @@ Usage:
|
|
|
4803
4811
|
instance.json providers.<capability>)
|
|
4804
4812
|
[--preview [--max-age <s>]] decide everything, create nothing; the JSON's
|
|
4805
4813
|
decision binds an apply (--expect-decision <rev>);
|
|
4806
|
-
--max-age reuses recent heads
|
|
4814
|
+
--max-age reuses recent heads, on a preview and
|
|
4815
|
+
on an apply bound by --expect-decision only
|
|
4807
4816
|
oats retire <instance> [--force] retire an instance (window, hooks,
|
|
4808
4817
|
[--self] worktree, home); --self = retire the
|
|
4809
4818
|
[--keep-dir] [--json] CALLING instance: the window dies, then
|
|
@@ -4981,9 +4990,13 @@ Observation reuse (feature observe-max-age):
|
|
|
4981
4990
|
remote again; the JSON
|
|
4982
4991
|
then carries observation { observedAt (the oldest
|
|
4983
4992
|
head used), reused, localRevision (a digest of
|
|
4984
|
-
the local configuration read) }.
|
|
4993
|
+
the local configuration read) }. A spawn apply
|
|
4994
|
+
bound by --expect-decision takes it too (feature
|
|
4995
|
+
spawn-apply-max-age): its decision fence holds,
|
|
4996
|
+
and its JSON carries no observation. Refused
|
|
4985
4997
|
(E_BAD_ARGS) by every other command, an edit form,
|
|
4986
|
-
a spawn apply, and with
|
|
4998
|
+
a spawn apply without --expect-decision, and with
|
|
4999
|
+
--server
|
|
4987
5000
|
|
|
4988
5001
|
Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
|
|
4989
5002
|
}
|
package/docs/configuration.md
CHANGED
|
@@ -611,5 +611,6 @@ the bounded parsed-read cache and the observations `--max-age` reuses; all of
|
|
|
611
611
|
it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
|
|
612
612
|
catalog file. The read verbs (`status`, `workspace status`, `souls`,
|
|
613
613
|
`capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
|
|
614
|
-
`spawn --preview`)
|
|
614
|
+
`spawn --preview`), and a spawn apply bound by `--expect-decision`, take
|
|
615
|
+
`--max-age <seconds>` to reuse a remote head observed that recently
|
|
615
616
|
([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -45,7 +45,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
45
45
|
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
46
|
"server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
|
|
47
47
|
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
|
-
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key"
|
|
48
|
+
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
|
|
49
|
+
"status-retire-state","session-inspect-size"],
|
|
49
50
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
50
51
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
51
52
|
"capabilityShowApi":1}
|
|
@@ -122,6 +123,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
122
123
|
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
123
124
|
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
124
125
|
| `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
|
|
126
|
+
| `session-inspect-size` | `size: { cols, rows }` in cells on `session inspect --json` when `present` is true; absent otherwise. Remote inspect relays the execution host's size ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)) | |
|
|
125
127
|
| `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
|
|
126
128
|
| `lifecycle-kernel-codes` | `oats retire`, `oats instance stop`, `oats session …` and `oats worktree add\|remove` answer kernel codes only (`^E_[A-Z0-9_]+$`), in `error.code` and in the codes inside their results, with one exception: a document with an unsafe mapping key or value is refused under its own name, `unsafe-config-key` or `unsafe-config-value`, by these commands as by every other; `error.details.cause` on an error that has a code which is not a kernel code (`{code, syscall}`) and on a defect of the kernel (`{name}`), and none on a refusal that has no code, which is answered with the command's general code and its message alone ([The envelope](#kernel-codes)); `error.details.reached` on every error of a retire apply once the retire of the home has begun, and its absence before that ([`error.details.reached`](#retire-reached)), OATS 0.52.0. Gate on the probe: a kernel without it can answer one of these commands with a system code (`ENOENT`, `EACCES`), and an absent `reached` there says nothing | |
|
|
127
129
|
| `schedule-run-warnings` | a schedule run's record (`lastRun`, `recentRuns[]`) and a trigger fire's record and `lastRun` carry `warnings?`, the launch answer's warnings, when it had some; OATS 0.52.0 ([schedules and triggers](#schedules-and-triggers)) | |
|
|
@@ -131,6 +133,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
131
133
|
| `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
|
|
132
134
|
| `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
|
|
133
135
|
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
136
|
+
| `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
|
|
137
|
+
| `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
|
|
134
138
|
|
|
135
139
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
136
140
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -308,6 +312,7 @@ it and answer live, without the block.
|
|
|
308
312
|
oats status | workspace status | souls | capabilities | inspect --soul|--home
|
|
309
313
|
| teams | soul teams <soul> … --max-age <seconds> --json
|
|
310
314
|
oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
|
|
315
|
+
oats spawn <soul> … --expect-decision <revision> --max-age <seconds> --json (feature spawn-apply-max-age)
|
|
311
316
|
oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
|
|
312
317
|
oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
|
|
313
318
|
```
|
|
@@ -327,10 +332,13 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
327
332
|
- **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
|
|
328
333
|
preview's `result` gains the same block, so you can say "as of
|
|
329
334
|
`<observedAt>`". The `decision` covers the heads the preview used, reused
|
|
330
|
-
or live: a reused head the member has since moved from makes
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
335
|
+
or live: a reused head the member has since moved from makes an apply
|
|
336
|
+
that observes live refuse `E_DECISION_STALE`, and the apply records the
|
|
337
|
+
head it observed, so the next preview under `--max-age` shows it with a new
|
|
338
|
+
`decision.revision`. The preview-bound apply takes the flag from
|
|
339
|
+
`spawn-apply-max-age` (OATS 0.58.0): with `--expect-decision`, it reuses
|
|
340
|
+
heads as the preview does, and its decision fence is unchanged
|
|
341
|
+
([Apply](#apply)). Its answer carries no block.
|
|
334
342
|
- **`localRevision`:** 24 lowercase hex characters, opaque. It digests every
|
|
335
343
|
piece of local configuration the kernel read for this answer:
|
|
336
344
|
`oats-local.yaml` (and each closer `oats-local.yaml` it looked for and did
|
|
@@ -361,18 +369,25 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
361
369
|
spelling of the same repository (ssh vs https) or for a different ref; its
|
|
362
370
|
commit can no longer be fetched. Each is observed live, as without the flag.
|
|
363
371
|
A live observation that fails is the usual error, never an older head.
|
|
364
|
-
- **Refusals:** every other command,
|
|
365
|
-
`--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`)
|
|
372
|
+
- **Refusals:** every other command, every edit form (`teams add|remove|default`)
|
|
366
373
|
and any `--server`
|
|
367
374
|
invocation refuse the flag before reading or writing anything (the removed
|
|
368
375
|
`soul teams --add|--remove|--default|--clear-default` answer their own
|
|
369
376
|
`E_BAD_ARGS` first), with
|
|
370
377
|
`E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
|
|
371
|
-
verbs reuse observations (status, workspace
|
|
372
|
-
capabilities show, inspect --soul|--home,
|
|
373
|
-
|
|
378
|
+
verbs and a preview-bound spawn apply reuse observations (status, workspace
|
|
379
|
+
status, souls, capabilities, capabilities show, inspect --soul|--home,
|
|
380
|
+
spawn --preview, spawn --expect-decision <revision>, trigger poll, and the
|
|
381
|
+
read forms of teams and soul teams)" and,
|
|
374
382
|
with `--server`, "--max-age cannot be combined with --server: observation
|
|
375
|
-
reuse is local to this machine".
|
|
383
|
+
reuse is local to this machine". A spawn apply without `--expect-decision`
|
|
384
|
+
(or with no value after it) refuses it with `E_BAD_ARGS` "--max-age is not
|
|
385
|
+
accepted by \`oats spawn\` without --expect-decision: a spawn apply reuses
|
|
386
|
+
observations only with --expect-decision <revision>, which binds it to the
|
|
387
|
+
decision a preview showed". Write verbs refuse the flag because a writer
|
|
388
|
+
acting on a reused observation could persist a fact the workspace no longer
|
|
389
|
+
holds; a preview-bound apply is the exception because its fence binds it to
|
|
390
|
+
the decision the operator confirmed.
|
|
376
391
|
A capability command's argv (`oats <namespace> …`) is its provider's: the
|
|
377
392
|
kernel neither reads nor refuses `--max-age` there. The same holds for
|
|
378
393
|
`capture`, `recall`, `setup` and `experimental`, which parse their own argv:
|
|
@@ -2316,10 +2331,11 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2316
2331
|
localRevision}`, shaped exactly as the read verbs' block; without it the
|
|
2317
2332
|
preview is exactly as before, and no other field changes shape.
|
|
2318
2333
|
- `decision.revision` covers the heads the preview used, reused or live.
|
|
2319
|
-
|
|
2320
|
-
reused observation refuses `E_DECISION_STALE`, and the
|
|
2321
|
-
it observed, so re-preview under `--max-age` to get the
|
|
2322
|
-
revision.
|
|
2334
|
+
An apply without `--max-age` (or with `--max-age 0`) observes live: a head
|
|
2335
|
+
that moved since the reused observation refuses `E_DECISION_STALE`, and the
|
|
2336
|
+
apply records what it observed, so re-preview under `--max-age` to get the
|
|
2337
|
+
new head and revision. An apply with `--expect-decision` may reuse heads
|
|
2338
|
+
too (feature `spawn-apply-max-age`, [Apply](#apply)).
|
|
2323
2339
|
|
|
2324
2340
|
**Provider settings.**
|
|
2325
2341
|
- `providers` is the `--provider` map as typed.
|
|
@@ -2363,6 +2379,16 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
|
|
|
2363
2379
|
`E_INSTANCE_NAME_TAKEN` (for `--name`) or `E_PLACEMENT_TAKEN`.
|
|
2364
2380
|
- A refused child spawn appends `child-spawn-refused` to the parent's log (on
|
|
2365
2381
|
apply only).
|
|
2382
|
+
- `--max-age <s>` with `--expect-decision <revision>` (feature
|
|
2383
|
+
`spawn-apply-max-age`, OATS 0.58.0) reuses member heads this machine
|
|
2384
|
+
observed at most `<s>` seconds ago, exactly as the preview does (the same
|
|
2385
|
+
values and fallbacks to a live observation), so an apply right after its
|
|
2386
|
+
preview asks no remote again. The decision is computed from those heads, and
|
|
2387
|
+
one that differs from `<revision>` is `E_DECISION_STALE`, as without the
|
|
2388
|
+
flag. The answer (success, replay, every refusal) has no `observation`
|
|
2389
|
+
block: the preview already gave its "as of".
|
|
2390
|
+
Without `--expect-decision` the flag is `E_BAD_ARGS`
|
|
2391
|
+
([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)).
|
|
2366
2392
|
|
|
2367
2393
|
**Idempotency** (feature `spawn-idempotency-2`): `--idempotency-key <key>`
|
|
2368
2394
|
with `--expect-decision` records the key and decision in `instance.json`.
|
|
@@ -2783,8 +2809,9 @@ its absence.
|
|
|
2783
2809
|
Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
|
|
2784
2810
|
`runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
|
|
2785
2811
|
in the row),
|
|
2786
|
-
`identity` when a provider recorded one, `rollbackIncomplete
|
|
2787
|
-
`retirePending` when present, and the Desktop
|
|
2812
|
+
`identity` when a provider recorded one, `rollbackIncomplete`,
|
|
2813
|
+
`retirePending` and [`retire`](#row-retire) when present, and the Desktop
|
|
2814
|
+
facts below.
|
|
2788
2815
|
- <a id="unreadable-record-row"></a>**A home whose `instance.json` cannot be
|
|
2789
2816
|
read** (OATS 0.52.0) is listed like every other, and one such home never
|
|
2790
2817
|
fails the listing. Its row has the fields of a home with no `instance.json`
|
|
@@ -2823,6 +2850,55 @@ its absence.
|
|
|
2823
2850
|
shell or a retained dead pane keeps, so a row with a claim is checked
|
|
2824
2851
|
against its session (as `oats session inspect` observes it) and reads
|
|
2825
2852
|
`null` unless a harness runs there.
|
|
2853
|
+
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
2854
|
+
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
2855
|
+
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
2856
|
+
`retirePending` keeps its meaning (the self-retire marker is there) and is
|
|
2857
|
+
not replaced. Status only reads: it takes no claim, removes no file and
|
|
2858
|
+
signals no process. `self` is `true` when the self-retire marker
|
|
2859
|
+
(`.oats-retire-pending-<instance>.json`, [souls-and-instances.md](souls-and-instances.md#self-retire-not-completed))
|
|
2860
|
+
is beside the home, whatever the claim says, and `false` for a retire
|
|
2861
|
+
another process runs (an `oats retire` holding the home's claim). The
|
|
2862
|
+
marker is read first:
|
|
2863
|
+
|
|
2864
|
+
| Beside the home | `state` | `self` | `since` |
|
|
2865
|
+
|---|---|---|---|
|
|
2866
|
+
| the marker, and the result file `.oats-retired-<instance>.json` with `ok: false` | `failed`, with `code` and `message` | `true` | the result's `completedAt`, else the marker's `requestedAt` |
|
|
2867
|
+
| the marker, no failed result, its completion process alive | `running` | `true` | the marker's `requestedAt` |
|
|
2868
|
+
| the marker, no failed result, the completion's liveness cannot be read, or the marker names no completion process | `unknown` | `true` | the marker's `requestedAt` |
|
|
2869
|
+
| the marker, no failed result, its completion process gone | `interrupted` | `true` | the marker's `requestedAt` |
|
|
2870
|
+
| a marker that cannot be read as an object | `unknown` | `true` | the marker file's modification time |
|
|
2871
|
+
| no marker; the home's claim held by a retire whose holder is alive | `running` | `false` | the claim's `since` |
|
|
2872
|
+
| no marker; the same, the holder's liveness cannot be read | `unknown` | `false` | the claim's `since` |
|
|
2873
|
+
| no marker; the claim's holder gone, a stop's claim, or no claim | absent | | |
|
|
2874
|
+
|
|
2875
|
+
A result with `ok: true` beside a marker still there reads as no result.
|
|
2876
|
+
`code` is the result's `error.code` when it matches `^E_[A-Z0-9_]+$`, and
|
|
2877
|
+
is left out otherwise (the state stays `failed`); `message` is its
|
|
2878
|
+
`error.message` on one line and cut to a retire's one-line reason (at most
|
|
2879
|
+
2048 UTF-16 code units, a cut ending in `…`), left out when empty: each is
|
|
2880
|
+
a string or absent, never `null`, and only on `failed`. `since` is always
|
|
2881
|
+
there, an instant as `toISOString()` writes it: the time in the table when
|
|
2882
|
+
it is one, else the marker file's modification time (the claim file's for
|
|
2883
|
+
a claim); a `retire` whose time cannot be read at all is not given. A
|
|
2884
|
+
failed retire that owes the home nothing leaves no marker: its row carries
|
|
2885
|
+
no `retire`, and its agent row's `retireFailures[]` holds the outcome, as
|
|
2886
|
+
before. A retire that was killed while it held the claim leaves a claim
|
|
2887
|
+
whose holder is gone, which reads absent.
|
|
2888
|
+
|
|
2889
|
+
**How the clients read it** (`packages/client/retire-state.mjs`): `since`
|
|
2890
|
+
a string, `self` a boolean, `code` an `E_…` code and `message` a string,
|
|
2891
|
+
each optional field absent or a string, never `null`. Any other field is
|
|
2892
|
+
dropped. A value with any field out of this shape is dropped whole, never
|
|
2893
|
+
repaired, and the row reads as if it had none; it never fails the roster.
|
|
2894
|
+
`retirePending` is read on its own and kept as reported. The Desktop and
|
|
2895
|
+
`oats tui` read `running` and `unknown` as **Retiring…**, `failed` as
|
|
2896
|
+
**Retire failed** (its `message` and `code` shown as OATS's words, through
|
|
2897
|
+
the display filter) and `interrupted` as **Retire didn't finish**. A row
|
|
2898
|
+
with `retirePending` and no `retire` (a kernel without the feature) reads
|
|
2899
|
+
**Retiring…**. `rollbackIncomplete` and `spawnInProgress` are read before
|
|
2900
|
+
it. A remote roster row's `retire` is read by the same rule
|
|
2901
|
+
([remote rows](#remote-row-retire)).
|
|
2826
2902
|
- **`modules`** becomes drift rows `{name, from, commit, current, status,
|
|
2827
2903
|
reason?}` when the workspace was read. `status` is `current`, `moved` or
|
|
2828
2904
|
`missing` (`reason`: `capability-absent`, `package-absent`, or the member's
|
|
@@ -2991,6 +3067,18 @@ route target:
|
|
|
2991
3067
|
`producer`) is `null`, and an unknown `reason` or an invalid `message` is
|
|
2992
3068
|
`null` inside a claim that still counts. As on a local row, the host
|
|
2993
3069
|
reports a claim only for a running instance.
|
|
3070
|
+
- <a id="remote-row-retire"></a>**`retire`** (feature `status-retire-state`, OATS 0.59.0) is on a row only
|
|
3071
|
+
when the host's row has the key: a host whose kernel predates the feature,
|
|
3072
|
+
and a saved route the host did not list, carry none. When present it is
|
|
3073
|
+
passed through the [local row's](#row-retire) rule again on this side: a
|
|
3074
|
+
`state` that is not one of `running`, `unknown`, `failed`, `interrupted`, a
|
|
3075
|
+
`since` that is not a `toISOString()` instant, a `self` that is not a
|
|
3076
|
+
boolean, or a value that is not an object drops the key; a `code` that is
|
|
3077
|
+
not a kernel code, a `code` or `message` that is not a string, and a `code`
|
|
3078
|
+
or `message` on a state other than `failed` are left out, and `message` is
|
|
3079
|
+
cut to the same bound. `oats status --server
|
|
3080
|
+
<id> --json` relays the host's answer verbatim, `retire` included, as it
|
|
3081
|
+
does every other field.
|
|
2994
3082
|
- **`addressable`** (0.31): `true` for every row the host reports. Routed
|
|
2995
3083
|
session and lifecycle commands reach it by `--home`, or by name when the
|
|
2996
3084
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
package/docs/desktop.md
CHANGED
|
@@ -227,9 +227,8 @@ a spawn may run for a long time: its roster row reads **Setting up worktree…**
|
|
|
227
227
|
until the worktree is ready, and offers no actions meanwhile. If the spawn was
|
|
228
228
|
interrupted or a capability couldn't set up the worktree, the spawn was rolled
|
|
229
229
|
back, and the notification says that nothing was created. A home whose spawn
|
|
230
|
-
didn't finish its cleanup reads **Spawn didn't finish**, and
|
|
231
|
-
|
|
232
|
-
instance…**, which completes them. A server spawn whose worktree hooks take
|
|
230
|
+
didn't finish its cleanup reads **Spawn didn't finish**, and offers only
|
|
231
|
+
**Retire instance…**, which completes it. A server spawn whose worktree hooks take
|
|
233
232
|
more than about a minute is not yet supported from the Desktop; use the CLI on
|
|
234
233
|
the server. Every dropdown in the app has the
|
|
235
234
|
same themed look, and its open list follows the light or dark theme.
|
|
@@ -257,6 +256,34 @@ With an OATS older than 0.52.0, after an interrupted stop the instance can be
|
|
|
257
256
|
started and then cannot be stopped while `.oats-stop-pending.json` exists in
|
|
258
257
|
its home.
|
|
259
258
|
|
|
259
|
+
**A retire in progress reads Retiring…, never as a failure.** An instance's
|
|
260
|
+
roster row reads **Retiring…** while:
|
|
261
|
+
|
|
262
|
+
- OATS reports its retire running, or cannot tell whether the process
|
|
263
|
+
holding the retire still runs;
|
|
264
|
+
- its OATS does not report a retire's state yet (no `retire` on the row)
|
|
265
|
+
and the instance has a retire pending;
|
|
266
|
+
- the Desktop's own retire of it was sent and the roster has not been read
|
|
267
|
+
since its answer came. A retire that OATS refused, or whose plan had
|
|
268
|
+
changed, runs nothing, and the row reads as the roster says at once.
|
|
269
|
+
|
|
270
|
+
A retiring row offers no Start, Stop, Restart or Open, and no inline
|
|
271
|
+
button. **Retire instance…** stays in the row's menu, after its usual
|
|
272
|
+
confirmation: OATS refuses a second retire while one runs, and when the
|
|
273
|
+
holder can't be read it may be the only way on.
|
|
274
|
+
|
|
275
|
+
When the retire has ended without finishing, the row says so and offers only
|
|
276
|
+
**Retire instance…**, which finishes it:
|
|
277
|
+
|
|
278
|
+
- **Retire failed**: a self-retire's completion recorded an error. Its
|
|
279
|
+
reason is OATS's own message, with its code, shown through the same
|
|
280
|
+
display filter as every other text from OATS (control characters and
|
|
281
|
+
line breaks never reach the screen, a long message is cut, a message that
|
|
282
|
+
looks like a secret is withheld). With a code and no message, the reason
|
|
283
|
+
is OATS's code, shown the same way.
|
|
284
|
+
- **Retire didn't finish**: a scheduled completion is gone and left no
|
|
285
|
+
outcome.
|
|
286
|
+
|
|
260
287
|
## One workspace, several machines
|
|
261
288
|
|
|
262
289
|
The switcher lists each workspace once, however many deployments it has: the
|
|
@@ -349,6 +349,10 @@ than the server's checked one account and launched with another
|
|
|
349
349
|
given the pane's `PATH` as the pane reads it, a relative entry (and an
|
|
350
350
|
empty one) resolved against the pane's working directory, the home.
|
|
351
351
|
The command a refusal names keeps the harness's name as declared.
|
|
352
|
+
The Claude probe (`claude plugin list --json`) sets `DISABLE_TELEMETRY=1`
|
|
353
|
+
for its own run, so Claude skips its telemetry flush at exit: that selects
|
|
354
|
+
no account and changes no answer, and no launch, install step or other
|
|
355
|
+
probe gets it.
|
|
352
356
|
- **The folder-trust check only warns**: `<harness> folder trust: the
|
|
353
357
|
configuration file this launch will read could not be established
|
|
354
358
|
(<why, and what would make it readable>); nothing is said about its
|
|
@@ -1035,6 +1039,17 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1035
1039
|
harness, `shell` for a fallback shell,
|
|
1036
1040
|
`stopped` for an absent or dead terminal, or `not-launched`. An unavailable
|
|
1037
1041
|
backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
|
|
1042
|
+
With feature `session-inspect-size` in `oats version --json`, a present
|
|
1043
|
+
terminal also reports `size: { cols, rows }`: positive integer window width
|
|
1044
|
+
and height in cells. The kernel reads tmux's `window_width` and
|
|
1045
|
+
`window_height` in the same call as the pane identity, so a viewer can open
|
|
1046
|
+
its PTY at the window's current size without constructing a tmux target.
|
|
1047
|
+
Split windows remain refused. `size` is absent when `present` is false,
|
|
1048
|
+
including a retained dead pane. Malformed dimensions are an
|
|
1049
|
+
`E_SESSION_UNAVAILABLE` error containing `invalid tmux pane response`.
|
|
1050
|
+
`session inspect --server <id> --home <home> --json` relays the execution
|
|
1051
|
+
host's size; check that host's feature list before relying on it. This is a
|
|
1052
|
+
snapshot: inspect again to observe a resize.
|
|
1038
1053
|
A home without its session receipt is refused with
|
|
1039
1054
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
|
|
1040
1055
|
spelling that differs from the on-disk one, the path a kernel before 0.49.0
|
package/docs/implementation.md
CHANGED
|
@@ -120,7 +120,9 @@ and the rules its tests pin.
|
|
|
120
120
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
121
121
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
122
122
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
123
|
+
| `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
|
|
123
124
|
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
125
|
+
| `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
|
|
124
126
|
| `servers.mjs` | routing commands to a registered server |
|
|
125
127
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
126
128
|
| `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
|
package/docs/integrations.md
CHANGED
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.2.
|
|
9
|
+
This is the operator guide for **oats.okf 5.2.1** (OATS **>=0.49.0**). Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
25
25
|
```yaml
|
|
26
26
|
# oats-workspace.yaml (excerpt)
|
|
27
27
|
packages:
|
|
28
|
-
oats.okf: v5.2.
|
|
28
|
+
oats.okf: v5.2.1
|
|
29
29
|
defaults:
|
|
30
30
|
knowledge: { oats.okf: { from: package } }
|
|
31
31
|
stores:
|
|
@@ -50,10 +50,10 @@ settings:
|
|
|
50
50
|
|
|
51
51
|
Upgrading from 4.x requires the ordered
|
|
52
52
|
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
53
|
-
just editing a version line. For 5.2.
|
|
53
|
+
just editing a version line. For 5.2.1, OATS >=0.49.0 remains required:
|
|
54
54
|
that kernel first supports the public source-event lookup after retirement.
|
|
55
55
|
|
|
56
|
-
**Upgrade:** pin `oats.okf: v5.2.
|
|
56
|
+
**Upgrade:** pin `oats.okf: v5.2.1` and run `oats sync`. Only new spawns get
|
|
57
57
|
the capability-owned harvest duty, skill and spawn-recorded policy. Existing
|
|
58
58
|
homes keep their copied provider even after a session restart. Deployments
|
|
59
59
|
whose briefings never mentioned harvesting now get knowledge proposals at
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.12.
|
|
13
|
-
| `oats.okf` | `v5.2.
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.12.2` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.28.0` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf: v5.2.
|
|
32
|
+
`packages:` map (`oats.okf: v5.2.1`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.2.
|
|
47
|
+
oats.okf: v5.2.1 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.2.
|
|
51
|
+
- **Bare version** (`v5.2.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.2.
|
|
54
|
+
convention (`v5.2.1` or `oats-framework/v1.12.2`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.12.
|
|
78
|
-
oats.okf: v5.2.
|
|
79
|
-
oats.aweb: v1.
|
|
77
|
+
oats.framework: v1.12.2
|
|
78
|
+
oats.okf: v5.2.1
|
|
79
|
+
oats.aweb: v1.28.0
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.2.1 ✓ (@ 72e989b9)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.
|
|
137
|
+
oats package add oats.aweb v1.28.0 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.2.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.2.1",
|
|
164
|
+
"commit": "72e989b926e8ac1b7b912785beff396d1fc41cbb",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.1", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.2", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.12.
|
|
362
|
-
resolves to tag `oats-framework/v1.12.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.12.2`
|
|
362
|
+
resolves to tag `oats-framework/v1.12.2`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|