@awebai/oats 0.48.0 → 0.49.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 +226 -14
- package/docs/capabilities.md +256 -8
- package/docs/capability-manifest.schema.json +18 -5
- package/docs/configuration.md +6 -0
- package/docs/desktop-cli-api.md +368 -31
- package/docs/desktop.md +72 -5
- package/docs/execution-targets.md +17 -2
- package/docs/implementation.md +62 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +8 -8
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/schedules.md +62 -39
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +381 -53
- package/docs/workspaces.md +2 -2
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +5 -2
- package/lib/core.mjs +1109 -321
- package/lib/instance-events.mjs +6 -3
- package/lib/instance-git.mjs +11 -5
- package/lib/instance-inspect.mjs +14 -3
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +1 -0
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/triggers.mjs +201 -65
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
package/docs/capabilities.md
CHANGED
|
@@ -94,15 +94,49 @@ A self-contained package has an `oats.json`:
|
|
|
94
94
|
slot.
|
|
95
95
|
- `skills` entries can be skill directories or roots containing skills.
|
|
96
96
|
- `inject` is optional instance instruction Markdown.
|
|
97
|
-
- The hooks are `spawn`, `launch` and `
|
|
97
|
+
- The hooks are `spawn`, `launch`, `retire` and `worktree`
|
|
98
|
+
([The worktree event](#the-worktree-event)). A hook is a
|
|
98
99
|
command string, or `{ command, required }`. `required: true` is valid **only
|
|
99
|
-
on `spawn`**:
|
|
100
|
+
on `spawn` and `worktree`**: a required spawn hook's failure fails the spawn
|
|
101
|
+
and rolls it back,
|
|
100
102
|
instead of producing an instance whose capability never configured itself —
|
|
101
103
|
an aweb identity that could not be minted leaves an agent believing it can be
|
|
102
|
-
woken by mail.
|
|
104
|
+
woken by mail. A required `worktree` hook's failure fails the spawn the same
|
|
105
|
+
way, or removes the tree `oats worktree add` made. Every other hook stays
|
|
106
|
+
best-effort and only warns, so advisory
|
|
103
107
|
work never becomes a spawn blocker. `launch` and `retire` cannot be
|
|
104
108
|
required: they run outside a spawn transaction, so there is no moment to
|
|
105
109
|
enforce them. A `soul-scaffold` hook is tolerated and ignored.
|
|
110
|
+
- An **event this kernel does not run** (a newer kernel's) is accepted from
|
|
111
|
+
0.49.0 on, so a capability that adopts a new event keeps composing on an
|
|
112
|
+
older host. Declared as a command string, `{ command }` or
|
|
113
|
+
`{ command, required: false }`, it is ignored and never runs, and the
|
|
114
|
+
capability carries the warning `hook-event-unsupported`: `capability <id>
|
|
115
|
+
declares hook "<event>", which this kernel does not run`. Declared
|
|
116
|
+
`required: true`, it is refused (`declares unsupported hook`), because
|
|
117
|
+
skipping a hook its author declared essential would fail open. The
|
|
118
|
+
tolerance covers the event's name only: its declaration is checked as for a
|
|
119
|
+
known event (a non-empty command, no unknown keys, a boolean `required`, a
|
|
120
|
+
script inside the capability), and a malformed one is refused. It helps
|
|
121
|
+
from 0.49.0 on only: a kernel before 0.49.0 refuses every unknown event, so
|
|
122
|
+
a capability that must load there declares only the events it runs.
|
|
123
|
+
- The warning is `{code: "hook-event-unsupported", capability, path,
|
|
124
|
+
message}`. It appears in `oats sync` and `oats workspace status`, `oats
|
|
125
|
+
capabilities show`, `oats inspect`, `oats readiness` and `oats doctor` (in
|
|
126
|
+
their `warnings`), and as its message in the `warnings` strings of `oats
|
|
127
|
+
spawn --preview` and `oats spawn` (clipped to fit their receipt), in JSON and in text
|
|
128
|
+
([desktop-cli-api.md](desktop-cli-api.md#capability-warnings-hook-event-unsupported-oats-0490)).
|
|
129
|
+
`path` names the manifest that was read, in one of two forms, never an
|
|
130
|
+
absolute host path:
|
|
131
|
+
|
|
132
|
+
| Read from | `path` | Commands |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| the workspace (a member's or a package's manifest) | `<repoKey>:<dir>/oats.json#/hooks/<event>`, or `package:<id>:<dir>/oats.json#/hooks/<event>`; `<dir>` relative to the repository | sync, workspace status, capabilities show, inspect and readiness `--soul`, doctor, spawn |
|
|
135
|
+
| an instance home's module copy | `.oats/modules/<name>/oats.json#/hooks/<event>`, relative to the home | inspect and readiness `--home` |
|
|
136
|
+
|
|
137
|
+
Doctor without `--soul` reads every member and locked package capability
|
|
138
|
+
from this machine's cache only. What the cache cannot answer is reported as
|
|
139
|
+
unchecked (`hook-events-unchecked` in its information), never as no warning.
|
|
106
140
|
- A capability declaring a **required** spawn hook should declare a `retire` hook
|
|
107
141
|
too. Without one, OATS has no way to undo what the spawn hook did and no way to
|
|
108
142
|
know whether it did anything, so a failure quarantines the home rather than
|
|
@@ -118,7 +152,8 @@ A self-contained package has an `oats.json`:
|
|
|
118
152
|
`oats status` reports it as retained state rather than a live instance, and
|
|
119
153
|
`oats retire <instance>` retries the cleanup — re-running the retire hooks and
|
|
120
154
|
the worktree removal, verifying both, and verifying (never deleting) the
|
|
121
|
-
branch: no retire deletes a branch
|
|
155
|
+
branch: no retire deletes a branch, with one exception, a spawn killed while
|
|
156
|
+
its `worktree` hooks ran (below). While the branch the failed spawn created
|
|
122
157
|
is still there, the retry stays incomplete with the item `the branch the
|
|
123
158
|
failed spawn created is left: OATS does not delete it. Inspect it and delete
|
|
124
159
|
it with Git if it is not wanted, then retry`. The item names no branch: the
|
|
@@ -147,6 +182,60 @@ A self-contained package has an `oats.json`:
|
|
|
147
182
|
success, and every Git step it records must be re-run and verified. A retry that resolves no
|
|
148
183
|
capabilities — a hand-edited descriptor, or config drift since the spawn — is an
|
|
149
184
|
incomplete cleanup, not a clean one, and the home stays.
|
|
185
|
+
- **A spawn in progress** (0.49.0). A `work: worktree` spawn that fires
|
|
186
|
+
[`worktree` hooks](#the-worktree-event) writes the same marker just before
|
|
187
|
+
the first of them, so a parent killed while they run (SIGKILL included)
|
|
188
|
+
leaves a home `oats retire` can clean up. Its `outstanding` holds the retire
|
|
189
|
+
hooks of the capabilities whose spawn hooks ran, plus the Git steps
|
|
190
|
+
`worktree` and `branch`. It adds an optional top-level `inProgress: { pid,
|
|
191
|
+
processStart, startedAt, branch, baseOid, hookPgid?, hookStart? }`: the
|
|
192
|
+
spawning process, identified by its pid and start time, the branch the spawn
|
|
193
|
+
created and the commit it created it at, and the process group of the hook
|
|
194
|
+
running. The spawn removes the marker once its final `instance.json` and
|
|
195
|
+
baseline are written; a failure's compensation replaces it in one rename.
|
|
196
|
+
Such a marker satisfies every rule above, so a reader that does not know
|
|
197
|
+
`inProgress` reads it as a quarantine. While the spawning process is
|
|
198
|
+
verifiably alive (its pid runs with the recorded start time):
|
|
199
|
+
- `oats status` gives the home's row `spawnInProgress: true` and no
|
|
200
|
+
`rollbackIncomplete`;
|
|
201
|
+
- `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--force` included;
|
|
202
|
+
- `oats session start` refuses it as any quarantined home
|
|
203
|
+
(`E_INSTANCE_RETIRING`).
|
|
204
|
+
|
|
205
|
+
Whether the process exists is the operating system's answer (`kill -0`:
|
|
206
|
+
"no such process" is gone, another user's process exists), the same on
|
|
207
|
+
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
|
+
(in a fixed `LC_ALL=C`, `TZ=UTC` environment) where there is no `/proc`,
|
|
209
|
+
as on macOS. A start that cannot be read is never taken to mean the process is
|
|
210
|
+
gone, nor shown as alive: `oats status` shows the quarantine
|
|
211
|
+
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
212
|
+
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
|
213
|
+
check by hand. Once that check shows the spawn is gone, `oats retire
|
|
214
|
+
<instance> --force` retires the home and keeps the branch
|
|
215
|
+
(`spawnCompensation.reason`, `forcedIncomplete`).
|
|
216
|
+
|
|
217
|
+
Once that process is gone (killed with SIGKILL, or its rollback cut
|
|
218
|
+
short), `oats retire` finishes the spawn's own compensation, in order:
|
|
219
|
+
1. it ends the hook process group the spawn left, only when the group's
|
|
220
|
+
leader runs with its recorded start time. A group whose leader has
|
|
221
|
+
exited is not signalled, and a warning names it;
|
|
222
|
+
2. it runs the owed retire hooks;
|
|
223
|
+
3. it removes the worktree and verifies the removal;
|
|
224
|
+
4. only then, it deletes `inProgress.branch` with an atomic
|
|
225
|
+
compare-and-delete at `inProgress.baseOid` (`git update-ref -d
|
|
226
|
+
refs/heads/<b> <baseOid>`).
|
|
227
|
+
|
|
228
|
+
This is the one exception to "no retire deletes a branch": a branch still
|
|
229
|
+
at the commit it was created at holds no work. Retire does not delete it,
|
|
230
|
+
and falls back to the "branch left" item above naming the branch (the home
|
|
231
|
+
is retained), when its tip moved, when it is checked out in any worktree,
|
|
232
|
+
or when its ref cannot be read. Every other quarantine keeps its branch.
|
|
233
|
+
The retire result's `branchDeleted` means exactly "retire's own
|
|
234
|
+
`--delete-branch`" (refused, so always `false`), not whether a branch was
|
|
235
|
+
deleted. This step is reported in the additive `spawnCompensation`, the one
|
|
236
|
+
place a retire's branch deletion is reported: `{ branch, branchDeleted:
|
|
237
|
+
true }`, or `{ branch, branchDeleted: false, reason }`, present only when
|
|
238
|
+
the step was reached.
|
|
150
239
|
- Because some cleanups can never succeed (a capability offering no way to undo its
|
|
151
240
|
own setup, a permanently unreachable remote), **`--force` also overrides
|
|
152
241
|
retention**: the home is removed, and everything still outstanding is printed as
|
|
@@ -210,17 +299,35 @@ A self-contained package has an `oats.json`:
|
|
|
210
299
|
`home`, the roots are recorded at spawn. The other work modes do not use
|
|
211
300
|
them.
|
|
212
301
|
|
|
302
|
+
A root is read the way spawn records it: a backslash reads as `/`, one
|
|
303
|
+
leading `./` and one trailing `/` are dropped (`./build/` is `build`).
|
|
304
|
+
What is left must be a relative path with no empty, `.` or `..` segment
|
|
305
|
+
(`build`, `node_modules/.cache`). Refused: an empty string, an absolute
|
|
306
|
+
path (`/x`, `\x`, or a Windows one such as `C:/x`, on every host),
|
|
307
|
+
`../x`, `a/../b`, `a//b`, `a/./b`, `.`. Two entries of one manifest that
|
|
308
|
+
overlap, the same root or one inside the other (`build` and `./build/`,
|
|
309
|
+
`a` and `a/b`), are refused too.
|
|
310
|
+
|
|
311
|
+
Spawn alone can see two more cases, and refuses the spawn with
|
|
312
|
+
`E_CAPABILITY_BROKEN` and rolls it back: a declared root that is a
|
|
313
|
+
symlink in the work (also one whose target is missing), and roots of
|
|
314
|
+
different capabilities that overlap. `oats spawn --json` reports these,
|
|
315
|
+
as other spawn failures, as `E_SPAWN_FAILED` with the same message.
|
|
316
|
+
|
|
213
317
|
A malformed `retirement` is refused wherever the manifest is read: member
|
|
214
318
|
discovery (`E_WORKSPACE_SCHEMA`), package manifests (`E_PACKAGE_MANIFEST`)
|
|
215
319
|
and the kernel loader refuse the same manifest, with a JSON pointer:
|
|
216
320
|
`/retirement` (no `disposable` map, or a key other than `disposable`,
|
|
217
321
|
`home` and `work`), `/retirement/disposable/<scope>` (not an array of
|
|
218
|
-
strings)
|
|
219
|
-
grammar)
|
|
322
|
+
strings), `/retirement/disposable/home/<i>` (an entry outside the
|
|
323
|
+
grammar) or `/retirement/disposable/work/<i>` (a root outside the grammar,
|
|
324
|
+
or one that overlaps an earlier entry):
|
|
220
325
|
|
|
221
326
|
```text
|
|
222
327
|
capability <id> manifest retirement.disposable.home entry "<value>" must name one hidden top-level home entry (".name", or ".prefix-*")
|
|
223
328
|
capability <id> manifest retirement.disposable.home entry "<value>" covers a kernel-owned home entry
|
|
329
|
+
capability <id> manifest retirement.disposable.work entry "<value>" must be a relative path under work/ with no empty, "." or ".." segment
|
|
330
|
+
capability <id> manifest retirement.disposable.work entry "<value>" overlaps entry "<earlier>": the same root, or one inside the other
|
|
224
331
|
```
|
|
225
332
|
|
|
226
333
|
This kernel reads the field. What retire does with the entries is in
|
|
@@ -441,7 +548,8 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
|
|
|
441
548
|
`OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
|
|
442
549
|
`OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
|
|
443
550
|
preview (only a preview-aware hook does, below); on a real run
|
|
444
|
-
`OATS_LAUNCH_PREVIEW` is not set.
|
|
551
|
+
`OATS_LAUNCH_PREVIEW` is not set. A worktree hook also gets the tree
|
|
552
|
+
variables of [The worktree event](#the-worktree-event).
|
|
445
553
|
|
|
446
554
|
A dispatched command (`oats <namespace> <command>`, from an instance home or
|
|
447
555
|
from the deployment directory) receives:
|
|
@@ -483,7 +591,8 @@ a home with none recorded gives `{}`. A final JSON line may return `meta`,
|
|
|
483
591
|
`brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
|
|
484
592
|
launch hook's preview answer may add `volatileEnv` (below). A **spawn or
|
|
485
593
|
launch hook** may also return an `env` object for the launched process;
|
|
486
|
-
returning `env` from a retire hook is an
|
|
594
|
+
returning `env` from a retire or [worktree](#the-worktree-event) hook is an
|
|
595
|
+
explicit contract error.
|
|
487
596
|
|
|
488
597
|
A **launch hook** runs at every start and restart of a home for each provider
|
|
489
598
|
recorded at spawn (under its recorded settings). Its `launch` arguments and
|
|
@@ -615,6 +724,145 @@ Spawn order is by capability name; retirement reverses successful
|
|
|
615
724
|
spawn order. Hooks run from the instance's own copy
|
|
616
725
|
(`<home>/.oats/modules/<cap>/`).
|
|
617
726
|
|
|
727
|
+
### The worktree event
|
|
728
|
+
|
|
729
|
+
`OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
|
|
730
|
+
kernel has just created: install dependencies, link environment files, pin
|
|
731
|
+
a toolchain. The kernel runs only the hooks of the instance's own
|
|
732
|
+
capabilities; it runs no code from the repository.
|
|
733
|
+
|
|
734
|
+
**When it fires.** Once for each tree the kernel creates:
|
|
735
|
+
|
|
736
|
+
- `./work` of a `work: worktree` spawn, after the spawn hooks succeed and
|
|
737
|
+
inside the spawn's transaction;
|
|
738
|
+
- each extra tree `oats worktree add` makes
|
|
739
|
+
([extra trees](souls-and-instances.md#extra-trees)).
|
|
740
|
+
|
|
741
|
+
It never fires for a `checkout`, `attached`, `workspace` or `directory`
|
|
742
|
+
`./work`, for a tree made with raw Git, or at start, restart, resume or
|
|
743
|
+
retire. `oats worktree remove` fires no hook. An `add` that finds its tree
|
|
744
|
+
already made (same clone, branch and base) runs no hook again.
|
|
745
|
+
|
|
746
|
+
**How it runs.** Hooks run in capability-name order, from the module copy,
|
|
747
|
+
like every hook. Other events keep their own behaviour (120 s, buffered,
|
|
748
|
+
cwd the home); this one differs:
|
|
749
|
+
|
|
750
|
+
- **cwd is the new tree.** `OATS_TREE` names it too.
|
|
751
|
+
- stdin is `/dev/null`, with no terminal.
|
|
752
|
+
- The hook is started detached, in its own process group, so a timeout or an
|
|
753
|
+
interrupt ends the whole group.
|
|
754
|
+
- stdout and stderr go to `<home>/.oats/logs/worktree-<purpose>-<cap>.log`
|
|
755
|
+
(`worktree-work-<cap>.log` for `./work`), created 0600 and truncated on each
|
|
756
|
+
run. On `oats worktree add` they are also copied to the kernel's stderr,
|
|
757
|
+
never its stdout: `--json` prints only the envelope. A caller that closes
|
|
758
|
+
its end of stderr or stdout (a tool shell killed, Desktop gone) only stops
|
|
759
|
+
the copy: the hooks and the add run to their end, and the log is whole. The log holds whatever
|
|
760
|
+
the hook printed, so its content never enters any JSON answer, receipt,
|
|
761
|
+
record, marker or instance event: they carry the log's path only. The
|
|
762
|
+
`warning` of the hook's last JSON line is the one piece of its output that
|
|
763
|
+
may surface.
|
|
764
|
+
- The timeout is 30 minutes, fixed. At the timeout the kernel sends the group
|
|
765
|
+
SIGTERM, then SIGKILL after a short grace.
|
|
766
|
+
- The result is the exit status. Of the last stdout line's JSON only
|
|
767
|
+
`warning` is read. Returning `env` is a contract error
|
|
768
|
+
(`E_HOOK_ENVIRONMENT_CONTRACT`), as at retire; `meta`, `brief` and `launch`
|
|
769
|
+
are ignored.
|
|
770
|
+
- A non-required hook that fails or times out is a warning; the tree is kept.
|
|
771
|
+
A required one (`{ command, required: true }`) fails closed:
|
|
772
|
+
- at spawn, it fails the spawn through the required-hook rollback above
|
|
773
|
+
(retire hooks compensate in reverse, the worktree-mode Git state is
|
|
774
|
+
removed and verified, and the home is deleted, or kept as a quarantine).
|
|
775
|
+
The hook's log was in that home: once it is deleted, the answer names
|
|
776
|
+
no log path (each `details.hooks` entry's `log` is `null`) and says to run
|
|
777
|
+
the setup with `oats worktree add` in an existing instance to see its
|
|
778
|
+
output; a quarantined home keeps its logs, and the answer names them;
|
|
779
|
+
- at `oats worktree add`, the tree is removed. The branch is deleted only
|
|
780
|
+
when that `add` created it, no worktree has it checked out, and it is
|
|
781
|
+
still where `add` created it.
|
|
782
|
+
|
|
783
|
+
Both exit nonzero, naming the capability and its log. `oats worktree add`
|
|
784
|
+
refuses with `E_REQUIRED_HOOK_FAILED` (`E_HOOK_ENVIRONMENT_CONTRACT` for an
|
|
785
|
+
`env` answer); `oats spawn` fails as for a required spawn hook.
|
|
786
|
+
- A hook that removes or moves the tree fails the check that follows the
|
|
787
|
+
hooks: a failure when any hook is required, else a warning.
|
|
788
|
+
- SIGINT, SIGTERM or SIGHUP to the kernel while the hooks run ends the running
|
|
789
|
+
hook's group, rolls back as for a required failure, and exits 128 + the
|
|
790
|
+
signal number with `E_INTERRUPTED`. A parent killed with SIGKILL leaves a
|
|
791
|
+
record the next command completes: the `creating` tree record for `add`
|
|
792
|
+
(the next `oats worktree add` or `remove` of that purpose rolls it back), or
|
|
793
|
+
the spawn's [in-progress marker](#manifest) for a spawn (`oats retire`).
|
|
794
|
+
That recovery signals the hook process group the killed parent left only
|
|
795
|
+
while the group's leader runs with its recorded start time. A group whose
|
|
796
|
+
leader has exited is never signalled, because its id may already belong to
|
|
797
|
+
another group. The recovery reports it in a warning, and any leftover
|
|
798
|
+
processes are ended by hand. A group that still has members while its
|
|
799
|
+
leader's start cannot be read (where `ps` fails) is not signalled either,
|
|
800
|
+
and the recovery does not go on past it: the leader may still be that hook,
|
|
801
|
+
or that git step. `add`, `remove` and `oats retire` refuse with
|
|
802
|
+
`E_LIFECYCLE_BUSY` and keep the record, naming the group, its recorded
|
|
803
|
+
start and the way out: check the group by hand and, if it is that hook or
|
|
804
|
+
git step, end it (`kill -TERM -- -<pgid>`) and retry. If it is not, remove
|
|
805
|
+
the record named in the message (for `add` and `remove`), or run `oats retire
|
|
806
|
+
<instance> --force`, which then keeps the branch.
|
|
807
|
+
|
|
808
|
+
**Leave the tree clean.** `oats worktree remove` refuses a tree with
|
|
809
|
+
uncommitted changes (`E_WORKTREE_DIRTY`). So a hook should leave the tree
|
|
810
|
+
clean: an install that does not rewrite the lockfile (`npm ci`, `yarn install
|
|
811
|
+
--immutable`, not a plain `npm install`), and outputs that are gitignored. A
|
|
812
|
+
hook that has to change tracked files says so in its capability's brief.
|
|
813
|
+
|
|
814
|
+
**Environment.** The standard hook variables above, and:
|
|
815
|
+
|
|
816
|
+
| Variable | Value |
|
|
817
|
+
|---|---|
|
|
818
|
+
| `OATS_TREE` | the absolute canonical path of the new tree |
|
|
819
|
+
| `OATS_TREE_CLONE` | the absolute path of the clone the tree was added from |
|
|
820
|
+
| `OATS_TREE_REMOTE` | the clone's `origin` URL, without credentials (below) |
|
|
821
|
+
| `OATS_TREE_MEMBER` | the member repository key, or empty (below) |
|
|
822
|
+
| `OATS_BRANCH` | the branch the tree was created on |
|
|
823
|
+
| `OATS_TREE_BASE` | the base as given: `--base`, or the spawn's planned base ref |
|
|
824
|
+
| `OATS_TREE_BASE_OID` | the commit the tree's HEAD is at when the hook starts |
|
|
825
|
+
| `OATS_PURPOSE` | the `--purpose`; empty for `./work` |
|
|
826
|
+
| `OATS_TREE_ORIGIN` | `spawn` or `add` |
|
|
827
|
+
|
|
828
|
+
`OATS_TREE_MEMBER` is never inferred over the network:
|
|
829
|
+
|
|
830
|
+
- `oats worktree add --repo <key>`: that key;
|
|
831
|
+
- `oats worktree add` without `--repo`: the soul's member key, when the
|
|
832
|
+
clone's local remotes name that repository;
|
|
833
|
+
- `oats worktree add --repo <path>`: empty;
|
|
834
|
+
- a spawn: the soul's member key, when the clone is a clone of the soul's
|
|
835
|
+
repository; else empty.
|
|
836
|
+
|
|
837
|
+
`OATS_TREE_REMOTE` never carries a credential. For a URL-style remote
|
|
838
|
+
(`scheme://userinfo@host/...`), the whole userinfo (`user:password@` or
|
|
839
|
+
`token@`) is dropped; for an scp-style remote (`user@host:path`), the `user@`
|
|
840
|
+
is dropped. `https://user:tok@host/org/r.git` becomes
|
|
841
|
+
`https://host/org/r.git`, and `git@host:org/r.git` becomes `host:org/r.git`.
|
|
842
|
+
The kernel records, prints, logs and passes on only this form: the hook
|
|
843
|
+
environment, the tree record, the instance event and the receipt.
|
|
844
|
+
|
|
845
|
+
**The environment is inherited.** As for every hook, the hook runs with the
|
|
846
|
+
environment of whoever ran the command; inside an instance session that is
|
|
847
|
+
the session's own. The kernel adds no credentials. A hook that needs a
|
|
848
|
+
registry token or a deploy key gets it from that environment, or from its
|
|
849
|
+
own configuration.
|
|
850
|
+
|
|
851
|
+
**Adoption.** A kernel before 0.49.0 refuses a manifest that declares
|
|
852
|
+
`hooks.worktree`, and with it the whole capability. In order:
|
|
853
|
+
|
|
854
|
+
1. Upgrade the kernel on **every host that composes the capability**.
|
|
855
|
+
2. Only then declare `hooks.worktree`, with `compatibility.oats:
|
|
856
|
+
">=0.49.0"`, so an older host refuses with `E_CAPABILITY_INCOMPATIBLE`
|
|
857
|
+
naming the release, not with a schema error.
|
|
858
|
+
3. The blast radius is every soul that composes the capability, on every host
|
|
859
|
+
below the release: one capability can stop every developer soul of a
|
|
860
|
+
workspace from spawning, as in lfx-oats-workspace#22, where one capability
|
|
861
|
+
took down every developer soul.
|
|
862
|
+
4. To limit it, put the hook in a small capability composed only by the souls
|
|
863
|
+
that need the setup.
|
|
864
|
+
5. Declare it `required` when the tree is unusable without the setup.
|
|
865
|
+
|
|
618
866
|
## Official packages
|
|
619
867
|
|
|
620
868
|
The official packages and the capabilities and souls each carries are listed
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"OptionalHook": {
|
|
25
25
|
"oneOf":[
|
|
26
26
|
{"type":"string"},
|
|
27
|
-
{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"const":false,"description":"Only the
|
|
27
|
+
{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"const":false,"description":"Only the spawn and worktree hooks may be required."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
|
|
28
28
|
]
|
|
29
29
|
}
|
|
30
30
|
},
|
|
@@ -259,9 +259,17 @@
|
|
|
259
259
|
]
|
|
260
260
|
},
|
|
261
261
|
"retire": {"$ref":"#/$defs/OptionalHook"},
|
|
262
|
-
"launch": {"$ref":"#/$defs/OptionalHook"}
|
|
262
|
+
"launch": {"$ref":"#/$defs/OptionalHook"},
|
|
263
|
+
"worktree": {
|
|
264
|
+
"description": "Runs once in each tree the kernel creates: ./work of a work: worktree spawn (after the spawn hooks) and each `oats worktree add`. Its cwd is the new tree; see docs/capabilities.md, The worktree event.",
|
|
265
|
+
"oneOf":[
|
|
266
|
+
{"type":"string"},
|
|
267
|
+
{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string"},"required":{"type":"boolean","description":"When true, a failure or timeout fails the spawn, or removes the tree `oats worktree add` made."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
|
|
268
|
+
]
|
|
269
|
+
}
|
|
263
270
|
},
|
|
264
|
-
"additionalProperties":
|
|
271
|
+
"additionalProperties": {"$ref":"#/$defs/OptionalHook"},
|
|
272
|
+
"description": "Lifecycle events to commands. An event this kernel does not run (a newer kernel's) is accepted with a warning and ignored, unless it is declared required: that is refused. Kernels before 0.49.0 refuse every unknown event."
|
|
265
273
|
},
|
|
266
274
|
"settings": {
|
|
267
275
|
"type": "object",
|
|
@@ -320,10 +328,15 @@
|
|
|
320
328
|
},
|
|
321
329
|
"work": {
|
|
322
330
|
"type": "array",
|
|
323
|
-
"description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made.",
|
|
331
|
+
"description": "Relative roots under work/ that a worktree instance's capability generates. Their untracked or ignored bytes do not count as the instance's untracked or ignored worktree bytes; they are still copied when a recovery copy is made. A backslash reads as /, one leading ./ and one trailing / are dropped, and what is left must be a relative path with no empty, . or .. segment; an absolute path (/x, C:/x) is refused. Two entries of one manifest that overlap (the same root, or one inside the other) are refused; spawn also refuses roots of different capabilities that overlap, and a root that is a symlink in the work.",
|
|
324
332
|
"items": {
|
|
325
333
|
"type": "string",
|
|
326
|
-
"minLength": 1
|
|
334
|
+
"minLength": 1,
|
|
335
|
+
"pattern": "^(?:\\.[/\\\\])?(?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+(?:[/\\\\](?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+)*[/\\\\]?$",
|
|
336
|
+
"not": {
|
|
337
|
+
"description": "A Windows absolute path is refused on every host.",
|
|
338
|
+
"pattern": "^[A-Za-z]:[/\\\\]"
|
|
339
|
+
}
|
|
327
340
|
}
|
|
328
341
|
}
|
|
329
342
|
},
|
package/docs/configuration.md
CHANGED
|
@@ -101,6 +101,12 @@ default. A home not yet created uses its resolved existing directory ancestor
|
|
|
101
101
|
plus its intended suffix; launch checks the created home's identity again.
|
|
102
102
|
No existing home is enabled automatically. Removing an entry disables consent
|
|
103
103
|
for future launches.
|
|
104
|
+
On a case-insensitive filesystem (the macOS default) one home has several
|
|
105
|
+
letter-case spellings, and a key in any of them is valid. A key spelled exactly
|
|
106
|
+
as the home is launched decides. Otherwise the single key naming the same
|
|
107
|
+
directory decides, and `consentSource` points at that key. Several keys naming
|
|
108
|
+
it in different case, with none spelled exactly, decide nothing: no consent.
|
|
109
|
+
Consent never reaches another directory.
|
|
104
110
|
|
|
105
111
|
The sole confirmation covered is Claude's development-channel prompt for
|
|
106
112
|
`plugin:aweb-channel@awebai-marketplace`. The provider's `claudeChannelMode`
|