@awebai/oats 0.48.0 → 0.50.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.
Files changed (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -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 `retire`. A hook is a
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`**: the hook's failure then fails the spawn and rolls it back,
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. Every other hook stays best-effort and only warns, so advisory
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. While the branch the failed spawn created
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) or `/retirement/disposable/home/<i>` (an entry outside the
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
@@ -246,6 +353,9 @@ A self-contained package has an `oats.json`:
246
353
  separate from declaring the package.
247
354
  - `environment` lists the exact launch variables the capability may set;
248
355
  spawn hook output must be a subset and use the capability vendor prefix.
356
+ - `triggerSources` (optional) declares the capability's
357
+ [trigger sources](#trigger-sources-triggersources). It is checked only
358
+ where a source is used, never when the capability loads.
249
359
  - Target names never appear in a package manifest.
250
360
 
251
361
  `capability` is the only manifest identity field; it may also carry
@@ -441,7 +551,8 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
441
551
  `OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
442
552
  `OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
443
553
  preview (only a preview-aware hook does, below); on a real run
444
- `OATS_LAUNCH_PREVIEW` is not set.
554
+ `OATS_LAUNCH_PREVIEW` is not set. A worktree hook also gets the tree
555
+ variables of [The worktree event](#the-worktree-event).
445
556
 
446
557
  A dispatched command (`oats <namespace> <command>`, from an instance home or
447
558
  from the deployment directory) receives:
@@ -483,7 +594,8 @@ a home with none recorded gives `{}`. A final JSON line may return `meta`,
483
594
  `brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
484
595
  launch hook's preview answer may add `volatileEnv` (below). A **spawn or
485
596
  launch hook** may also return an `env` object for the launched process;
486
- returning `env` from a retire hook is an explicit contract error.
597
+ returning `env` from a retire or [worktree](#the-worktree-event) hook is an
598
+ explicit contract error.
487
599
 
488
600
  A **launch hook** runs at every start and restart of a home for each provider
489
601
  recorded at spawn (under its recorded settings). Its `launch` arguments and
@@ -615,6 +727,145 @@ Spawn order is by capability name; retirement reverses successful
615
727
  spawn order. Hooks run from the instance's own copy
616
728
  (`<home>/.oats/modules/<cap>/`).
617
729
 
730
+ ### The worktree event
731
+
732
+ `OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
733
+ kernel has just created: install dependencies, link environment files, pin
734
+ a toolchain. The kernel runs only the hooks of the instance's own
735
+ capabilities; it runs no code from the repository.
736
+
737
+ **When it fires.** Once for each tree the kernel creates:
738
+
739
+ - `./work` of a `work: worktree` spawn, after the spawn hooks succeed and
740
+ inside the spawn's transaction;
741
+ - each extra tree `oats worktree add` makes
742
+ ([extra trees](souls-and-instances.md#extra-trees)).
743
+
744
+ It never fires for a `checkout`, `attached`, `workspace` or `directory`
745
+ `./work`, for a tree made with raw Git, or at start, restart, resume or
746
+ retire. `oats worktree remove` fires no hook. An `add` that finds its tree
747
+ already made (same clone, branch and base) runs no hook again.
748
+
749
+ **How it runs.** Hooks run in capability-name order, from the module copy,
750
+ like every hook. Other events keep their own behaviour (120 s, buffered,
751
+ cwd the home); this one differs:
752
+
753
+ - **cwd is the new tree.** `OATS_TREE` names it too.
754
+ - stdin is `/dev/null`, with no terminal.
755
+ - The hook is started detached, in its own process group, so a timeout or an
756
+ interrupt ends the whole group.
757
+ - stdout and stderr go to `<home>/.oats/logs/worktree-<purpose>-<cap>.log`
758
+ (`worktree-work-<cap>.log` for `./work`), created 0600 and truncated on each
759
+ run. On `oats worktree add` they are also copied to the kernel's stderr,
760
+ never its stdout: `--json` prints only the envelope. A caller that closes
761
+ its end of stderr or stdout (a tool shell killed, Desktop gone) only stops
762
+ the copy: the hooks and the add run to their end, and the log is whole. The log holds whatever
763
+ the hook printed, so its content never enters any JSON answer, receipt,
764
+ record, marker or instance event: they carry the log's path only. The
765
+ `warning` of the hook's last JSON line is the one piece of its output that
766
+ may surface.
767
+ - The timeout is 30 minutes, fixed. At the timeout the kernel sends the group
768
+ SIGTERM, then SIGKILL after a short grace.
769
+ - The result is the exit status. Of the last stdout line's JSON only
770
+ `warning` is read. Returning `env` is a contract error
771
+ (`E_HOOK_ENVIRONMENT_CONTRACT`), as at retire; `meta`, `brief` and `launch`
772
+ are ignored.
773
+ - A non-required hook that fails or times out is a warning; the tree is kept.
774
+ A required one (`{ command, required: true }`) fails closed:
775
+ - at spawn, it fails the spawn through the required-hook rollback above
776
+ (retire hooks compensate in reverse, the worktree-mode Git state is
777
+ removed and verified, and the home is deleted, or kept as a quarantine).
778
+ The hook's log was in that home: once it is deleted, the answer names
779
+ no log path (each `details.hooks` entry's `log` is `null`) and says to run
780
+ the setup with `oats worktree add` in an existing instance to see its
781
+ output; a quarantined home keeps its logs, and the answer names them;
782
+ - at `oats worktree add`, the tree is removed. The branch is deleted only
783
+ when that `add` created it, no worktree has it checked out, and it is
784
+ still where `add` created it.
785
+
786
+ Both exit nonzero, naming the capability and its log. `oats worktree add`
787
+ refuses with `E_REQUIRED_HOOK_FAILED` (`E_HOOK_ENVIRONMENT_CONTRACT` for an
788
+ `env` answer); `oats spawn` fails as for a required spawn hook.
789
+ - A hook that removes or moves the tree fails the check that follows the
790
+ hooks: a failure when any hook is required, else a warning.
791
+ - SIGINT, SIGTERM or SIGHUP to the kernel while the hooks run ends the running
792
+ hook's group, rolls back as for a required failure, and exits 128 + the
793
+ signal number with `E_INTERRUPTED`. A parent killed with SIGKILL leaves a
794
+ record the next command completes: the `creating` tree record for `add`
795
+ (the next `oats worktree add` or `remove` of that purpose rolls it back), or
796
+ the spawn's [in-progress marker](#manifest) for a spawn (`oats retire`).
797
+ That recovery signals the hook process group the killed parent left only
798
+ while the group's leader runs with its recorded start time. A group whose
799
+ leader has exited is never signalled, because its id may already belong to
800
+ another group. The recovery reports it in a warning, and any leftover
801
+ processes are ended by hand. A group that still has members while its
802
+ leader's start cannot be read (where `ps` fails) is not signalled either,
803
+ and the recovery does not go on past it: the leader may still be that hook,
804
+ or that git step. `add`, `remove` and `oats retire` refuse with
805
+ `E_LIFECYCLE_BUSY` and keep the record, naming the group, its recorded
806
+ start and the way out: check the group by hand and, if it is that hook or
807
+ git step, end it (`kill -TERM -- -<pgid>`) and retry. If it is not, remove
808
+ the record named in the message (for `add` and `remove`), or run `oats retire
809
+ <instance> --force`, which then keeps the branch.
810
+
811
+ **Leave the tree clean.** `oats worktree remove` refuses a tree with
812
+ uncommitted changes (`E_WORKTREE_DIRTY`). So a hook should leave the tree
813
+ clean: an install that does not rewrite the lockfile (`npm ci`, `yarn install
814
+ --immutable`, not a plain `npm install`), and outputs that are gitignored. A
815
+ hook that has to change tracked files says so in its capability's brief.
816
+
817
+ **Environment.** The standard hook variables above, and:
818
+
819
+ | Variable | Value |
820
+ |---|---|
821
+ | `OATS_TREE` | the absolute canonical path of the new tree |
822
+ | `OATS_TREE_CLONE` | the absolute path of the clone the tree was added from |
823
+ | `OATS_TREE_REMOTE` | the clone's `origin` URL, without credentials (below) |
824
+ | `OATS_TREE_MEMBER` | the member repository key, or empty (below) |
825
+ | `OATS_BRANCH` | the branch the tree was created on |
826
+ | `OATS_TREE_BASE` | the base as given: `--base`, or the spawn's planned base ref |
827
+ | `OATS_TREE_BASE_OID` | the commit the tree's HEAD is at when the hook starts |
828
+ | `OATS_PURPOSE` | the `--purpose`; empty for `./work` |
829
+ | `OATS_TREE_ORIGIN` | `spawn` or `add` |
830
+
831
+ `OATS_TREE_MEMBER` is never inferred over the network:
832
+
833
+ - `oats worktree add --repo <key>`: that key;
834
+ - `oats worktree add` without `--repo`: the soul's member key, when the
835
+ clone's local remotes name that repository;
836
+ - `oats worktree add --repo <path>`: empty;
837
+ - a spawn: the soul's member key, when the clone is a clone of the soul's
838
+ repository; else empty.
839
+
840
+ `OATS_TREE_REMOTE` never carries a credential. For a URL-style remote
841
+ (`scheme://userinfo@host/...`), the whole userinfo (`user:password@` or
842
+ `token@`) is dropped; for an scp-style remote (`user@host:path`), the `user@`
843
+ is dropped. `https://user:tok@host/org/r.git` becomes
844
+ `https://host/org/r.git`, and `git@host:org/r.git` becomes `host:org/r.git`.
845
+ The kernel records, prints, logs and passes on only this form: the hook
846
+ environment, the tree record, the instance event and the receipt.
847
+
848
+ **The environment is inherited.** As for every hook, the hook runs with the
849
+ environment of whoever ran the command; inside an instance session that is
850
+ the session's own. The kernel adds no credentials. A hook that needs a
851
+ registry token or a deploy key gets it from that environment, or from its
852
+ own configuration.
853
+
854
+ **Adoption.** A kernel before 0.49.0 refuses a manifest that declares
855
+ `hooks.worktree`, and with it the whole capability. In order:
856
+
857
+ 1. Upgrade the kernel on **every host that composes the capability**.
858
+ 2. Only then declare `hooks.worktree`, with `compatibility.oats:
859
+ ">=0.49.0"`, so an older host refuses with `E_CAPABILITY_INCOMPATIBLE`
860
+ naming the release, not with a schema error.
861
+ 3. The blast radius is every soul that composes the capability, on every host
862
+ below the release: one capability can stop every developer soul of a
863
+ workspace from spawning, as in lfx-oats-workspace#22, where one capability
864
+ took down every developer soul.
865
+ 4. To limit it, put the hook in a small capability composed only by the souls
866
+ that need the setup.
867
+ 5. Declare it `required` when the tree is unusable without the setup.
868
+
618
869
  ## Official packages
619
870
 
620
871
  The official packages and the capabilities and souls each carries are listed
@@ -1016,3 +1267,169 @@ checks in one readiness read share 60 s, and checks the budget does not reach
1016
1267
  are not run (`unknown`, `time-budget-exhausted`). Answer from configuration
1017
1268
  and local state. A provider that must call a remote service should bound that
1018
1269
  call well inside the 30 s.
1270
+
1271
+ ## Trigger sources (`triggerSources`)
1272
+
1273
+ A capability may declare **trigger sources**: each is one of its own commands
1274
+ that, at each poll, lists the events that are due now. A
1275
+ [trigger](schedules.md#capability-sources) names one as `on.source:
1276
+ "<capability>:<source>"`, and the kernel keeps everything after the list:
1277
+ event keys, at-least-once recording, pending events, concurrency, the
1278
+ instance name, the event file and the spawn.
1279
+
1280
+ ```json
1281
+ "commands": { "review-source": "bin/graph.mjs review-source" },
1282
+ "triggerSources": {
1283
+ "harvest-branches": {
1284
+ "command": "review-source",
1285
+ "description": "Ready harvest/* branches, one event per judged head",
1286
+ "events": ["opened", "updated"],
1287
+ "parameters": { "prefix": { "default": "harvest/", "description": "Branch prefix", "pattern": "^[A-Za-z0-9._/-]{1,80}$" } },
1288
+ "fields": { "graph": { "pattern": "^[a-z0-9-]{1,40}$" }, "branch": {} },
1289
+ "urlHosts": ["graph.example.org"]
1290
+ }
1291
+ }
1292
+ ```
1293
+
1294
+ - **The source name** is 1 to 40 lowercase letters, digits and dashes,
1295
+ starting with a letter or digit. At most 16 sources.
1296
+ - **`command`** names one of `commands`. Its script must resolve to a regular
1297
+ file inside the module directory.
1298
+ - **`description`** (optional): one line of at most 200 characters.
1299
+ - **`events`**: 1 to 16 distinct names, each 1 to 40 lowercase letters,
1300
+ digits and underscores, starting with a letter.
1301
+ - **`parameters`** (optional, at most 16), named with a letter then letters,
1302
+ digits and underscores (at most 40): `{ required?, default?, description?,
1303
+ pattern? }`. A value is a string of at most 200 characters matching
1304
+ `pattern`, by default `^[A-Za-z0-9._/:@ ,*-]{0,200}$`; a `default` must
1305
+ match it too. Parameters reach the source only, never a task.
1306
+ - **`fields`** (optional, at most 16, named as parameters): `{ pattern? }`, by
1307
+ default `^[A-Za-z0-9._/:@-]{1,200}$`. A trigger's template may name a
1308
+ declared field as `{fields.<name>}`; the value is the event's, validated.
1309
+ Whatever the pattern admits (`.*` included), a value longer than 200
1310
+ characters (code points), or carrying a control character, a line or
1311
+ paragraph separator, a bidi control, U+200B, U+2060, U+FEFF or a tag
1312
+ character, makes its event invalid, and the pattern is never run on one.
1313
+ - **Patterns** are JavaScript regular expressions with the `u` flag (the flag
1314
+ JSON Schema's `pattern` uses), compiled once and always matched whole: the
1315
+ kernel wraps each as `^(?:…)$`. One that does not compile makes the source
1316
+ malformed.
1317
+ - **`urlHosts`** (optional, at most 16): the exact lowercase hostnames an
1318
+ event's `url` may name. With none declared, an event's `url` is invalid.
1319
+ The allow-list lives here, never on an event. An event's `url` must also be
1320
+ printable ASCII with no space (`0x21`–`0x7e`) as written: percent-encode
1321
+ anything else.
1322
+
1323
+ **Containment.** A malformed `triggerSources` **never refuses the
1324
+ capability**. It is not part of the manifest contract that spawn, discovery
1325
+ and the lock check: they ignore it. It is validated only where a source is
1326
+ used, by `trigger add`, a poll, `trigger test` and `trigger poll`, **per
1327
+ source**: a malformed source fails only the triggers naming it
1328
+ (`E_TRIGGER_SOURCE`, `details: { capability, source, pointer }`, the pointer
1329
+ into the manifest), and a well-formed sibling keeps working. A malformed top
1330
+ level (not an object, or more than 16 sources) fails every trigger naming the
1331
+ capability. `oats capabilities show <name> --json` adds `triggerSources`,
1332
+ exactly as declared, and, when the declaration has any, the problems a trigger
1333
+ would get as `triggerSourceProblems: [{ source, pointer, message }]`
1334
+ (`source` `null` for the top level); it never refuses the command. The
1335
+ closed sub-schema is in
1336
+ [`capability-manifest.schema.json`](capability-manifest.schema.json); what a
1337
+ schema cannot say (a pattern compiles, `command` names a command, a default
1338
+ matches its pattern) is checked at use only.
1339
+
1340
+ **Schema tooling.** The runtime ignores manifest keys it does not know, but
1341
+ until this release the published `capability-manifest.schema.json` was closed
1342
+ at the top level (`additionalProperties: false`). A tool validating a manifest
1343
+ against an older copy of the schema flags `triggerSources`: the repository's
1344
+ own `validate-project`, the package dry-run checks, a provider's CI that pins
1345
+ the schema. Validate against this release's schema, or declare the key once
1346
+ your tooling uses it. A provider declaring `triggerSources` does not need to
1347
+ raise `compatibility.oats`: every workspace-model kernel ignores the key, and
1348
+ only the host that runs a trigger naming the source needs this release.
1349
+
1350
+ **Invocation.** A poll runs the command's script with `node`, from the
1351
+ capability's directory in the deployment's verified module store (the
1352
+ capability at its resolved commit, digest-verified, for a member capability
1353
+ as for a package one), with the command's words after the script as
1354
+ arguments and no shell. The host tick runs it through a child `oats trigger
1355
+ poll <id> --run-source --max-age 600`; a person, through `oats trigger poll
1356
+ <id> --run-source` or `oats trigger test <id> --run-source`. Those
1357
+ **execute the capability's source command** whatever the host's trust and
1358
+ the trigger's `runsOn` say, and so only with `--run-source`: without it they
1359
+ are refused (`E_TRIGGER_SOURCE_RUN`) before anything of the capability runs
1360
+ or is written. The flag is caller intent, never trust consent: see
1361
+ [schedules.md](schedules.md#capability-sources). A poll records nothing on
1362
+ its own; the tick records what it folds.
1363
+
1364
+ **Request** — one JSON document on stdin, with exactly these keys:
1365
+
1366
+ ```json
1367
+ {"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","trigger":"local/harvest-review",
1368
+ "params":{"prefix":"harvest/"},"settings":{"store":"~/.graph"},
1369
+ "input":{"context":{"kind":"workspace","workspace":"github.com/acme/agents","deployment":"/srv/acme",
1370
+ "soul":"graph-reviewer","host":"kb-bot-server"}}}
1371
+ ```
1372
+
1373
+ - `trigger` is the qualified trigger id.
1374
+ - `params` are the trigger's, with the declared defaults applied (a parameter
1375
+ with neither a value nor a default is absent).
1376
+ - `settings` is the merged provider payload the trigger's soul resolves for
1377
+ the capability.
1378
+ - `host` is this host's `host.name`, or `null`.
1379
+
1380
+ **Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
1381
+ gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
1382
+ variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
1383
+ `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_WORKSPACE`,
1384
+ the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and `OATS_SOUL`. There is no
1385
+ `OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
1386
+ Under the host timer, the inherited environment is the timer's (only `PATH`
1387
+ and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
1388
+ not in an exported variable.
1389
+
1390
+ **Answer** — exit 0, and exactly one JSON document on stdout, at most 1 MiB
1391
+ (whitespace around it is fine; progress text is not):
1392
+
1393
+ ```json
1394
+ {"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","ok":true,
1395
+ "result":{"events":[{"key":"harvest/x:9f2c41d","subject":"harvest/x","event":"opened",
1396
+ "url":"https://graph.example.org/x","fields":{"graph":"kb","branch":"harvest/x"}}],
1397
+ "skipped":[{"subject":"harvest/y","why":"not judged yet"}]}}
1398
+ ```
1399
+
1400
+ - **The envelope** has exactly `schemaVersion, phase, capability, source, ok,
1401
+ result`; `schemaVersion`, `phase`, `capability` and `source` echo the
1402
+ request. `result` is `{ events, skipped? }`, exactly.
1403
+ - **A refusal** is `{…, "ok": false, "error": { "code", "message"? }}`.
1404
+ - **An event** is `{ key, subject, event, url?, fields? }`: the rules are in
1405
+ [schedules.md](schedules.md#capability-sources). An invalid event is
1406
+ dropped alone; the others go on.
1407
+ - **`skipped`** (optional) is `[{ subject, why }]`: what the source looked at
1408
+ and chose not to list, shown in `trigger status` and `trigger test`.
1409
+
1410
+ | Outcome | `E_TRIGGER_POLL` `details.cause` | recorded |
1411
+ |---|---|---|
1412
+ | nonzero exit or a signal | `exit` | nothing; pending events kept |
1413
+ | not exactly one JSON document, unknown keys, a wrong echo, a malformed `result`, over 1 MiB | `result` | nothing |
1414
+ | more than 500 events, or more than 100 skipped | `too-many-events` | nothing |
1415
+ | over 30 s (killed) | `timeout` | nothing |
1416
+ | `ok: false` | `refused`, with `details.source: { code, message? }` | nothing |
1417
+ | the soul does not resolve | `resolution` | nothing |
1418
+ | the trigger's meaning does not hold | (`E_TRIGGER_SOURCE` / `E_TRIGGER_INVALID`) | nothing; the source does not run |
1419
+
1420
+ **Your text is untrusted.** A skipped item's `why`, a refusal's `message` and
1421
+ its `code` are never composed into a task or any kernel sentence. They are
1422
+ kept only in fields that name the source and printed under `source says:`,
1423
+ capped (`why` 200 characters, `message` 500, `code` 128) and with every
1424
+ control character, line or paragraph separator, bidi control, U+200B,
1425
+ U+2060, U+FEFF and tag character replaced by U+FFFD. What a task may carry
1426
+ (`{subject}`, `{key}`, `{url}`, `{fields.<name>}`) is refused rather than
1427
+ replaced: an event whose `url` is not printable ASCII, or whose field value
1428
+ is longer than 200 characters or carries one of those characters whatever
1429
+ its pattern admits, is an invalid event.
1430
+
1431
+ **Time.** A source gets at most 30 s and is killed after that; the tick's
1432
+ whole poll, resolution included, gets 35 s, and polls run only while they can
1433
+ end within 50 s of the tick's start. Answer from a cache or a quick query: a
1434
+ source slower than that should cache.
1435
+
@@ -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 existing spawn hook may be required."},"inputs":{"$ref":"#/$defs/HookInputs"}}}
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
  },
@@ -248,6 +248,48 @@
248
248
  }
249
249
  }
250
250
  },
251
+ "triggerSources": {
252
+ "description": "Trigger sources (#669): each a command of this capability that, at each poll, lists the events due now; a trigger names one as on.source \"<capability>:<source>\". Validated only where a source is used (trigger add, a poll, trigger test and trigger poll), never when the capability loads: a malformed declaration fails the triggers naming it (E_TRIGGER_SOURCE) and nothing else. Checked at use only, not by this schema: every pattern compiles; command names a key of commands; a parameter default matches its pattern. A pattern is ECMA-262 with the u flag, matched anchored as ^(?:…)$; the default parameter value pattern is ^[A-Za-z0-9._/:@ ,*-]{0,200}$ and the default field pattern ^[A-Za-z0-9._/:@-]{1,200}$. Whatever its pattern admits, an event's field value is at most 200 code points and carries no control, bidi, invisible or tag character.",
253
+ "type": "object",
254
+ "maxProperties": 16,
255
+ "propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]{0,39}$" },
256
+ "additionalProperties": {
257
+ "type": "object",
258
+ "required": ["command", "events"],
259
+ "additionalProperties": false,
260
+ "properties": {
261
+ "command": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "One of this manifest's commands: the source's program, run once per poll (one JSON request on stdin, one JSON answer on stdout)." },
262
+ "description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
263
+ "events": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } },
264
+ "parameters": {
265
+ "type": "object",
266
+ "maxProperties": 16,
267
+ "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
268
+ "additionalProperties": {
269
+ "type": "object",
270
+ "additionalProperties": false,
271
+ "properties": {
272
+ "required": { "type": "boolean" },
273
+ "default": { "type": "string", "maxLength": 200 },
274
+ "description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
275
+ "pattern": { "type": "string", "minLength": 1 }
276
+ }
277
+ }
278
+ },
279
+ "fields": {
280
+ "type": "object",
281
+ "maxProperties": 16,
282
+ "propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
283
+ "additionalProperties": {
284
+ "type": "object",
285
+ "additionalProperties": false,
286
+ "properties": { "pattern": { "type": "string", "minLength": 1 } }
287
+ }
288
+ },
289
+ "urlHosts": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "maxLength": 253, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$" } }
290
+ }
291
+ }
292
+ },
251
293
  "hooks": {
252
294
  "type": "object",
253
295
  "properties": {
@@ -259,9 +301,17 @@
259
301
  ]
260
302
  },
261
303
  "retire": {"$ref":"#/$defs/OptionalHook"},
262
- "launch": {"$ref":"#/$defs/OptionalHook"}
304
+ "launch": {"$ref":"#/$defs/OptionalHook"},
305
+ "worktree": {
306
+ "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.",
307
+ "oneOf":[
308
+ {"type":"string"},
309
+ {"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"}}}
310
+ ]
311
+ }
263
312
  },
264
- "additionalProperties": false
313
+ "additionalProperties": {"$ref":"#/$defs/OptionalHook"},
314
+ "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
315
  },
266
316
  "settings": {
267
317
  "type": "object",
@@ -320,10 +370,15 @@
320
370
  },
321
371
  "work": {
322
372
  "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.",
373
+ "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
374
  "items": {
325
375
  "type": "string",
326
- "minLength": 1
376
+ "minLength": 1,
377
+ "pattern": "^(?:\\.[/\\\\])?(?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+(?:[/\\\\](?!\\.{1,2}(?:[/\\\\]|$))[^/\\\\]+)*[/\\\\]?$",
378
+ "not": {
379
+ "description": "A Windows absolute path is refused on every host.",
380
+ "pattern": "^[A-Za-z]:[/\\\\]"
381
+ }
327
382
  }
328
383
  }
329
384
  },