@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.
Files changed (41) hide show
  1. package/bin/oats.mjs +226 -14
  2. package/docs/capabilities.md +256 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +6 -0
  5. package/docs/desktop-cli-api.md +368 -31
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +17 -2
  8. package/docs/implementation.md +62 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +2 -2
  12. package/docs/packages.md +8 -8
  13. package/docs/release-notes/v0.49.0.md +770 -0
  14. package/docs/schedules.md +62 -39
  15. package/docs/servers.md +7 -0
  16. package/docs/souls-and-instances.md +381 -53
  17. package/docs/workspaces.md +2 -2
  18. package/injects/work-checkout.md +17 -11
  19. package/injects/work-worktree.md +19 -13
  20. package/lib/capability-contract.mjs +100 -11
  21. package/lib/capability-show.mjs +5 -2
  22. package/lib/core.mjs +1109 -321
  23. package/lib/instance-events.mjs +6 -3
  24. package/lib/instance-git.mjs +11 -5
  25. package/lib/instance-inspect.mjs +14 -3
  26. package/lib/instance-lifecycle.mjs +106 -16
  27. package/lib/instance-resolution.mjs +15 -3
  28. package/lib/launch-prompt-policy.mjs +17 -3
  29. package/lib/packages.mjs +1 -0
  30. package/lib/real-path.mjs +27 -0
  31. package/lib/resolve.mjs +4 -4
  32. package/lib/retire-output.mjs +6 -1
  33. package/lib/schedule.mjs +1 -0
  34. package/lib/servers.mjs +32 -6
  35. package/lib/tree-copy.mjs +18 -7
  36. package/lib/triggers.mjs +201 -65
  37. package/lib/workspace.mjs +20 -5
  38. package/lib/worktree-hooks.mjs +392 -0
  39. package/lib/worktree.mjs +655 -0
  40. package/package-catalog.json +1 -1
  41. package/package.json +1 -1
package/docs/schedules.md CHANGED
@@ -61,8 +61,8 @@ the rule is refused, `E_SCHEDULE_INVALID` or `E_TRIGGER_INVALID` with `field:
61
61
  "description"`; a workspace file's header that breaks it is only a warning
62
62
  (see [the header](#workspace-triggers-and-schedules)). It is stored as given
63
63
  and is informational only: it never reaches a run's argv, environment, task,
64
- template or reconcile. A capability that registers jobs (knowledge harvest's
65
- `run-source` jobs) sets it so that its command jobs can be told apart. Set it
64
+ template or reconcile. A capability that registers command jobs can set it
65
+ so operators can tell those jobs apart; oats.okf 5.0 registers none. Set it
66
66
  in the definition or with `--description=<text>` on `add`; change only it with
67
67
  `update <id> --description=<text>` (see [Commands](#commands)). Local triggers
68
68
  take it from OATS 0.43.0 (feature `automation-descriptions`); an older kernel
@@ -165,11 +165,17 @@ when the timer cannot reach it.
165
165
  **only after a successful spawn**. Until then the event stays pending, is
166
166
  retried at every poll, and is dropped when its PR closes. A tick that dies
167
167
  between the spawn and the record spawns the event again on the next poll
168
- (held by `perKey` while the first instance lives), so a trigger's soul
168
+ (held by `perKey` while the first instance lives, under the same name with
169
+ spawn's `-2`), so a trigger's soul
169
170
  should tolerate a second run on the same event.
171
+ - **Subject.** Each event has a `subject`, the thing it is about: a PR's
172
+ number, as a string. Two events of one PR (an `opened` and a later
173
+ `synchronize`) have different keys and one subject.
170
174
  - **Concurrency.** `max` (default 1) bounds the trigger's live instances and
171
- `perKey` (default 1) those of one PR, counted from the homes'
172
- `instance.json.trigger` records; a retired instance frees its slot. An event
175
+ `perKey` (default 1) those of one subject (a PR's number), counted from the
176
+ homes' `instance.json.trigger` records (a home spawned before 0.49.0 records
177
+ no subject and counts by its PR's repo and number); a retired instance frees
178
+ its slot. An event
173
179
  over a bound stays pending (`held`). A newer push supersedes a pending
174
180
  `synchronize` for an older head of the same PR.
175
181
  - **The spawn** is `oats spawn`. `soul` is bare or qualified
@@ -180,9 +186,29 @@ when the timer cannot reach it.
180
186
  setting (`E_TRIGGER_TEAMS` when the soul has no messaging capability).
181
187
  `launchConfig`, `harness`, `model`, `yolo` and `backend` are as for
182
188
  schedules.
189
+ - **The instance name** is spawn's own: `<stem>-<purpose>`, where the stem is
190
+ the slug of the soul's agent name (a package soul's is
191
+ `<package>--<soul>`, so its stem is long), read from one `oats spawn <soul>
192
+ --preview` (with the trigger's launch selection) per trigger per tick in
193
+ which it fires. Spawn never truncates or
194
+ rewrites a name and refuses one over 64 characters, and it adds `-2`, `-3`, …
195
+ when a name is taken, so the trigger keeps its names to **61 characters**,
196
+ three for that suffix. A name that fits is passed exactly as rendered. A
197
+ longer one gets a cut purpose: as much of the rendered purpose as fits, then
198
+ `-` and the first 6 hex characters of SHA-256 over the event key (two events
199
+ of one PR get different names; the same event, re-fired, the same name).
200
+ When a name needs cutting and the stem leaves no room even for `-<6 hex>`
201
+ (a stem over 54 characters), the event is not spawned: it stays pending
202
+ with `lastError.code: E_INSTANCE_NAME_INVALID`, naming the stem and its
203
+ length. A stem over 62 characters is too long even for the preview's own
204
+ numbered name (`<stem>-1`): it is refused with the same code, as too long
205
+ for a triggered spawn, and the message quotes the preview's refusal (which
206
+ names that numbered name and its length, not the stem's).
207
+ `oats trigger test <id> --json` shows each would-fire event's `instance` and
208
+ `nameCut`. A failed preview fails the spawn the same way, with its own code.
183
209
  - **The event reaches the instance** as `OATS_TRIGGER_EVENT_FILE`
184
- (`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number, url,
185
- event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
210
+ (`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number,
211
+ subject, url, event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
186
212
  harness, and is recorded in `instance.json.trigger`.
187
213
 
188
214
  ```sh
@@ -507,35 +533,32 @@ to its home.
507
533
  fails, the spawn result still carries the instance receipt, plus
508
534
  `wakeScheduleError` and a warning.
509
535
 
510
- ## Knowledge harvest jobs
511
-
512
- oats.okf uses both mechanisms. The flow, the harvest switch and the package
513
- souls are described in [knowledge.md](knowledge.md#knowledge-operations).
514
-
515
- - **Harvest.** A source exists only where harvest is on (`oats-local.yaml`
516
- `settings.oats.okf.harvest: on`; default off). oats.okf then registers one
517
- local **command job per source**, `okf-<source id>`, which runs from the
518
- deployment with argv equivalent to:
519
-
520
- ```text
521
- oats okf run-source --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
522
- ```
523
-
524
- The job spawns the package soul `oats.okf/knowledge-harvester`. The source's
525
- evidence lives outside its home, so the job keeps working after the source
526
- instance retires; once a retired source is drained, oats.okf removes the
527
- job. Registration never re-enables a disabled job.
528
- `oats schedule disable okf-<source id>` is the emergency brake for one
529
- source.
530
- - **Review.** Each harvest PR is reviewed by a new
531
- `oats.okf/knowledge-maintainer`, spawned by a trigger from the package
532
- template `oats.okf:harvest-review`: a workspace file
533
- (`oats-triggers/okf-harvest-review.yaml`) or a local `oats trigger add
534
- --from oats.okf:harvest-review`.
535
-
536
- Registering a source never installs the host timer. `oats okf inspect
537
- --source <source.json> --soul <soul>` reports the job and whether the timer is
538
- actually active; `oats okf setup --source <source.json> --soul <soul>
539
- --install-host` installs it, and `--disable` disables the job without
540
- stopping a running worker. The scheduler's launch receipts do not replace
541
- oats.okf's own processing, delivery and acceptance receipts.
536
+ ## Knowledge harvest and review
537
+
538
+ **oats.okf 5.0 does not schedule harvest jobs.** At important checkpoints a
539
+ working instance updates its notes, writes its own proposal (what to save,
540
+ why, and backing notes), and directly spawns the package harvester:
541
+
542
+ ```sh
543
+ oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
544
+ ```
545
+
546
+ The unrelated harvester can outlive the proposing instance. It checks the
547
+ recorded source and its soul opt-out, accepted knowledge and open/recent
548
+ harvest PRs, then proposes an owned-node change through a normal reviewed
549
+ Git PR. Retirement does not automatically capture or harvest anything.
550
+ There is no host harvest switch, per-source command job, run-source command
551
+ or capture/drain/worker engine. The soul-only `knowledge: { harvest: off }`
552
+ keeps consultation while forbidding harvest of that soul's material.
553
+
554
+ **Review still uses a trigger.** Each harvest PR can be reviewed by
555
+ `oats.okf/knowledge-maintainer`, spawned from the package template
556
+ `oats.okf:harvest-review`: a workspace trigger file or a local
557
+ `oats trigger add --from oats.okf:harvest-review`. This is a PR-review
558
+ trigger, not a harvest scheduler or a kernel PR-opened capture hook.
559
+
560
+ Deployments upgrading from 4.x must settle registered sources before
561
+ changing the pin, then use the 5.0 guard-exempt host-key cleanup before new
562
+ spawns. See the [5.0 cutover sequence](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters). Provider
563
+ behaviour remains in the [oats.okf package](https://github.com/awebai/oats-okf);
564
+ none of this adds provider-specific behaviour to the scheduler or kernel.
package/docs/servers.md CHANGED
@@ -311,6 +311,13 @@ its group from the saved routes. State is pulled on every call within
311
311
  `--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
312
312
  not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.
313
313
 
314
+ The group's `probe` also relays the host's kernel features (0.49.0,
315
+ `probe.features`): the top-level `features` of the same `status --json`
316
+ answer, never a separate `version --json`, kept only when it is a valid list
317
+ of feature names and otherwise `null` (unknown, as from a host before
318
+ 0.49.0); a failed probe has no `features` key
319
+ ([the field](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
320
+
314
321
  **Harvest** runs the knowledge capability's `okf harvest --json` in the
315
322
  instance's saved home on the server and relays its envelope.
316
323