@awebai/oats 0.68.1 → 0.69.2
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 +180 -36
- package/docs/capabilities.md +73 -10
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/configuration.md +68 -2
- package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
- package/docs/design/2026-10-22-module-upgrade.md +1 -1
- package/docs/desktop-cli-api.md +600 -25
- package/docs/desktop-instance-start.md +59 -3
- package/docs/desktop.md +175 -10
- package/docs/execution-targets.md +536 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +33 -15
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +25 -16
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +6 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/servers.md +51 -7
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +46 -9
- package/docs/tui.md +177 -21
- package/docs/upgrading.md +16 -7
- package/docs/workspaces.md +2 -2
- package/injects/instance-boundary.md +19 -33
- package/injects/work-attached.md +8 -13
- package/injects/work-checkout.md +16 -30
- package/injects/work-directory.md +9 -15
- package/injects/work-workspace.md +8 -19
- package/injects/work-worktree.md +18 -33
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +496 -127
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-background.mjs +54 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +35 -0
- package/lib/instance-resolution.mjs +3 -2
- package/lib/instance-same-work.mjs +67 -0
- package/lib/instance-upgrade.mjs +18 -0
- package/lib/launch-prompt-fixtures/README.md +62 -0
- package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
- package/lib/launch-prompt-fixtures.mjs +49 -0
- package/lib/launch-prompt-resume.mjs +55 -0
- package/lib/login-environment.mjs +27 -9
- package/lib/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +136 -27
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +33 -0
- package/lib/session-resume.mjs +337 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +15 -11
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +41 -6
- package/package-catalog.json +11 -5
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +39 -8
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +16 -0
- package/packages/client/deployment-panel.mjs +7 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-tree.mjs +64 -14
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +11 -3
- package/packages/client/remote-roster.mjs +5 -1
- package/packages/client/roster-sections.mjs +50 -6
- package/packages/client/same-work.mjs +49 -0
- package/packages/client/session-attach.mjs +35 -5
- package/packages/client/session-resume-cli.mjs +64 -0
- package/packages/client/session-resume-trigger.mjs +167 -0
- package/packages/client/session-resume.mjs +332 -0
- package/packages/client/soul-rows.mjs +2 -0
- package/packages/client/spawn-apply-contract.mjs +2 -1
- package/packages/client/spawn-decision.mjs +4 -1
- package/packages/client/spawn-preview-contract.mjs +12 -1
- package/packages/client/spawn-preview.mjs +2 -0
- package/packages/client/tmux-status.mjs +30 -7
- package/packages/client/waiting-on-you.mjs +11 -4
- package/packages/client/workspace-step.mjs +17 -5
- package/packages/record/lib/last-conversation.mjs +123 -0
- package/packages/record/lib/session-roots.mjs +10 -1
- package/packages/tui/README.md +2 -2
- package/packages/tui/lib/client.mjs +7 -3
- package/packages/tui/lib/main.mjs +49 -14
- package/packages/tui/lib/model.mjs +146 -55
- package/packages/tui/lib/store.mjs +84 -27
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/frame.mjs +74 -7
- package/packages/tui/lib/views/help.mjs +10 -3
- package/packages/tui/lib/views/instances.mjs +41 -3
- package/skills/oats-getting-started/SKILL.md +117 -4
package/docs/capabilities.md
CHANGED
|
@@ -274,8 +274,9 @@ A self-contained package has an `oats.json`:
|
|
|
274
274
|
`.a*`);
|
|
275
275
|
- an exact name that is `.oats`, `.agents` or `.claude`, or that starts
|
|
276
276
|
with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
|
|
277
|
-
`.oats-agents-md`, `.oats-start`, `.oats-attachments
|
|
278
|
-
|
|
277
|
+
`.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
|
|
278
|
+
`.oats-background` or `.oats-same-work`: the top-level entries the kernel
|
|
279
|
+
itself writes in an instance home;
|
|
279
280
|
- a prefix that starts with `.oats-`.
|
|
280
281
|
|
|
281
282
|
An exact name such as `.oats-aweb` is allowed: it is a provider's
|
|
@@ -473,8 +474,23 @@ Every spawned instance gets a **full copy** of each capability its soul
|
|
|
473
474
|
resolved to, under `<home>/.oats/modules/<capability>/` (manifest, `bin/`,
|
|
474
475
|
injects, skills), and those skills flat under `<home>/.agents/skills/<skill>/`
|
|
475
476
|
beside the soul's own, one level deep where harnesses discover them. Its generated `AGENTS.md` is the
|
|
476
|
-
soul's `AGENTS.md`,
|
|
477
|
-
|
|
477
|
+
soul's `AGENTS.md`, then each module's inject, then the kernel's instance-boundary
|
|
478
|
+
and work-mode blocks, last. The injects take the order the soul and the workspace
|
|
479
|
+
give them: first the capabilities the soul lists, in its `capabilities:` order (a
|
|
480
|
+
soul entry that re-lists a workspace default sits at the soul's place), then the
|
|
481
|
+
workspace defaults the soul does not list, in the order the workspace's
|
|
482
|
+
`defaults:` lists them (slot defaults and `defaults.capabilities` entries as they
|
|
483
|
+
appear in the file). A standalone soul has no workspace defaults; the kernel's
|
|
484
|
+
own `oats.core` default, which it gets unless it names `oats.core`, comes after
|
|
485
|
+
the capabilities it lists, as any default does. A capability name made only of
|
|
486
|
+
digits (`"123"`) is the one exception to the listing order: it comes first in its
|
|
487
|
+
list, ahead of the names written before it, because the parsed list puts
|
|
488
|
+
integer-like keys first. A capability
|
|
489
|
+
with no inject adds nothing, and one the soul turns `off` or a slot `none` drops
|
|
490
|
+
is not composed. Only the instructions take this order: modules, skills and hooks
|
|
491
|
+
stay in name order, and reordering a soul's list is not a composition change (no
|
|
492
|
+
drift). `oats instance upgrade` keeps the order a home recorded and puts the
|
|
493
|
+
kernel's blocks last. Two composed skills with one name fail the spawn
|
|
478
494
|
(`E_SKILL_DUPLICATE`). The harness then starts normally, with its own skill
|
|
479
495
|
discovery; the details are in [souls-and-instances.md](souls-and-instances.md).
|
|
480
496
|
Change a capability's inject or skills in its repository, then spawn a new
|
|
@@ -1044,7 +1060,8 @@ latest-state capability.
|
|
|
1044
1060
|
|
|
1045
1061
|
### oats.core: needs input
|
|
1046
1062
|
|
|
1047
|
-
oats.core (2.4.0
|
|
1063
|
+
oats.core (since 2.4.0, which needs kernel 0.40.0; 2.8.0 needs 0.49.0, as
|
|
1064
|
+
"Across `oats instance upgrade`" below says) tells the deployment
|
|
1048
1065
|
when an instance is waiting on a human, in two independent ways. Each shows
|
|
1049
1066
|
on `oats status` and in `oats instance events`. The verbs' contract
|
|
1050
1067
|
(`oats instance waiting`, `oats instance attention`, the `waiting` event) is
|
|
@@ -1057,7 +1074,10 @@ question, a decision, an approval, a credential, any input it waits on), it runs
|
|
|
1057
1074
|
`oats instance attention --message "<one line>"` from its home and ends its
|
|
1058
1075
|
turn. Once it has the answer, it runs `oats instance attention --clear`. The
|
|
1059
1076
|
claim belongs to producer `agent`. Only `--clear` or the next session start,
|
|
1060
|
-
restart or stop clears it.
|
|
1077
|
+
restart or stop clears it. An instance whose human talks to its parent rather
|
|
1078
|
+
than to it sends the question to its parent instead; the parent sets its own
|
|
1079
|
+
claim naming the child and relays the answer. A claim is never set for
|
|
1080
|
+
another home. The message is one line of at most 200
|
|
1061
1081
|
characters; control characters, the Unicode line and paragraph separators,
|
|
1062
1082
|
bidi controls (U+202A–202E, U+2066–2069), U+200B, U+2060, U+FEFF and tag
|
|
1063
1083
|
characters (U+E0000–E007F) are refused, and everything else (emoji ZWJ
|
|
@@ -1091,10 +1111,31 @@ home. Before 2.4.1 it set and cleared the claim of the home its environment
|
|
|
1091
1111
|
named, and its `Stop` and `SessionEnd` clears could erase that instance's
|
|
1092
1112
|
real claim.
|
|
1093
1113
|
|
|
1114
|
+
**A set carries what the session waits on** (oats.core 2.8.0,
|
|
1115
|
+
[#1502](https://github.com/awebai/oats/issues/1502)). The script reads the
|
|
1116
|
+
hook's JSON input, at most 64 KiB and for at most 1 s, and its
|
|
1117
|
+
`bin/claude-waiting-message.mjs` makes the claim's `--message` from it. On
|
|
1118
|
+
Claude Code 2.1.300:
|
|
1119
|
+
- an `AskUserQuestion` gives its first question's own words
|
|
1120
|
+
(`tool_input.questions[0].question`), with `(+N more)` when it asks
|
|
1121
|
+
several;
|
|
1122
|
+
- a `Notification` gives its `message`: "Claude needs your permission to use
|
|
1123
|
+
Bash" for a permission prompt, "Claude Code needs your input" for an
|
|
1124
|
+
elicitation dialog.
|
|
1125
|
+
|
|
1126
|
+
The text is made one line, the kernel's refused characters are replaced with
|
|
1127
|
+
U+FFFD, and it is cut to 200 code points with `…`, so the kernel accepts it.
|
|
1128
|
+
An input with no text, or a reader that fails or takes over 1 s, sets the
|
|
1129
|
+
claim without one. A new text for the same reason is a change, so the claim
|
|
1130
|
+
is set again. A set records its intent before it reads the text, and only
|
|
1131
|
+
the latest event's text is ever applied. So a clear or a question that comes
|
|
1132
|
+
while an earlier set is still reading stands, and the earlier text never
|
|
1133
|
+
lands over it.
|
|
1134
|
+
|
|
1094
1135
|
Claude Code shows an AskUserQuestion through its permission dialog, so that
|
|
1095
1136
|
dialog's own `permission_prompt` follows the question's set: the script keeps
|
|
1096
|
-
the current reason in its marker
|
|
1097
|
-
open question. A granted tool that fails fires `PostToolUseFailure`, not
|
|
1137
|
+
the current reason in its marker (and the text beside it), and a permission
|
|
1138
|
+
prompt never relabels an open question or replaces its text. A granted tool that fails fires `PostToolUseFailure`, not
|
|
1098
1139
|
`PostToolUse`, so that clears too.
|
|
1099
1140
|
|
|
1100
1141
|
**Subagents' tool calls do not clear.** Background and parallel subagents
|
|
@@ -1143,7 +1184,8 @@ clears it.
|
|
|
1143
1184
|
in the home (`.oats/modules/oats.core`), which a start does not refresh. A
|
|
1144
1185
|
home spawned with an oats.core that does not read the variable therefore
|
|
1145
1186
|
writes its hook's own node path at every start: a restart repairs its
|
|
1146
|
-
hooks after each Node upgrade, and a respawn
|
|
1187
|
+
hooks after each Node upgrade, and a respawn, or an upgrade of its
|
|
1188
|
+
oats.core (below), gives it the lasting path. A
|
|
1147
1189
|
launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
|
|
1148
1190
|
and pi homes get nothing.
|
|
1149
1191
|
- **It never hurts the session.** Claude Code reads a hook's stdout and exit
|
|
@@ -1216,6 +1258,25 @@ clears it.
|
|
|
1216
1258
|
exactly `.claude/settings.json`. oats.core writes it at spawn before the
|
|
1217
1259
|
retirement baseline is taken, and again at every start.
|
|
1218
1260
|
|
|
1261
|
+
**Across `oats instance upgrade`.** oats.core 2.8.0 declares an `upgrade`
|
|
1262
|
+
hook ([the upgrade event](#the-upgrade-event)), not required, so a stopped
|
|
1263
|
+
home whose oats.core moves to it is upgraded rather than respawned. The
|
|
1264
|
+
hook that runs is the destination's, so this covers homes spawned on any
|
|
1265
|
+
earlier oats.core, with or without the emitter. oats.core records no
|
|
1266
|
+
capability metadata, and its settings entries name the module copy's path,
|
|
1267
|
+
`.oats/modules/oats.core`, which an upgrade keeps; the next start's launch
|
|
1268
|
+
hook rewrites them. So `plan` adopts a home whose recorded
|
|
1269
|
+
`capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
|
|
1270
|
+
`false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
|
|
1271
|
+
refuses any other value as state it cannot vouch for, with the remedy
|
|
1272
|
+
`respawn the instance: oats retire <instance>, then oats spawn`. `apply`
|
|
1273
|
+
returns `{"meta":{}}`, which the kernel records as
|
|
1274
|
+
`capabilityMeta["oats.core"]`, and exits 1 with a JSON `warning` on any other
|
|
1275
|
+
metadata. Neither phase reads the home or calls the host. oats.core 2.8.0
|
|
1276
|
+
requires OATS 0.49.0: an earlier kernel drops a capability that declares a
|
|
1277
|
+
hook event it does not know, so it would lose oats.core whole. Only OATS
|
|
1278
|
+
0.68.0 and later run the hook.
|
|
1279
|
+
|
|
1219
1280
|
**Why the project settings file, not `--settings`.** On Claude Code
|
|
1220
1281
|
2.1.288, Claude honours only the last `--settings` flag on a command line:
|
|
1221
1282
|
that file replaces earlier ones wholesale, even one with no hooks. The
|
|
@@ -1281,7 +1342,9 @@ again" permission rules there.
|
|
|
1281
1342
|
so its `Stop` and `SessionEnd` clears can erase the home's own live
|
|
1282
1343
|
`oats.core` claim ([#557](https://github.com/awebai/oats/issues/557)).
|
|
1283
1344
|
- A Claude instance spawned before the upgrade gets the emitter only when
|
|
1284
|
-
it is respawned
|
|
1345
|
+
it is respawned, or when `oats instance upgrade` moves its oats.core to
|
|
1346
|
+
2.8.0 or later and it starts again. Its launch hook comes from its
|
|
1347
|
+
recorded module copy.
|
|
1285
1348
|
|
|
1286
1349
|
## Operations a capability declares
|
|
1287
1350
|
|
|
@@ -366,7 +366,7 @@
|
|
|
366
366
|
"description": "Home entries the kernel owns cannot be declared.",
|
|
367
367
|
"anyOf": [
|
|
368
368
|
{"pattern": "^\\.(?:oats|agents|claude)$"},
|
|
369
|
-
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
|
|
369
|
+
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
|
|
370
370
|
{"pattern": "^\\.oats-.*\\*$"}
|
|
371
371
|
]
|
|
372
372
|
}
|
package/docs/configuration.md
CHANGED
|
@@ -251,6 +251,15 @@ v<semver>` after the logo, which may be caught mid-animation), the error and the
|
|
|
251
251
|
|
|
252
252
|
A restart where the notice shows records `flag-ignored`.
|
|
253
253
|
|
|
254
|
+
**Known limit: a split window.** The confirmation still requires the agent's
|
|
255
|
+
window to have one pane. A start or restart in place on a window that has
|
|
256
|
+
another pane (oats.setup's no-echo prompt, for example) relaunches Claude in
|
|
257
|
+
the agent's pane
|
|
258
|
+
([which pane is the agent's](execution-targets.md#which-pane-is-the-agents))
|
|
259
|
+
but answers nothing: the home records `launchPrompts.status: "blocked"`, and
|
|
260
|
+
Claude waits at its development-channel prompt for a person, as after any
|
|
261
|
+
blocked start. Close the other pane before the restart.
|
|
262
|
+
|
|
254
263
|
**The two settings that stop it.** OATS confirms the prompt only because the
|
|
255
264
|
deployment launches Claude with the development-channel flag. To keep the prompt
|
|
256
265
|
for a person, stop launching that way: `settings.oats.aweb.delivery: session`
|
|
@@ -279,8 +288,8 @@ instance's terminal and press Enter yourself.
|
|
|
279
288
|
## Launch configurations
|
|
280
289
|
|
|
281
290
|
An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
|
|
282
|
-
(a bare name looked up on `PATH`, or a path relative to
|
|
283
|
-
|
|
291
|
+
(a bare name looked up on `PATH`, or a path relative to the directory of the
|
|
292
|
+
file that declares it), `args` (literal, no shell), `env` (a literal string, or
|
|
284
293
|
`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
|
|
285
294
|
`default` (0.32; see [the harness default](#the-harness-default)). A launch
|
|
286
295
|
configuration is a host choice: a soul never names one.
|
|
@@ -315,6 +324,63 @@ configuration is a host choice: a soul never names one.
|
|
|
315
324
|
`oats spawn` and reading `aw` mail and chat, and what stays gated.
|
|
316
325
|
`yolo` is separate and is meant for isolated machines.
|
|
317
326
|
|
|
327
|
+
### This machine's launch configurations
|
|
328
|
+
|
|
329
|
+
`~/.oats/config/launch-configs.yaml` (`$OATS_HOME_DIR/config/` when
|
|
330
|
+
`OATS_HOME_DIR` is set) declares launch configurations for every deployment
|
|
331
|
+
on this machine. The person writes it, or an installer running as the
|
|
332
|
+
person; nothing in OATS writes it.
|
|
333
|
+
|
|
334
|
+
```yaml
|
|
335
|
+
launch-configs:
|
|
336
|
+
claude-auto:
|
|
337
|
+
harness: claude
|
|
338
|
+
args: ["--permission-mode", "auto"]
|
|
339
|
+
default: true
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
- **One key.** The file holds `launch-configs:` and nothing else. Its entries
|
|
343
|
+
have exactly the schema of the deployment's block and the same checks.
|
|
344
|
+
- **Missing or broken.** A missing file declares nothing. A file that is there
|
|
345
|
+
but cannot be read, is not valid YAML, is empty, lacks `launch-configs:`,
|
|
346
|
+
has any other top-level key, or holds an invalid entry is refused
|
|
347
|
+
(`E_LAUNCH_CONFIG_INVALID`, naming the file). The refusal reaches every
|
|
348
|
+
listing, preview, spawn and start that reads launch configurations. It is
|
|
349
|
+
never skipped. `oats doctor` reports the file and does not fail on it.
|
|
350
|
+
- **Precedence, by name.** Each deployment reads the machine's entries under
|
|
351
|
+
its own. A deployment entry with the same name replaces the machine's
|
|
352
|
+
whole: no field of the machine's entry is kept. Its `shadows` names the
|
|
353
|
+
machine file. With no deployment in reach, the machine's entries alone
|
|
354
|
+
apply.
|
|
355
|
+
- **Precedence, for the default.** The [harness default](#the-harness-default)
|
|
356
|
+
is per harness. A deployment's `default: true` for a harness wins over the
|
|
357
|
+
machine's: the machine's entry for that harness stays listed, but not as
|
|
358
|
+
default. The machine's default applies when the deployment declares none
|
|
359
|
+
for that harness. Two defaults for one harness within one file are refused,
|
|
360
|
+
as in the deployment.
|
|
361
|
+
- **`source`** is the directory an entry was declared in: the deployment
|
|
362
|
+
directory, or `~/.oats/config`. A relative `executable` resolves against
|
|
363
|
+
it.
|
|
364
|
+
- **Where it shows.**
|
|
365
|
+
- `oats launch-config list` (and `--json`) gives each entry's `source` and
|
|
366
|
+
`shadows`.
|
|
367
|
+
- `oats spawn --preview` names the machine file when it supplied the
|
|
368
|
+
configuration; the JSON carries `launchConfigSource`.
|
|
369
|
+
- `oats doctor --json` reports the file under `machineLaunchConfigs`:
|
|
370
|
+
`file`, `present`, `ok`, `configurations` (the names) and, when broken,
|
|
371
|
+
`error`.
|
|
372
|
+
- **Writes.** `oats launch-config set|remove` writes only the deployment's
|
|
373
|
+
`oats-local.yaml`. Setting a name the machine also declares adds a
|
|
374
|
+
deployment entry that shadows it, and removing that entry uncovers the
|
|
375
|
+
machine's again. Desktop's launch-configuration editor writes the same
|
|
376
|
+
way: saving a row whose source is the machine file writes a deployment
|
|
377
|
+
entry of that name, which then shadows the machine's.
|
|
378
|
+
- **Homes.** A spawn records the configuration as it was, the machine's like
|
|
379
|
+
the deployment's (`launchConfigSource` is the directory it came from). A
|
|
380
|
+
start or restart runs the recorded recipe; a later edit of either file
|
|
381
|
+
reaches a home only through `--launch-config <name>`, `--reselect-launch`
|
|
382
|
+
or a respawn.
|
|
383
|
+
|
|
318
384
|
### The harness default
|
|
319
385
|
|
|
320
386
|
`default: true` makes a configuration this host's baseline for its harness
|
|
@@ -258,13 +258,15 @@ delivers; what a provider consumes is its own contract. Teams reach providers as
|
|
|
258
258
|
from: { kind: "member", repoKey, commit }
|
|
259
259
|
| { kind: "package", package, version, commit, integrity, repoKey } }],
|
|
260
260
|
slots, skills, injects, payloads, payloadOrigins,
|
|
261
|
-
teams, defaultTeam, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision }
|
|
261
|
+
teams, defaultTeam, slotsFrom, capabilitiesFrom, instructionOrder, turnedOff, declRevision, payloadRevision, revision }
|
|
262
262
|
```
|
|
263
263
|
|
|
264
264
|
`module.dir` is the listed capability directory (for a package, the `oats-package.json#capabilities[]`
|
|
265
265
|
entry). `declRevision` covers `{ resolutionApi, soul, modules, slots, skills, injects }`,
|
|
266
266
|
`payloadRevision` the payloads, `revision` both (24 hex of SHA-256 over canonical JSON). A spawn decision
|
|
267
|
-
binds `revision`. Provenance fields enter neither revision.
|
|
267
|
+
binds `revision`. Provenance fields enter neither revision. `instructionOrder` is one: the module names
|
|
268
|
+
in the order their injects take in the composed `AGENTS.md` (the soul's `capabilities:` order, then the
|
|
269
|
+
workspace defaults it does not list, in `defaults:` file order).
|
|
268
270
|
|
|
269
271
|
---
|
|
270
272
|
|
|
@@ -316,8 +318,8 @@ shims that throw `E_REMOVED { name, contract }`, pointing at this record.
|
|
|
316
318
|
2. The copy's digest must equal the fetch's and any `module.digest` (`E_MATERIALIZE_INTEGRITY`).
|
|
317
319
|
3. Copy skills whole to `<home>/.agents/skills/<skill>/`, flat (0.30.2; the grouped
|
|
318
320
|
`<name>/<skill>/` layout this section first specified hid every skill from the harnesses).
|
|
319
|
-
4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) +
|
|
320
|
-
|
|
321
|
+
4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + module injects in
|
|
322
|
+
`instructionOrder` + kernel blocks (`options.blocks`); operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
|
|
321
323
|
and `.claude/skills → ../.agents/skills`.
|
|
322
324
|
5. Record `modules: { <name>: { from, commit, digest, materializedAt } }`, `providers` (the payloads) and
|
|
323
325
|
`resolutionRevision` in `instance.json`.
|
|
@@ -78,7 +78,7 @@ Apply runs under the claim, with the plan revision re-checked. A stale plan refu
|
|
|
78
78
|
|
|
79
79
|
1. **Stage.** Stage the new module copies in `<home>/.oats/.staging-upgrade-<receipt>`, on the same filesystem so the renames are atomic, and recompose the derived files there. Use the **same code as spawn**: refactor `materialize()` so that composing a home from a resolution can target an existing home. Do not write a second composer. The derived files are:
|
|
80
80
|
- `.agents/skills`;
|
|
81
|
-
- `AGENTS.md`: the soul body at the **recorded soul commit**, the
|
|
81
|
+
- `AGENTS.md`: the soul body at the **recorded soul commit**, each module's inject in the order the home's `instructions` recorded (a module with no recorded block after them, by name), then the kernel blocks. If the soul body at that commit can't be read, refuse;
|
|
82
82
|
- in `instance.json`: `modules`, `capabilities[]`, `capabilityRuntime[]` (the absolute hook commands that retire runs), `skills[]`, `instructions[]`, `composition`, `launch.hooks.contributions`, `resolutionRevision`.
|
|
83
83
|
Read the soul body through discovery's path rule at that recorded commit:
|
|
84
84
|
a member soul uses `souls/<agent>/AGENTS.md`; a package soul uses its
|