@awebai/oats 0.49.0 → 0.51.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 +150 -34
- package/docs/capabilities.md +172 -2
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +268 -22
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +120 -9
- package/docs/implementation.md +26 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +20 -7
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/schedules.md +228 -15
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +92 -8
- package/docs/workspaces.md +2 -2
- package/lib/capability-show.mjs +14 -1
- package/lib/claim.mjs +126 -0
- package/lib/core.mjs +428 -102
- package/lib/instance-events.mjs +3 -7
- package/lib/instance-git.mjs +8 -5
- package/lib/instance-inspect.mjs +44 -15
- package/lib/refused-text.mjs +17 -0
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/schedule.mjs +8 -2
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/lib/worktree-hooks.mjs +24 -9
- package/lib/worktree.mjs +14 -86
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
|
@@ -346,8 +346,9 @@ positive whole number of milliseconds replaces the fixed 30-minute timeout of
|
|
|
346
346
|
tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
|
|
347
347
|
10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
|
|
348
348
|
the kernel read a process's start time with `ps`, as on a host without
|
|
349
|
-
`/proc` (macOS), on a host that has it
|
|
350
|
-
|
|
349
|
+
`/proc` (macOS), on a host that has it; an absolute path instead runs that
|
|
350
|
+
file as `ps`, directly and in the same fixed environment; any other value
|
|
351
|
+
reads no start at all. A launch configuration cannot set any of them. Do not set them in a deployment.
|
|
351
352
|
|
|
352
353
|
**An instance creates an agents' session or window without its own
|
|
353
354
|
environment.** Nothing of an instance's environment reaches a server or a
|
|
@@ -486,12 +487,33 @@ tmux -L oats kill-server # replace it: ends EVERY sessio
|
|
|
486
487
|
- `-L oats` reaches the server of the environment you type it in
|
|
487
488
|
(`TMUX_TMPDIR`). For the server an instance is on, use the socket from its
|
|
488
489
|
row in `oats status --json`: `tmux -S <socket> …`.
|
|
489
|
-
- A tmux server whose socket file is missing
|
|
490
|
-
|
|
491
|
-
that
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
490
|
+
- <a id="missing-socket"></a>A tmux server whose socket file is missing
|
|
491
|
+
(`error connecting to <socket> (No such file or directory)`) is not proof
|
|
492
|
+
that it exited: a server outlives its removed socket file (a
|
|
493
|
+
temporary-files cleaner, a removed socket directory), and tmux gives the
|
|
494
|
+
same words after a reboot, when the server is gone. So OATS reads it as
|
|
495
|
+
stopped only when no process works in the instance's home
|
|
496
|
+
([the process scan](souls-and-instances.md#the-process-scan)): the row is
|
|
497
|
+
not running and a start creates the window again, as after a reboot. When
|
|
498
|
+
a process works there, or the scan cannot run, the state is not
|
|
499
|
+
established: `oats status` shows the row `running: null` with
|
|
500
|
+
`runtimeState: "unreachable"` and a `runtimeError` that names the
|
|
501
|
+
processes (pid and program, at most five) or the scan's error;
|
|
502
|
+
`oats session start` and `restart` refuse with `E_SESSION_UNKNOWN` and
|
|
503
|
+
create no server at that path; `oats instance stop` refuses with
|
|
504
|
+
`E_SESSION_UNAVAILABLE`, never "already idle". tmux recreates a removed
|
|
505
|
+
socket file when its server process receives `SIGUSR1`
|
|
506
|
+
(`kill -USR1 <pid of that tmux server>`); OATS names that and never sends
|
|
507
|
+
it. Any process working in the
|
|
508
|
+
home counts, a shell left in that directory included, as for retire: the
|
|
509
|
+
message names its pid and program, so end it or leave the directory. A
|
|
510
|
+
socket file no server listens on (`no server running on <socket>`) is
|
|
511
|
+
definitive: stopped, with no scan
|
|
512
|
+
([#624](https://github.com/awebai/oats/issues/624)). This holds for every
|
|
513
|
+
tmux server OATS reads, not only the `oats` server, and for a home that
|
|
514
|
+
records no socket and reads your default server. A home that records
|
|
515
|
+
neither a socket nor a launch (`--no-launch`) reads as not running
|
|
516
|
+
whatever works in it.
|
|
495
517
|
|
|
496
518
|
<a id="existing-instances"></a>
|
|
497
519
|
#### Existing instances
|
|
@@ -582,6 +604,8 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
|
|
|
582
604
|
pane is reused in place. A missing window, or one whose tmux server cannot
|
|
583
605
|
be reached, is created again on the OATS tmux server, and the start warns when that is
|
|
584
606
|
not the server the home recorded ([Existing instances](#existing-instances)).
|
|
607
|
+
A server whose socket file is missing counts as gone only when no process
|
|
608
|
+
works in the home ([missing socket file](#missing-socket)).
|
|
585
609
|
- A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
|
|
586
610
|
starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
|
|
587
611
|
is refused (`E_INSTANCE_RETIRING`).
|
|
@@ -743,7 +767,10 @@ children and uncommitted work, with a `planRevision`. `--apply --plan-revision
|
|
|
743
767
|
<rev> --idempotency-key <key>` stops the instance and its recorded children
|
|
744
768
|
first (`--no-recursive` stops only the instance), with the same bounded
|
|
745
769
|
SIGTERM. Restart the instance later with `oats session start` or
|
|
746
|
-
`oats session restart`.
|
|
770
|
+
`oats session restart`. An instance whose recorded tmux socket file is
|
|
771
|
+
missing while a process works in its home, or the process scan cannot run,
|
|
772
|
+
is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
|
|
773
|
+
stopped ([missing socket file](#missing-socket)).
|
|
747
774
|
|
|
748
775
|
### Inspect, input and attach
|
|
749
776
|
|
|
@@ -751,6 +778,7 @@ SIGTERM. Restart the instance later with `oats session start` or
|
|
|
751
778
|
oats session inspect --home /abs/home --json
|
|
752
779
|
oats session input --home /abs/home --text-file message.txt --json
|
|
753
780
|
oats session attach --home /abs/home
|
|
781
|
+
oats session attach --home /abs/home --detach-key 'C-\'
|
|
754
782
|
```
|
|
755
783
|
|
|
756
784
|
- **inspect** reports `backend`, `present` and `state`: `unknown` for a live
|
|
@@ -800,6 +828,89 @@ oats session attach --home /abs/home
|
|
|
800
828
|
session linked to the agent's window alone.
|
|
801
829
|
Closing the viewer leaves the agent running.
|
|
802
830
|
|
|
831
|
+
**Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
|
|
832
|
+
every key goes to the agent, the tmux prefix included. Close the terminal.
|
|
833
|
+
With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
|
|
834
|
+
`session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
|
|
835
|
+
viewer's client. The agent's window and every other viewer are untouched.
|
|
836
|
+
The key is taken from the agent's input: the agent never receives it while
|
|
837
|
+
this viewer is attached. A keyed viewer reads a tmux key table of its own,
|
|
838
|
+
named as its temporary session and removed with it, so the key is bound
|
|
839
|
+
for that viewer alone. Check the feature in `oats version --json` before
|
|
840
|
+
passing the flag: a kernel without it ignores the flag and opens a viewer
|
|
841
|
+
with no exit.
|
|
842
|
+
|
|
843
|
+
The key is one of these, spelled exactly (case-sensitive):
|
|
844
|
+
|
|
845
|
+
```
|
|
846
|
+
key = control / meta / function
|
|
847
|
+
control = "C-" ( "a"-"g" / "j"-"l" / "n"-"z" / "\" / "]" / "^" / "_" )
|
|
848
|
+
meta = "M-" ( "a"-"z" / "0"-"9" )
|
|
849
|
+
function = [ "C-" / "M-" / "S-" ] "F" ( "1" … "12" )
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
Anything else is `E_BAD_ARGS`, before any tmux or ssh call: a missing
|
|
853
|
+
value, a plain character, `C-i` and `C-m` (Tab and Enter on tmux before
|
|
854
|
+
3.5), `C-h` (the byte, 0x08, that many terminals send for Ctrl+Backspace
|
|
855
|
+
and some for Backspace, so the name is not one key everywhere), `C-[`
|
|
856
|
+
(Escape), `M-[`, `M-]`, `M-\`, `M-O` and the other ESC + C1 introducers (a
|
|
857
|
+
terminal reply can arrive as that key), `Any`, mouse key names, two keys,
|
|
858
|
+
upper case, and anything with a space, `;` or a control character. The
|
|
859
|
+
kernel does not judge whether a harness reads the key: that is the
|
|
860
|
+
caller's choice.
|
|
861
|
+
|
|
862
|
+
**While the pane is scrolled back.** The viewer's wheel and drag bindings
|
|
863
|
+
put the pane in tmux's copy mode, and there copy mode's key table is read
|
|
864
|
+
before the viewer's. A detach key that copy mode binds acts in copy mode
|
|
865
|
+
and does not detach; it detaches once the mode is left (`q`, or scrolling
|
|
866
|
+
back to the bottom). The grammar does not exclude those keys. The
|
|
867
|
+
copy-mode tables are the tmux server's, shared by every session and
|
|
868
|
+
changed by the operator's `~/.tmux.conf`, so no grammar can promise a key
|
|
869
|
+
is free there, and the kernel never binds a detach key in a table other
|
|
870
|
+
sessions read. With tmux's default tables (3.7c), 35 of the 111 keys are
|
|
871
|
+
taken in emacs or vi copy mode (for example `C-e`, `C-c`, `M-w`, `C-u`);
|
|
872
|
+
`C-\` and `F12` are bound in neither and detach from copy mode. Detaching
|
|
873
|
+
while scrolled back leaves the agent's pane in copy mode for the next
|
|
874
|
+
viewer, as closing a viewer mid-scroll does.
|
|
875
|
+
|
|
876
|
+
**The suggested key is `C-\`**, written `--detach-key 'C-\'` (quoted: an
|
|
877
|
+
unquoted trailing backslash continues the line). The kernel fixes no key.
|
|
878
|
+
What was checked:
|
|
879
|
+
|
|
880
|
+
- It has no default binding in Claude Code 2.1.288 (which refuses to let
|
|
881
|
+
a user bind it: "terminal quit signal"), Codex CLI 0.160.0 or pi 1.0.2.
|
|
882
|
+
It is unbound in bash 5.3 (`bind -p`) and in zsh's and fish's documented
|
|
883
|
+
defaults. It is the default detach key of dtach and abduco.
|
|
884
|
+
- A viewer with this key gives up: in a fallback shell, the tty's QUIT (no
|
|
885
|
+
SIGQUIT from the keyboard); in vim and nvim, the `C-\ C-n` prefix; in
|
|
886
|
+
nano, Replace (also on `M-r`).
|
|
887
|
+
- On a layout where `\` needs AltGr, use `F12`: it has no default binding
|
|
888
|
+
in the same three harnesses, bash, nvim or less. Some terminals and
|
|
889
|
+
laptops keep F12 for themselves.
|
|
890
|
+
- `C-]`, `C-_`, `C-g`, `C-t` and `C-b` are each bound by all three
|
|
891
|
+
harnesses.
|
|
892
|
+
|
|
893
|
+
**Exit status.**
|
|
894
|
+
|
|
895
|
+
| How the command ended | Status |
|
|
896
|
+
|---|---|
|
|
897
|
+
| Left by the detach key (the agent keeps running) | 20 |
|
|
898
|
+
| The viewer ended without the key: the agent's window ended, or `oats` itself was stopped by SIGHUP, SIGTERM or SIGINT and closed the viewer | 0 |
|
|
899
|
+
| A refusal (bad arguments, not launched, session gone), or tmux failing under the viewer (its server exited) | 1 |
|
|
900
|
+
|
|
901
|
+
20 is answered only when the key's own binding ran, and only by a kernel
|
|
902
|
+
with the feature. No status an existing caller sees changes meaning. 20 is
|
|
903
|
+
nonzero, so `set -e`, an `&&` chain and tmux's `remain-on-exit failed`
|
|
904
|
+
treat a leave by the key as a failure. The routed form (`--server`) relays
|
|
905
|
+
these statuses and adds ssh's own 255 ([servers.md](servers.md#run-there)).
|
|
906
|
+
|
|
907
|
+
With `--detach-key`, `oats` handles SIGQUIT. `C-\` is also the terminal's
|
|
908
|
+
QUIT character: pressed before the viewer has the terminal, or again once
|
|
909
|
+
the viewer has given it back, it would otherwise end `oats` with status 131
|
|
910
|
+
and leave the viewer's session and key table on the tmux server. A QUIT
|
|
911
|
+
that arrives before the key was used stops the attach, with status 1;
|
|
912
|
+
after a leave by the key it changes nothing, and the status is 20.
|
|
913
|
+
|
|
803
914
|
### Attachments
|
|
804
915
|
|
|
805
916
|
`oats session upload --file <local> --home <abs>` copies a file into
|
package/docs/implementation.md
CHANGED
|
@@ -58,16 +58,20 @@ published to npm. Its developer docs are in
|
|
|
58
58
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
59
59
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
60
60
|
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
|
|
61
|
+
| `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
|
|
62
|
+
| `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
|
|
61
63
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
|
62
64
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
63
65
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
64
66
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
|
|
65
67
|
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
|
|
68
|
+
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`) and by `oats retire` per home (`core.mjs`, `retireInstance`) |
|
|
66
69
|
| `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL |
|
|
67
70
|
| `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
|
|
68
71
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
69
72
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
70
73
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
74
|
+
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
71
75
|
| `servers.mjs` | routing commands to a registered server |
|
|
72
76
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
73
77
|
| `launch-prompt-completion.mjs` | pure, qualified post-answer completion reporting using a finite bottom input/footer table and 21 question markers; never an input matcher |
|
|
@@ -384,6 +388,13 @@ and acts on every existing session through its recorded socket
|
|
|
384
388
|
`list-windows`, `new-window` (a window id) and `set-option`.
|
|
385
389
|
- A server a test starts is killed by its socket, never by name and never
|
|
386
390
|
with a bare `tmux kill-server`.
|
|
391
|
+
- A test that needs a terminal (an attached tmux client, a key press) runs
|
|
392
|
+
the command in a pane of a second private server and types at that pane
|
|
393
|
+
with `send-keys`; the pane's shell records the exit status
|
|
394
|
+
(`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
|
|
395
|
+
bytes a terminal sends (`send-keys -l`). A pane program that must show the
|
|
396
|
+
keys it reads puts its terminal in raw mode first: in cooked mode a control
|
|
397
|
+
byte is a signal or an edit, not input.
|
|
387
398
|
|
|
388
399
|
Nor does a test depend on where or how the suite runs:
|
|
389
400
|
|
|
@@ -408,7 +419,8 @@ A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
|
|
|
408
419
|
unit, a live operator tmux server and Apple git, run from inside an instance
|
|
409
420
|
home. A pull request that could not be run there says so in its hand-over. The
|
|
410
421
|
suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
|
|
411
|
-
with `require`), git ≥ 2.45,
|
|
422
|
+
with `require`), git ≥ 2.45, tmux, and lsof where `/proc` cannot be read
|
|
423
|
+
(awebai/oats#783, #625). The
|
|
412
424
|
helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
|
|
413
425
|
shared fixture (`v2Deployment`) applies all of it, so a suite built on it
|
|
414
426
|
inherits it (awebai/oats#816):
|
|
@@ -438,13 +450,21 @@ inherits it (awebai/oats#816):
|
|
|
438
450
|
no host service manager is reachable at all.
|
|
439
451
|
- **No leftover processes.** The fixture's cleanup fails when a process still
|
|
440
452
|
works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
|
|
441
|
-
`processesInHome` (lsof). It catches a hook's or a CLI's grandchild that
|
|
453
|
+
`processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
|
|
442
454
|
outlived the test, once its parent has exited. The scan leaves out its caller
|
|
443
455
|
and the caller's direct children, so a test's own forgotten child is not
|
|
444
456
|
found here: that is the test's bug to fix. A process still exiting gets 2 s.
|
|
445
457
|
Nothing is killed, the base is removed, and the failure names each pid and
|
|
446
458
|
command. A test that leaves a process running on purpose (a group the kernel
|
|
447
|
-
must not signal) ends it itself before that check, on failure too
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
459
|
+
must not signal) ends it itself before that check, on failure too, through
|
|
460
|
+
`fx.beforeCleanup(fn)`: the cleanup runs those synchronous functions first,
|
|
461
|
+
in order, and still runs when one throws. Never end it with a later `t.after`: node:test
|
|
462
|
+
runs `t.after` hooks in the order they were added, so a hook added after the
|
|
463
|
+
fixture's runs after the check (`test/worktree-event.test.mjs`).
|
|
464
|
+
- **Cleanup even when a test fails.** Pass the test context,
|
|
465
|
+
`v2Deployment({ t })`: the fixture registers its own cleanup with
|
|
466
|
+
`t.after` when it is created, so a test that throws, rejects or times out
|
|
467
|
+
still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
|
|
468
|
+
and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
|
|
469
|
+
`t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
|
|
470
|
+
built removes its base itself.
|
package/docs/integrations.md
CHANGED
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.0**. Provider implementation and
|
|
9
|
+
This is the operator guide for **oats.okf 5.0.1**. Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
23
23
|
```yaml
|
|
24
24
|
# oats-workspace.yaml (excerpt)
|
|
25
25
|
packages:
|
|
26
|
-
oats.okf: v5.0.
|
|
26
|
+
oats.okf: v5.0.1
|
|
27
27
|
defaults:
|
|
28
28
|
knowledge: { oats.okf: { from: package } }
|
|
29
29
|
stores:
|
|
@@ -105,7 +105,8 @@ explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
|
|
|
105
105
|
5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
|
|
106
106
|
removed keys still refuse and name the fix. The harvester has no provider
|
|
107
107
|
runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
|
|
108
|
-
selection and retires after
|
|
108
|
+
selection and retires after successful handoff or nothing promotable. A
|
|
109
|
+
publication failure retains its live home; see [the flow](#the-flow).
|
|
109
110
|
|
|
110
111
|
## The soul's okf.json
|
|
111
112
|
|
|
@@ -165,10 +166,22 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
165
166
|
notes, edits only owned nodes in its own Git checkout, validates the
|
|
166
167
|
**whole base**, and creates a normal `okf-harvest`-labelled PR with v2
|
|
167
168
|
provenance. Proposal text is data written with the native file tool into
|
|
168
|
-
commit-message/PR-body files, never shell command text.
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
169
|
+
commit-message/PR-body files, never shell command text. A publication ref
|
|
170
|
+
is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
|
|
171
|
+
name in it; Git validates the full ref and the push must create a new
|
|
172
|
+
ref, never update or adopt an existing one. Source identity stays in
|
|
173
|
+
commit text and PR provenance. After all PRs are open (or nothing is
|
|
174
|
+
promotable), it hands over and retires rather than waiting for acceptance.
|
|
175
|
+
If source authority is unavailable it stops and reports; a consistent
|
|
176
|
+
instance/soul pair alone does not prove proposer authorship.
|
|
177
|
+
**On any publication failure it does not retire:** it keeps the live home,
|
|
178
|
+
clone/any commit, exact error and commit/PR text locations, and notifies
|
|
179
|
+
the source through existing messaging when reachable. Missing or failed
|
|
180
|
+
messaging does not hide the original error or permit retirement. Existing
|
|
181
|
+
attention may expose the blocked home where supported. No automatic
|
|
182
|
+
retries, new recipient or maintainer preflight; a maintainer exists only
|
|
183
|
+
for a labelled PR. A gh error can leave remote effects, so partial or
|
|
184
|
+
uncertain publication is not completion or permission to clean up.
|
|
172
185
|
4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
|
|
173
186
|
Human-accepted decisions are not silently superseded; the review path
|
|
174
187
|
keeps its human gate. A PR is not accepted knowledge until merged.
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.
|
|
13
|
-
| `oats.okf` | `v5.0.
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.9.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.24.1` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf: v5.0.
|
|
32
|
+
`packages:` map (`oats.okf: v5.0.1`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.0.
|
|
47
|
+
oats.okf: v5.0.1 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.0.
|
|
51
|
+
- **Bare version** (`v5.0.1`, `5.0.1`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.0.
|
|
54
|
+
convention (`v5.0.1` or `oats-framework/v1.9.1`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
78
|
-
oats.okf: v5.0.
|
|
79
|
-
oats.aweb: v1.
|
|
77
|
+
oats.framework: v1.9.1
|
|
78
|
+
oats.okf: v5.0.1
|
|
79
|
+
oats.aweb: v1.24.1
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.1 ✓ (@ 96b28d5c)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.
|
|
137
|
+
oats package add oats.aweb v1.24.1 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.0.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.0.1",
|
|
164
|
+
"commit": "96b28d5cd4f01e48ed50d8e999e8715749a99e87",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -290,6 +290,20 @@ overrides it; a workspace trigger made `from:` it shows its file header's
|
|
|
290
290
|
description, else the template's. A kernel before 0.43.0 refuses the key, so
|
|
291
291
|
a package whose template sets it needs `compatibility.oats: ">=0.43.0"`.
|
|
292
292
|
|
|
293
|
+
A template may name a capability's trigger source (feature
|
|
294
|
+
`trigger-sources`): its
|
|
295
|
+
`definition.on` is `{ source: "<capability>:<source>", params?, events,
|
|
296
|
+
poll? }`, and a parameter's `path` may point into `on.params` (for example
|
|
297
|
+
`on.params.prefix`). `add --from` checks what it means against the soul it
|
|
298
|
+
spawns, as for any capability-source trigger
|
|
299
|
+
([schedules.md](schedules.md#capability-sources)). A package does **not**
|
|
300
|
+
raise `compatibility.oats` for such a template: a template is read only by
|
|
301
|
+
`add --from`, so a kernel without feature `trigger-sources` refuses that one
|
|
302
|
+
`add --from` (`E_TRIGGER_INVALID` on `on.source`, or on `on.params` when the
|
|
303
|
+
template sets it), reports a workspace trigger made from it as a problem of
|
|
304
|
+
its snapshot, and uses the package's capabilities and souls as before. A
|
|
305
|
+
floor would refuse them all on every older host.
|
|
306
|
+
|
|
293
307
|
## Compatibility floors
|
|
294
308
|
|
|
295
309
|
A soul may state floors on package versions — constraints, not sources:
|
|
@@ -338,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
338
352
|
{
|
|
339
353
|
"policy": "docs/official-catalog.md",
|
|
340
354
|
"packages": {
|
|
341
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.
|
|
342
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.1", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.1", "path": "oats-package" }
|
|
343
357
|
}
|
|
344
358
|
}
|
|
345
359
|
```
|
|
346
360
|
|
|
347
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
348
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.1`
|
|
362
|
+
resolves to tag `oats-framework/v1.9.1`. Resolving through the catalog never
|
|
349
363
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -216,3 +216,44 @@ re-checks a published inventory against the source and its origin; it attests
|
|
|
216
216
|
what the remote advertised when queried, so released tags must never move.
|
|
217
217
|
`--generate --source <clone>` captures a working tree for development and
|
|
218
218
|
always records `release.status: pending`.
|
|
219
|
+
|
|
220
|
+
## Releasing `oats.framework`
|
|
221
|
+
|
|
222
|
+
The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
|
|
223
|
+
`oats.support`, `oats.knowledge-theory`) is not published by `release.yml` or
|
|
224
|
+
by this lane. A deployment takes it from this repository at the tag
|
|
225
|
+
`oats-framework/v<version>`, through the catalog ref or its workspace pin. A
|
|
226
|
+
skill changed under `oats-package/` therefore reaches deployments only when
|
|
227
|
+
that tag moves, whatever kernel version carried the change.
|
|
228
|
+
|
|
229
|
+
**A kernel release whose pull requests touched `oats-package/` ships a
|
|
230
|
+
framework release with it.** To see whether one is owed:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
git diff --stat "$(git describe --tags --abbrev=0 --match 'oats-framework/v*' origin/main)" origin/main -- oats-package
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
When the diff is not empty:
|
|
237
|
+
|
|
238
|
+
1. **The framework prep PR.** Bump `version` in the `oats.json` of each
|
|
239
|
+
changed capability and in `oats-package/oats-package.json`, and add the
|
|
240
|
+
release-notes entry. Read the skill lines added since the last tag: a
|
|
241
|
+
command or behaviour that an older kernel the capability still admits does
|
|
242
|
+
not have names the version it starts in. Guidance text alone does not
|
|
243
|
+
raise a capability's `compatibility.oats`.
|
|
244
|
+
2. **The tag.** After the PR merges, put the annotated tag
|
|
245
|
+
`oats-framework/v<version>` on its merge commit and push it. No workflow
|
|
246
|
+
runs on this tag.
|
|
247
|
+
3. **The pin**, in the kernel release-prep PR: `package-catalog.json`
|
|
248
|
+
(`ref`), `oats-workspace.yaml`, and the version literals in
|
|
249
|
+
`docs/official-catalog.md`, `docs/packages.md`, `docs/workspaces.md`,
|
|
250
|
+
`skills/oats-getting-started/SKILL.md` and
|
|
251
|
+
`test/release-packaging.test.mjs`. The pin does not ride the first PR:
|
|
252
|
+
the tag needs the bumped manifest on `main` first, and CI reads the
|
|
253
|
+
catalog's ref from the remote. Two tests in
|
|
254
|
+
`test/hook-events-forward-tolerant.test.mjs` sync a deployment that takes
|
|
255
|
+
the official catalog's packages, so the pin's CI fails with
|
|
256
|
+
`E_REMOTE_UNREADABLE` until the tag is pushed. (The clean-room smoke does
|
|
257
|
+
not read it: it tags its own copy of `oats-package/`.) A green CI proves
|
|
258
|
+
that the tag exists, not which commit it names: the pin's reviewer
|
|
259
|
+
confirms on the remote that it names the first PR's merge commit.
|