@awebai/oats 0.66.0 → 0.68.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 +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
package/docs/implementation.md
CHANGED
|
@@ -80,7 +80,7 @@ and the rules its tests pin.
|
|
|
80
80
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
81
81
|
| `docs/` | the reference pages, schemas, design records and release notes |
|
|
82
82
|
| `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
|
|
83
|
-
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)) |
|
|
83
|
+
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)), and the naming call's isolation proof (`naming-isolation-proof.mjs`, run by hand against real harnesses) |
|
|
84
84
|
| `test/` | the kernel and CLI suites, with their fixtures |
|
|
85
85
|
|
|
86
86
|
## Kernel modules
|
|
@@ -92,11 +92,14 @@ and the rules its tests pin.
|
|
|
92
92
|
| `workspace.mjs` | workspace, membership and soul files; discovery |
|
|
93
93
|
| `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
|
|
94
94
|
| `packages.mjs` | `packages:`, the catalog, `oats sync`, `oats-lock.json` |
|
|
95
|
-
| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally |
|
|
96
|
-
| `materialize.mjs` |
|
|
95
|
+
| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
|
|
96
|
+
| `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
|
|
97
|
+
| `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
|
|
98
|
+
| `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
|
|
97
99
|
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
98
100
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
99
|
-
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul
|
|
101
|
+
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul`, `inspect --soul --instructions` and `--composed-skills` (its `inScratch` reads the scratch home before it is removed, so the two flags share one materialization) |
|
|
102
|
+
| `instance-naming.mjs` | the suggested instance name of `spawn --suggest-name` (a preview's or an apply's) and of `oats instance suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself. Two drivers in `core.mjs`, both reusing it unchanged: `spawnBody`, after the spawn's harness checks, where a suggested name is then placed as `--name` would place it (a preview's call within its preflight budget, an apply's within its own 20 s); and `suggestSpawnName`, for a spawn elsewhere, which resolves the launch configuration and executable the way a spawn here would but places nothing and passes a `taken` that is always false. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
|
|
100
103
|
| `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
|
|
101
104
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
102
105
|
| `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
|
|
@@ -110,8 +113,8 @@ and the rules its tests pin.
|
|
|
110
113
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
|
111
114
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
112
115
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
113
|
-
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
|
|
114
|
-
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write,
|
|
116
|
+
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through |
|
|
117
|
+
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
|
|
115
118
|
| `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
|
|
116
119
|
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire` and `oats instance stop --apply` (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
|
|
117
120
|
| `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, an exact mode, a failed removal reported, a sync) keeps its own code |
|
|
@@ -138,6 +141,43 @@ and the rules its tests pin.
|
|
|
138
141
|
| `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
|
|
139
142
|
| `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings, and the plan `oats update` runs with its line that the Desktop goes first ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
|
|
140
143
|
|
|
144
|
+
An upgrade records a hook's in-flight marker before spawning it. A resumed
|
|
145
|
+
unknown outcome is durably recorded as uncertain before any retry work,
|
|
146
|
+
because the provider may already have changed host state even when no success
|
|
147
|
+
was recorded. Success or uncertainty makes the act forward-only. Only a
|
|
148
|
+
non-zero result observed and recorded in the same invocation, with no prior
|
|
149
|
+
success or uncertainty, permits rollback of composed bytes. An uncertain hook
|
|
150
|
+
is retried idempotently; a later refusal cannot turn that recovery into a
|
|
151
|
+
rollback.
|
|
152
|
+
|
|
153
|
+
Start and upgrade share the `.oats-start.lock` path through exclusive
|
|
154
|
+
acquisition: start uses `mkdir`, while upgrade creates a regular file with
|
|
155
|
+
`wx`. Both treat `EEXIST` as held. Upgrade takes the lifecycle claim before
|
|
156
|
+
reclaiming an interrupted upgrade's regular-file mutex, including an empty
|
|
157
|
+
file left by a killed opener, and never reclaims a directory. Start never
|
|
158
|
+
reclaims this path. Upgrade releases it only after persisting its final
|
|
159
|
+
invocation receipt.
|
|
160
|
+
|
|
161
|
+
Upgrade compares the home with its independent spawn baseline before it
|
|
162
|
+
changes anything there. A dirty home retains the entire baseline byte for
|
|
163
|
+
byte, so older kernels also recover its edits at retire. A clean home updates
|
|
164
|
+
only `homeFingerprint`; work fingerprints, digest versions, exclusions and
|
|
165
|
+
runtime authority remain as recorded. `retirementHomeChanged` and
|
|
166
|
+
`rebaseUpgradeRetirementBaseline` use retirement's existing comparison and
|
|
167
|
+
exclusions, without changing recovery or copy semantics.
|
|
168
|
+
|
|
169
|
+
The fingerprint helpers accept call-scoped `transientHomePaths`: exact
|
|
170
|
+
relative paths, no globs, each an existing regular file. Upgrade projects out
|
|
171
|
+
only `.oats-start.lock`. This is not a permanent exclusion: a later retire
|
|
172
|
+
hashes any leftover mutex as changed home bytes. The completed receipt is
|
|
173
|
+
published before the success event. A same-key retry deduplicates the event
|
|
174
|
+
and removes staging, without repeating adoption or composition.
|
|
175
|
+
|
|
176
|
+
Baseline replacement uses the existing atomic private-file writer. The
|
|
177
|
+
exclusive-create option still refuses an existing baseline. An interrupted replacement leaves a complete
|
|
178
|
+
old or new baseline, preserving the independent session authority required
|
|
179
|
+
to resume forward recovery.
|
|
180
|
+
|
|
141
181
|
The schedule registry stores explicit concurrency caps, leaving the schedule
|
|
142
182
|
cap absent for its effective default of five. `readRegistry()` is a pure,
|
|
143
183
|
bounded atomic-file snapshot: it takes no lock and writes nothing, projecting
|
package/docs/integrations.md
CHANGED
|
@@ -15,7 +15,7 @@ For each soul, OATS resolves zero or one implementation per slot:
|
|
|
15
15
|
| --- | --- | --- |
|
|
16
16
|
| `knowledge` | [knowledge](layers.md#the-knowledge-contract) | `oats.okf` |
|
|
17
17
|
| `messaging` | [communication](layers.md#the-communication-contract) | `oats.aweb` |
|
|
18
|
-
| `tasks` | [tasks](layers.md#the-tasks-contract) | `oats.jira`, `oats.linear` |
|
|
18
|
+
| `tasks` | [tasks](layers.md#the-tasks-contract) | `oats.aweb-tasks`, `oats.jira`, `oats.linear` |
|
|
19
19
|
|
|
20
20
|
A capability becomes an integration by declaring exactly one `layer` in its
|
|
21
21
|
manifest. Capabilities without `layer` compose additively.
|
|
@@ -40,8 +40,8 @@ arrives from.
|
|
|
40
40
|
```yaml
|
|
41
41
|
# oats-workspace.yaml: one default per slot, for every soul
|
|
42
42
|
packages:
|
|
43
|
-
oats.okf: v5.
|
|
44
|
-
oats.aweb: v1.
|
|
43
|
+
oats.okf: v5.3.0
|
|
44
|
+
oats.aweb: v1.31.0
|
|
45
45
|
oats.linear: v1.0.1
|
|
46
46
|
oats.jira: v1.0.1
|
|
47
47
|
defaults:
|
|
@@ -57,7 +57,8 @@ tasks:
|
|
|
57
57
|
# souls/support-triager/soul.yaml: opt out of one slot, replace another
|
|
58
58
|
knowledge: none # empties the slot
|
|
59
59
|
capabilities:
|
|
60
|
-
oats.
|
|
60
|
+
oats.linear: off # removes the tasks default...
|
|
61
|
+
oats.jira: { from: package } # ...so this one fills the slot (two would be E_SLOT_CONFLICT)
|
|
61
62
|
```
|
|
62
63
|
|
|
63
64
|
- A soul's slot key is either `none` or that slot's payload (settings for the
|
|
@@ -80,6 +81,7 @@ operations in full.
|
|
|
80
81
|
| --- | --- | --- | --- |
|
|
81
82
|
| `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` for Git-backed consultation, `git` and `gh` for proposal/review PRs; ordinary kernel/harness selection, no provider harvest-runtime setting | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
|
|
82
83
|
| `messaging` | `oats.aweb` | the `aw` CLI at 1.36.33 or later; for channel delivery, `@awebai/pi` in pi or the `aweb-channel` plugin in Claude Code; host-only `root`, `roots` and `residents` in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
|
|
84
|
+
| `tasks` | `oats.aweb-tasks` | the `aw` CLI at 1.36.33 or later, and `oats.aweb` as the soul's messaging: tasks act as the instance's own oats.aweb identity in its default team; nothing in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
|
|
83
85
|
| `tasks` | `oats.jira` | `acli`, authenticated to the Jira site; `site` and `project` in the soul's `tasks:` payload or `settings.oats.jira` | [awebai/oats-jira](https://github.com/awebai/oats-jira) |
|
|
84
86
|
| `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
|
|
85
87
|
|
|
@@ -91,6 +93,16 @@ operations in full.
|
|
|
91
93
|
soul-only `knowledge: { harvest: off }` forbids harvest while retaining
|
|
92
94
|
consultation. No host switch or automatic transcript/retire capture remains;
|
|
93
95
|
`knowledge-maintainer` reviews the resulting Git PRs.
|
|
96
|
+
- **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
|
|
97
|
+
tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
|
|
98
|
+
identity in its default team. **An existing workspace opts in** by pinning
|
|
99
|
+
`oats.aweb: v1.31.0` (or later), adding
|
|
100
|
+
`tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
|
|
101
|
+
`oats sync`. Only new spawns get it. A soul that names its own tasks
|
|
102
|
+
provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
|
|
103
|
+
fails with `E_SLOT_CONFLICT`: to keep its own, it adds
|
|
104
|
+
`oats.aweb-tasks: off` to its `capabilities:`. A soul opts out of tasks
|
|
105
|
+
entirely with `tasks: none`.
|
|
94
106
|
- **`oats.aweb`** mints a messaging identity for each instance at spawn and
|
|
95
107
|
removes it at retire, contributes the aweb messaging skills, and wires the
|
|
96
108
|
channel so sessions are woken by mail. Under `delivery: channel`, Claude Code
|
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.
|
|
9
|
+
This is the operator guide for **oats.okf 5.3.0** (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.
|
|
28
|
+
oats.okf: v5.3.0
|
|
29
29
|
defaults:
|
|
30
30
|
knowledge: { oats.okf: { from: package } }
|
|
31
31
|
stores:
|
|
@@ -50,15 +50,18 @@ 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.
|
|
53
|
+
just editing a version line. For 5.3.0, 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.
|
|
56
|
+
**Upgrade:** pin `oats.okf: v5.3.0` 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
|
|
60
|
-
|
|
60
|
+
the harvest checkpoints; souls not ready for this must declare
|
|
61
61
|
`knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
|
|
62
|
+
From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the checkpoint
|
|
63
|
+
line in `log.md`, drops the available-memory gate, and has the proposer name
|
|
64
|
+
each harvester (`--name`, below).
|
|
62
65
|
|
|
63
66
|
### Bindings document
|
|
64
67
|
|
|
@@ -170,13 +173,19 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
170
173
|
means no harvest, and `unknown` or an error means stop and report, never
|
|
171
174
|
infer permission or edit the record. Working instances never write
|
|
172
175
|
accepted knowledge themselves.
|
|
173
|
-
2. **Propose
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
176
|
+
2. **Propose at each harvest checkpoint.** The checkpoints are a PR handed
|
|
177
|
+
over for review and a finished task. In a long-lived role whose task
|
|
178
|
+
never finishes (a maintainer, an expert holding an area, a support desk),
|
|
179
|
+
they also include a feature ready, a release or deploy shipped, and a
|
|
180
|
+
direction decision taken with the human. A commit, a review round, a new
|
|
181
|
+
head of the same PR and each decision made while working are not
|
|
182
|
+
checkpoints: those are captured in `notes/`, and the next checkpoint
|
|
183
|
+
carries them. First update state, log and relevant notes. Apply
|
|
184
|
+
`knowledge-theory` and search accepted knowledge (`oats okf search`, then
|
|
185
|
+
`cat`): already accepted with nothing to add means no proposal. Make **one
|
|
186
|
+
proposal per checkpoint, carrying only what no earlier proposal carried**,
|
|
187
|
+
and record every checkpoint in `log.md`, either with its proposal and
|
|
188
|
+
harvester or with `nothing to propose` and the reason.
|
|
180
189
|
|
|
181
190
|
Write a short self-contained `proposals/<YYYY-MM-DD>-<slug>.md` in instance
|
|
182
191
|
home: What (one claim per concept), Why, Evidence (observations, dates,
|
|
@@ -187,22 +196,25 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
187
196
|
nodes; a lesson for a node the soul only reads is named in one line in its
|
|
188
197
|
hand-back for that node's owner.
|
|
189
198
|
|
|
190
|
-
**Before spawning:** one harvester at a time per instance.
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
199
|
+
**Before spawning:** one harvester at a time per instance. Do not spawn
|
|
200
|
+
another while `oats status` still lists the last one: keep the proposal
|
|
201
|
+
pending in STATE.md and log.md, add the next checkpoint's claims to it,
|
|
202
|
+
and launch it at that checkpoint once the last harvester is gone. Never
|
|
203
|
+
poll, sleep or stop other instances to make room. (5.3.0 removed the
|
|
204
|
+
5.2.x available-memory gate.)
|
|
205
|
+
|
|
206
|
+
**The proposer names its harvester.** For each new proposal,
|
|
207
|
+
**okf-propose** prints a fresh name: up to 21 characters of the source
|
|
208
|
+
instance's name, a dash, a random UUID without dashes, and `-harvester`,
|
|
209
|
+
64 characters at most (the kernel's and aweb's alias limit). The proposer
|
|
210
|
+
records it with the proposal in log.md before the preview, checks that
|
|
211
|
+
`oats status` doesn't list it, and uses it unchanged in both the preview and
|
|
212
|
+
the apply. Never leave the name to the kernel's numbered default: a retired
|
|
213
|
+
harvester's messaging alias can stay occupied with no instance listed, and
|
|
214
|
+
a numbered name can land on it.
|
|
203
215
|
|
|
204
216
|
```sh
|
|
205
|
-
oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
|
|
217
|
+
oats spawn oats.okf/knowledge-harvester --name <harvester-name> --task-file <proposal> --relation unrelated
|
|
206
218
|
```
|
|
207
219
|
|
|
208
220
|
Never combine `--relation unrelated` with `--relative-to`, or override
|
|
@@ -214,7 +226,12 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
214
226
|
evidence before capture, so do not dispose of it before capture.
|
|
215
227
|
Missing source authority never permits inventing it.
|
|
216
228
|
|
|
217
|
-
A refused or uncertain spawn is reported, not retried in a loop.
|
|
229
|
+
A refused or uncertain spawn is reported, not retried in a loop. On
|
|
230
|
+
`E_INSTANCE_NAME_TAKEN`, the proposer stops and reports the name and the
|
|
231
|
+
refusal: no `--purpose`, no counter, no new UUID in a retry. A messaging
|
|
232
|
+
identity failure (for example a stale certificate on the alias) is
|
|
233
|
+
reported to the operator; the proposer never removes certificates or
|
|
234
|
+
renames around it. If the
|
|
218
235
|
last harvester is still listed at hand-back, name it and the claims still
|
|
219
236
|
waiting; do not wait for it or spawn around it. A harvester retained after
|
|
220
237
|
a publication failure stays listed and holds back later proposals. Once
|
package/docs/layers.md
CHANGED
|
@@ -46,8 +46,8 @@ not proof that an agent is enrolled. The official provider is `oats.aweb`.
|
|
|
46
46
|
### The tasks contract
|
|
47
47
|
|
|
48
48
|
The tasks capability owns assignment, claims, status, blockers and handoff.
|
|
49
|
-
|
|
50
|
-
conversation, not task state.
|
|
49
|
+
The official providers are `oats.aweb-tasks` (from the `oats.aweb` package),
|
|
50
|
+
`oats.jira` and `oats.linear`. Messaging is conversation, not task state.
|
|
51
51
|
|
|
52
52
|
## What the kernel does not own
|
|
53
53
|
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,10 +9,10 @@ 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.
|
|
13
|
-
| `oats.okf` | `v5.
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
15
|
-
| `oats.engineering` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.14.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.31.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
|
+
| `oats.engineering` | `v1.11.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` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
@@ -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.
|
|
32
|
+
`packages:` map (`oats.okf: v5.3.0`); `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.
|
|
47
|
+
oats.okf: v5.3.0 # 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.
|
|
51
|
+
- **Bare version** (`v5.3.0`, `5.3.0`, `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.
|
|
54
|
+
convention (`v5.3.0` or `oats-framework/v1.14.1`) 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.
|
|
78
|
-
oats.okf: v5.
|
|
79
|
-
oats.aweb: v1.
|
|
77
|
+
oats.framework: v1.14.1
|
|
78
|
+
oats.okf: v5.3.0
|
|
79
|
+
oats.aweb: v1.31.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.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.3.0 ✓ (@ 79befeaf)
|
|
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.31.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.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.3.0",
|
|
164
|
+
"commit": "79befeaf98e04a5a46896ddad8ac3333ee90bce3",
|
|
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.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.3.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.14.1", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
362
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.14.1`
|
|
362
|
+
resolves to tag `oats-framework/v1.14.1`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -357,6 +357,22 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
|
|
|
357
357
|
|
|
358
358
|
No entry file writes this line: only the tag owner knows the release's
|
|
359
359
|
version when the notes are assembled.
|
|
360
|
+
- **The same pull request updates "Upgrading to the latest version"**, the
|
|
361
|
+
section [Upgrading](upgrading.md) opens with: the version being tagged in
|
|
362
|
+
each place the section names it (the latest version, its notes, the
|
|
363
|
+
Desktop and the CLI install), and the CLIs that version's Desktop accepts,
|
|
364
|
+
up to its next minor (`ACCEPT_RANGE` in `packages/client/cli-locator.mjs`
|
|
365
|
+
once the release plan has moved it). The page
|
|
366
|
+
states only this band; the earlier ones stay in their notes. When the
|
|
367
|
+
release's Upgrade section asks for more than the page's steps, the order
|
|
368
|
+
of the Desktop and the CLI and an optional package pin, the pull request
|
|
369
|
+
also adds the release's entry at the top of "Coming from an older
|
|
370
|
+
version", one line that links its notes.
|
|
371
|
+
`test/release-packaging.test.mjs` checks that the section names the
|
|
372
|
+
version the manifests carry and no other, and that the page's only band
|
|
373
|
+
is that version's Desktop's. The oats.setup skill `oats-upgrade` reads
|
|
374
|
+
this page at the release's tag, so what the tag carries is what an upgrade
|
|
375
|
+
follows.
|
|
360
376
|
- **A tag is refused while anything is under `docs/release-notes/next/`:** by
|
|
361
377
|
the `build-and-test` job of `release.yml` and by `release-lane.mjs build`,
|
|
362
378
|
each right after its notes-file gate and before anything is built. Each
|