@awebai/oats 0.49.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.
@@ -117,6 +117,7 @@ see the [official catalog](official-catalog.md) for current pins.
117
117
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
118
118
  | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
119
119
  | `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
120
+ | `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
120
121
  | `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
121
122
 
122
123
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
@@ -220,6 +221,7 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
220
221
  | teams | soul teams <soul> … --max-age <seconds> --json
221
222
  oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
222
223
  oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
224
+ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
223
225
  ```
224
226
 
225
227
  - **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
@@ -279,8 +281,8 @@ oats capabilities show <name> … --max-age <seconds> --json (feature capabilit
279
281
  `E_BAD_ARGS` first), with
280
282
  `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
281
283
  verbs reuse observations (status, workspace status, souls, capabilities,
282
- capabilities show, inspect --soul|--home, spawn --preview, and the read
283
- forms of teams and soul teams)" and,
284
+ capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
285
+ and the read forms of teams and soul teams)" and,
284
286
  with `--server`, "--max-age cannot be combined with --server: observation
285
287
  reuse is local to this machine".
286
288
  A capability command's argv (`oats <namespace> …`) is its provider's: the
@@ -1000,6 +1002,15 @@ nothing reads a working clone.
1000
1002
  [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
1001
1003
  Their `path` is the repository-relative form, unlike the paths above. The
1002
1004
  text form prints them (to stderr with `--file`).
1005
+ - `triggerSources` (feature `trigger-sources`), after
1006
+ `warnings`, only when the manifest declares the key: the declaration
1007
+ exactly as written, whatever its shape (untrusted text: render it as
1008
+ text). `triggerSourceProblems: [{source, pointer, message}]` follows only
1009
+ when the declaration has problems: the ones a trigger naming a source
1010
+ would get as `E_TRIGGER_SOURCE`, `source` `null` for a top-level problem,
1011
+ `pointer` a JSON pointer into the manifest. A malformed declaration never
1012
+ refuses the command and adds nothing to `problems`
1013
+ ([capabilities.md](capabilities.md#trigger-sources-triggersources)).
1003
1014
  - With `--max-age` (`0` included) both the show and the `--file` answer gain
1004
1015
  the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
1005
1016
  block `{observedAt, reused, localRevision}`.
@@ -1094,7 +1105,8 @@ nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
1094
1105
  (`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
1095
1106
 
1096
1107
  **Without `--json`** the show prints a short listing for an operator: the
1097
- inject's path and size, each skill with its files and sizes, and the
1108
+ inject's path and size, each skill with its files and sizes, the trigger
1109
+ sources (name, command, events, description) and their problems, and the
1098
1110
  problems. `--file` prints the text; a binary file prints a one-line note
1099
1111
  instead, and a truncated file prints its text followed by a one-line note.
1100
1112
 
@@ -1130,6 +1142,12 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
1130
1142
  empty list read as "no warning". Older kernels answer no such `warnings` key
1131
1143
  (inspect, readiness, show, doctor) and refuse the capability instead.
1132
1144
 
1145
+ `oats doctor --json` also lists what retires left behind in `information[]`:
1146
+ one `retained-recovery:` and one `retained-worktree:` line per item, after a
1147
+ line that gives each kind's total, and at most 50 items per kind
1148
+ ([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
1149
+ Each element is one line of text with no newline. The answer has no new key.
1150
+
1133
1151
  ### Desktop facts
1134
1152
 
1135
1153
  Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
@@ -2220,7 +2238,11 @@ its absence.
2220
2238
  claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
2221
2239
  the row's recorded tmux socket and session, never the caller's `$TMUX`;
2222
2240
  `null` with `runtimeState: "unreachable"` and the tmux error as
2223
- `runtimeError` when that server cannot be read; `null` for a home a
2241
+ `runtimeError` when that server cannot be read, and also when its socket
2242
+ file is missing while a process works in the home or the process scan
2243
+ cannot run, `runtimeError` then naming the processes or the scan's error
2244
+ ([#624](execution-targets.md#missing-socket); with no process in the home
2245
+ a missing socket file reads `false`, as after a reboot); `null` for a home a
2224
2246
  Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
2225
2247
  `runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
2226
2248
  in the row),
@@ -2917,7 +2939,10 @@ the instance back.
2917
2939
  idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
2918
2940
  "transcript", "launch"], replayed: false}`. A result is `{instance, home,
2919
2941
  ok: true, stopped, alreadyIdle, state}` or `{instance, home, ok: false,
2920
- code, message, stillRunning: [pid]}`.
2942
+ code, message, stillRunning: [pid]}`. `code` is `E_SESSION_UNAVAILABLE` when
2943
+ whether the instance runs cannot be established, among them a recorded
2944
+ tmux socket file that is missing while a process works in the home
2945
+ ([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
2921
2946
  - `ok: false`: at least one target still runs (text mode exits 1).
2922
2947
  - A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
2923
2948
  with `replayed: true`.
@@ -2955,8 +2980,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
2955
2980
  true, note}` when the session is observably gone: instance.json records no
2956
2981
  launch, or the recorded tmux server is not running, or the recorded window
2957
2982
  is gone and no pane on that server works in the home, and in every case no
2958
- live process on the host has its working directory in the home (`lsof`; a
2959
- scan that cannot run counts as not absent). Retire then proceeds
2983
+ live process on the host has its working directory in the home
2984
+ ([the process scan](souls-and-instances.md#the-process-scan): `/proc` on
2985
+ Linux, `lsof` elsewhere; a scan that cannot run counts as not absent). Retire then proceeds
2960
2986
  without quiescing (hooks run, work is preserved). Otherwise it stays
2961
2987
  `unestablished`, with a `note` saying why, and retire refuses with
2962
2988
  `E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
@@ -3038,7 +3064,10 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
3038
3064
 
3039
3065
  Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
3040
3066
  (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
3041
- `-2` suffix if taken; `detached-<oid12>` when detached), state intact. An
3067
+ `-2` suffix if taken; `detached-<oid12>` when detached), state intact. The
3068
+ `<branch>` leaf is the branch flattened to one path component, and a long one
3069
+ is cut and hashed to fit NAME_MAX
3070
+ ([souls-and-instances.md](souls-and-instances.md#extra-trees-at-retire)). An
3042
3071
  extra tree that is not clean is moved the same way; a clean one is removed.
3043
3072
 
3044
3073
  ```text
@@ -3338,6 +3367,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
3338
3367
  `E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
3339
3368
  that target and the way out: stop it, then `oats session restart`, which
3340
3369
  goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
3370
+ - A recorded tmux socket file that is missing while a process works in the
3371
+ home, or the process scan cannot run, is not a stopped server:
3372
+ `E_SESSION_UNKNOWN`, nothing started and no server created at that path
3373
+ ([#624](execution-targets.md#missing-socket)).
3341
3374
  - A lost response does not mean the launch failed: check status before a
3342
3375
  retry. A remote home's saved route names its execution host.
3343
3376
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
@@ -3545,11 +3578,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
3545
3578
  ### `oats trigger`
3546
3579
 
3547
3580
  ```text
3548
- oats trigger list | show <id> | status [<id>] | test <id> | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
3581
+ oats trigger list | show <id> | status [<id>] | test <id> [--run-source] | poll <id> --run-source [--max-age <s>] | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
3549
3582
  ```
3550
3583
 
3551
3584
  Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3552
- "trigger"`).
3585
+ "trigger"`). A trigger's source is the built-in `github.pull_request` or, with
3586
+ feature `trigger-sources`, `<capability>:<source>`, a source a
3587
+ capability declares ([schedules.md](schedules.md#capability-sources)).
3553
3588
 
3554
3589
  - `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
3555
3590
  `show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
@@ -3561,17 +3596,29 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3561
3596
  - `id` is always qualified (`local/<id>` or `<member>/<id>`); verbs accept
3562
3597
  `local/<id>` or a bare local id.
3563
3598
  - `on`: `{source: "github.pull_request", repo, events: [opened | reopened |
3564
- ready_for_review | labeled | synchronize], labels, base?, poll}`.
3599
+ ready_for_review | labeled | synchronize], labels, base?, poll}`, or for a
3600
+ capability source `{source: "<capability>:<source>", params: {<name>:
3601
+ <string>}, events: [<the source's event names>], poll}`.
3565
3602
  - `spawn`: `{soul, purpose, task, teams, launchConfig?, harness?, model?,
3566
3603
  yolo?, backend?}`. `purpose` and `task` template over `{repo}`,
3567
- `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`. `teams` are
3604
+ `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`, `{subject}` and
3605
+ `{key}`; a capability source's over `{trigger}`, `{source}`, `{subject}`,
3606
+ `{event}`, `{key}`, `{url}` and `{fields.<name>}`. `teams` are
3568
3607
  distinct labels passed as `--provider <messaging cap> join=<labels>`; a
3569
3608
  soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
3570
3609
  - `template?`: `{package, version, commit, template}`.
3571
3610
  - `lastRun`: `{at, instance, home, event, number, subject, key}`
3572
3611
  (`subject`, 0.49.0: the event's subject, a PR's number as a string;
3573
- for a run recorded before 0.49.0, its number); `nextDue`: the
3574
- next poll here, `null` before the first.
3612
+ for a run recorded before 0.49.0, its number; a capability source's
3613
+ run has `number: null`); `nextDue`: the next poll here, `null` before
3614
+ the first.
3615
+ - `invalid?`: `{code, message, field?}` when the stored definition no
3616
+ longer validates, as before. A capability source's trigger whose last
3617
+ meaning check failed at a poll carries `invalid: {code, message, field?,
3618
+ at}` instead (`code` `E_TRIGGER_SOURCE` or `E_TRIGGER_INVALID`; `at` when
3619
+ the check ran), until a good poll. `invalid` always means the trigger
3620
+ itself is invalid; an event the source answered badly is an *invalid
3621
+ event* (`invalidEvents`).
3575
3622
  - `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
3576
3623
  runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
3577
3624
  liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
@@ -3582,6 +3629,36 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3582
3629
  `subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
3583
3630
  PR's number, as a string. A record written before 0.49.0 has none, and
3584
3631
  its number is reported.
3632
+ - **A capability source's `status` row** (feature `trigger-sources`) has
3633
+ `repo: null`, `number: null` in `pending[]`, `fired[]` and `live[]`, and
3634
+ adds `source: {capability, name}`, `invalidEvents: [{text, rule}]` (the
3635
+ last good poll's, at most 20; `rule` is `shape`, `unknown-key`, `key`,
3636
+ `subject`, `event`, `url`, `fields` or `duplicate-key`, `text` the first
3637
+ 200 characters of the event's JSON), `skipped: [{subject, why}]` (the last
3638
+ good poll's, at most 100) and, when its last meaning check failed,
3639
+ `invalid: {code, message, field?, at}`. Its `lastPoll` is `{at, ok: true,
3640
+ events, invalidEvents, skipped, filtered}` (counts) or `{at, ok: false,
3641
+ cause, error, source?}`, and `lastError` may carry the same `source`.
3642
+ `cause` is `exit`, `result`, `too-many-events`, `timeout`, `refused` or
3643
+ `resolution`; `source: {code, message?}` is the source's own refusal.
3644
+ `why`, `source.code` and `source.message` are the source's untrusted text,
3645
+ capped (200, 128, 500 characters) with control, separator, bidi,
3646
+ invisible and tag characters replaced by U+FFFD: render them as text,
3647
+ marked as the source's.
3648
+ - **Presence and staleness.** `source`, `invalidEvents` and `skipped` are
3649
+ always present on a capability source's status row. The two lists are
3650
+ `[]` until the trigger's first good poll and hold the last good poll's
3651
+ lists after that. A failed poll (`lastPoll.ok: false`) and a failed
3652
+ meaning check (`invalid`, which leaves `lastPoll` as it was) leave them
3653
+ unchanged, so they can be older than `lastPoll.at`, `lastError.at` and
3654
+ `invalid.at`. The lists are the current source's: changing a trigger's
3655
+ `on.source` empties them and `pending`, and clears `invalid`, `lastPoll`
3656
+ and `lastError` (`fired` stays), in what `status` and `list` answer at
3657
+ once and in the state at the next tick.
3658
+ - **Arrays versus counts.** In `trigger test`'s `source` (`ok: true`) and
3659
+ in `trigger poll`'s answer, `events`, `invalidEvents` and `skipped` are
3660
+ arrays and `filtered` is a count. In `lastPoll` (`ok: true`) and in the
3661
+ tick's `polled` row, all four are counts.
3585
3662
  - `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
3586
3663
  runsHere, reason, detail?, enabledHere}, gh: {ok, account,
3587
3664
  credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
@@ -3596,20 +3673,96 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
3596
3673
  purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
3597
3674
  `null` when the soul does not resolve or its name is too long for a
3598
3675
  triggered spawn (that error is then in `problems`).
3676
+ - **`test <id> --run-source` of a capability source's trigger** runs the
3677
+ source (it executes the capability's source command, whatever the host's
3678
+ trust and `runsOn` say, and so only with the flag: see **`--run-source`**
3679
+ below) and answers `{triggerApi, id, ok, placement, gh, repo: null,
3680
+ soul, teams, source, wouldFire, problems, warnings, spawned: false}`, no
3681
+ `pollError`. `gh` is `null` unless the trigger has an `owner` (then as
3682
+ above, for the owner's host). `source` is `{capability, name, ok: true,
3683
+ events, invalidEvents, skipped, filtered}`, `{capability, name, ok: false,
3684
+ filtered: 0, invalid: {code, message, field?, at}, events: [],
3685
+ invalidEvents: [], skipped: []}` when its meaning fails, or `{capability,
3686
+ name, ok: false, filtered: 0, cause, error: {code, message}, source?,
3687
+ events: [], invalidEvents: [], skipped: []}` when the poll fails.
3688
+ Without `--run-source`, `test` answers a trigger whose meaning or
3689
+ resolution fails as above (exit 0, `source.ok: false`: no capability code
3690
+ runs to say so), and a trigger whose meaning holds with
3691
+ `E_TRIGGER_SOURCE_RUN`. `wouldFire` rows are `{key, subject,
3692
+ event, url?, instance, nameCut, held?}`. When the tick would not run the
3693
+ trigger here, `problems` holds `run manually with --run-source; the tick
3694
+ will not run it here: <reason>` (with the placement's detail). `warnings` always holds
3695
+ "this source's credential may not be visible to the host timer: it runs
3696
+ with only PATH and OATS_HOME_DIR set, so keep the source's login in its
3697
+ own store, not in an exported variable".
3698
+ - **`poll <id> --run-source`** (feature `trigger-sources`) runs a capability
3699
+ source's trigger's source once, its meaning checked first, and answers
3700
+ `{triggerApi, id, source: {capability, name}, events: [{key, subject,
3701
+ event, url?, fields}], invalidEvents: [{text, rule}], skipped: [{subject,
3702
+ why}], filtered}`, plus `observation` with `--max-age`. `events` are the
3703
+ valid events the trigger selects, `key` as the source wrote it (stored
3704
+ prefixed `<trigger>:`); `filtered` counts the valid events whose `event`
3705
+ the trigger does not select. It records nothing and spawns nothing, but it
3706
+ executes the capability's source command. A failed poll is `E_TRIGGER_POLL`
3707
+ with `details: {cause, source?}`; a meaning failure is `E_TRIGGER_SOURCE`
3708
+ `{capability, source, pointer?}` or `E_TRIGGER_INVALID {field}`; without
3709
+ the flag it is `E_TRIGGER_SOURCE_RUN`; a `github.pull_request` trigger is
3710
+ `E_BAD_ARGS`, with or without the flag. Without `--max-age` it observes
3711
+ the members live.
3712
+ - **`--run-source`** (feature `trigger-sources`): by hand, `test` and `poll`
3713
+ run a capability source's command only with this switch (it takes no
3714
+ value). It is caller intent, never trust consent: with it they run the
3715
+ source whatever the host's `automations.trust` and the trigger's `runsOn`
3716
+ say, and trust, `runsOn` and `owner` gate the tick exactly as before (the
3717
+ tick passes the flag to its own child). Without it, on a capability
3718
+ source's trigger: `E_TRIGGER_SOURCE_RUN`, `ok: false`, a non-zero exit,
3719
+ `details: {capability, source, flag: "--run-source"}`, and a message
3720
+ naming the command to run again (`oats trigger test|poll <id>
3721
+ --run-source`), and the trigger's `runsOn` when that is another host: it
3722
+ holds only the id, the capability and source names and `runsOn`, never
3723
+ text of the source's. Nothing of the capability has executed and nothing
3724
+ has been written in the deployment, the soul's copy under `agents/` and
3725
+ the capability's directory in the module store included. The
3726
+ order is fixed: a valid definition (`E_TRIGGER_INVALID`), then its meaning
3727
+ and the soul's resolution (`E_TRIGGER_SOURCE`, `E_TRIGGER_INVALID
3728
+ {field}`, `E_TRIGGER_POLL` `cause: "resolution"`), then this gate, then
3729
+ the run. On a `github.pull_request` trigger the flag is accepted and
3730
+ inert: `test` answers byte for byte the same.
3731
+ - **What a `triggerApi: 1` reader sees.** `triggerApi` stays 1. `on.source`
3732
+ is an open string: tell rows apart by it, and gate on `trigger-sources`.
3733
+ The keys above (`source`, `invalidEvents`, `skipped`, a meaning failure's
3734
+ `invalid`, `test`'s `source`) appear only on capability-source rows and
3735
+ are absent, not `null`, on a `github.pull_request` row, whose outputs are
3736
+ exactly as before. On a capability source's rows the PR-only fields are
3737
+ `null` (`repo`, `number`) or absent (`on.repo`, `on.labels`, `on.base`,
3738
+ `wouldFire[].repo`), and `lastPoll` carries the counts above instead of
3739
+ `prs` and `matching`.
3599
3740
  - A triggered instance records `instance.json.trigger`: `{id, key, source,
3600
3741
  repo, number, subject, url, event, headSha, observedAt, eventFile}`
3601
3742
  (`subject` since 0.49.0; `null` when the event had none). Its event file is
3602
3743
  `OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
3603
- event, headSha, labels, observedAt, key}`.
3744
+ event, headSha, labels, observedAt, key}`. For a capability source the
3745
+ record has `repo: null`, `number: null`, `headSha: null` and adds `fields`,
3746
+ and the event file is `{trigger, source, subject, event, key, url?,
3747
+ fields, observedAt}`.
3604
3748
  - `update <id> --description=<text>` (feature `automation-descriptions`)
3605
3749
  changes only a local trigger's description; `--description=` (empty)
3606
3750
  removes it. It sets `updatedAt` and leaves fired and pending events
3607
3751
  untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
3608
3752
  refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
3609
3753
  --description is supported for now"). An older kernel has no `update`.
3754
+ - `add` of a capability source's trigger checks its meaning against the
3755
+ soul's resolution before anything is written (`E_TRIGGER_SOURCE`,
3756
+ `E_TRIGGER_INVALID {field}`, or the soul's own resolution error).
3610
3757
  - Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
3611
- `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_POLL`,
3612
- `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
3758
+ `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_SOURCE {capability,
3759
+ source, pointer?}` (a capability source that is undeclared or malformed,
3760
+ whose capability the soul does not compose, or whose command is not a file
3761
+ inside the capability; `pointer` is a JSON pointer into the manifest),
3762
+ `E_TRIGGER_POLL` (`details.cause` and `details.source` for a capability
3763
+ source), `E_TRIGGER_SOURCE_RUN {capability, source, flag}` (`test` or
3764
+ `poll` of a capability source's trigger without `--run-source`: nothing
3765
+ ran, nothing was written), `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
3613
3766
  `E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
3614
3767
 
3615
3768
  <a id="automations-shared-rows"></a>
@@ -3681,7 +3834,12 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
3681
3834
  `number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
3682
3835
  soul as a tick does, and reports a preview failure or a name that cannot
3683
3836
  fit as `spawn-failed`), `invalid` and
3684
- `not-here`. A workspace schedule's state key is `<member>~<id>`. A failed
3837
+ `not-here`. A capability source's trigger adds `poll-deferred`
3838
+ (`deadline`: its poll could not end by 50 s after the tick started; it
3839
+ goes first next tick), its `polled` carries `events`, `invalidEvents`,
3840
+ `skipped` and `filtered`, `poll-failed` a `cause`, `invalid` a failed
3841
+ meaning check, and its `would-fire` has no `number`, and no `url` when the
3842
+ event has none. A workspace schedule's state key is `<member>~<id>`. A failed
3685
3843
  snapshot refresh is `{workspace, action: "error", error}`.
3686
3844
 
3687
3845
  <a id="the-harness-rename-feature-harness-oats-0270"></a>
package/docs/desktop.md CHANGED
@@ -288,6 +288,19 @@ arguments as written, an operation and its home), its run state and where it
288
288
  comes from. Writing summaries needs OATS 0.43 or later; an older OATS still
289
289
  shows the ones it reports.
290
290
 
291
+ A trigger can take its events from a source a capability declares instead of
292
+ GitHub pull requests (OATS 0.50.0 or later). Its page shows the source and
293
+ what the trigger passes to it, what the source's last poll found or why it
294
+ failed, and which events OATS refused or the source skipped. Text that comes
295
+ from the source, from the trigger's file or from the capability's manifest is
296
+ shown as a quote with a line saying whose it is; it is never a link or a
297
+ button. **Test** on a pull-request trigger reads GitHub and reports what would
298
+ fire. **Test** on such a capability trigger runs the capability's source
299
+ command on this computer, so it first shows what will run and with which
300
+ parameters, and runs it once only when you press **Run test**. Nothing is
301
+ recorded or spawned, and testing does not trust or start a trigger that this
302
+ computer doesn't trust.
303
+
291
304
  The Spawn dialog also has an optional **Recurring wake-up** setting. It binds
292
305
  the schedule to the newly created home, preserving that agent's identity and
293
306
  work. A wake starts that same home if it is stopped, then sends the saved
@@ -486,12 +486,33 @@ tmux -L oats kill-server # replace it: ends EVERY sessio
486
486
  - `-L oats` reaches the server of the environment you type it in
487
487
  (`TMUX_TMPDIR`). For the server an instance is on, use the socket from its
488
488
  row in `oats status --json`: `tmux -S <socket> …`.
489
- - A tmux server whose socket file is missing or does not answer reads as not
490
- reachable, which is not proof that it exited: status, start and stop read
491
- that state as stopped
492
- ([#624](https://github.com/awebai/oats/issues/624)). That is an existing
493
- limit of every tmux server OATS uses, not of the `oats` server in
494
- particular.
489
+ - <a id="missing-socket"></a>A tmux server whose socket file is missing
490
+ (`error connecting to <socket> (No such file or directory)`) is not proof
491
+ that it exited: a server outlives its removed socket file (a
492
+ temporary-files cleaner, a removed socket directory), and tmux gives the
493
+ same words after a reboot, when the server is gone. So OATS reads it as
494
+ stopped only when no process works in the instance's home
495
+ ([the process scan](souls-and-instances.md#the-process-scan)): the row is
496
+ not running and a start creates the window again, as after a reboot. When
497
+ a process works there, or the scan cannot run, the state is not
498
+ established: `oats status` shows the row `running: null` with
499
+ `runtimeState: "unreachable"` and a `runtimeError` that names the
500
+ processes (pid and program, at most five) or the scan's error;
501
+ `oats session start` and `restart` refuse with `E_SESSION_UNKNOWN` and
502
+ create no server at that path; `oats instance stop` refuses with
503
+ `E_SESSION_UNAVAILABLE`, never "already idle". tmux recreates a removed
504
+ socket file when its server process receives `SIGUSR1`
505
+ (`kill -USR1 <pid of that tmux server>`); OATS names that and never sends
506
+ it. Any process working in the
507
+ home counts, a shell left in that directory included, as for retire: the
508
+ message names its pid and program, so end it or leave the directory. A
509
+ socket file no server listens on (`no server running on <socket>`) is
510
+ definitive: stopped, with no scan
511
+ ([#624](https://github.com/awebai/oats/issues/624)). This holds for every
512
+ tmux server OATS reads, not only the `oats` server, and for a home that
513
+ records no socket and reads your default server. A home that records
514
+ neither a socket nor a launch (`--no-launch`) reads as not running
515
+ whatever works in it.
495
516
 
496
517
  <a id="existing-instances"></a>
497
518
  #### Existing instances
@@ -582,6 +603,8 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
582
603
  pane is reused in place. A missing window, or one whose tmux server cannot
583
604
  be reached, is created again on the OATS tmux server, and the start warns when that is
584
605
  not the server the home recorded ([Existing instances](#existing-instances)).
606
+ A server whose socket file is missing counts as gone only when no process
607
+ works in the home ([missing socket file](#missing-socket)).
585
608
  - A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
586
609
  starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
587
610
  is refused (`E_INSTANCE_RETIRING`).
@@ -743,7 +766,10 @@ children and uncommitted work, with a `planRevision`. `--apply --plan-revision
743
766
  <rev> --idempotency-key <key>` stops the instance and its recorded children
744
767
  first (`--no-recursive` stops only the instance), with the same bounded
745
768
  SIGTERM. Restart the instance later with `oats session start` or
746
- `oats session restart`.
769
+ `oats session restart`. An instance whose recorded tmux socket file is
770
+ missing while a process works in its home, or the process scan cannot run,
771
+ is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
772
+ stopped ([missing socket file](#missing-socket)).
747
773
 
748
774
  ### Inspect, input and attach
749
775
 
@@ -58,6 +58,8 @@ 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 |
@@ -68,6 +70,7 @@ published to npm. Its developer docs are in
68
70
  | `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
71
  | `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
72
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
73
+ | `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
74
  | `servers.mjs` | routing commands to a registered server |
72
75
  | `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
76
  | `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 |
@@ -408,7 +411,8 @@ A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
408
411
  unit, a live operator tmux server and Apple git, run from inside an instance
409
412
  home. A pull request that could not be run there says so in its hand-over. The
410
413
  suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
411
- with `require`), git ≥ 2.45, lsof and tmux (awebai/oats#783). The
414
+ with `require`), git ≥ 2.45, tmux, and lsof where `/proc` cannot be read
415
+ (awebai/oats#783, #625). The
412
416
  helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
413
417
  shared fixture (`v2Deployment`) applies all of it, so a suite built on it
414
418
  inherits it (awebai/oats#816):
@@ -438,13 +442,21 @@ inherits it (awebai/oats#816):
438
442
  no host service manager is reachable at all.
439
443
  - **No leftover processes.** The fixture's cleanup fails when a process still
440
444
  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
445
+ `processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
442
446
  outlived the test, once its parent has exited. The scan leaves out its caller
443
447
  and the caller's direct children, so a test's own forgotten child is not
444
448
  found here: that is the test's bug to fix. A process still exiting gets 2 s.
445
449
  Nothing is killed, the base is removed, and the failure names each pid and
446
450
  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: node:test
448
- runs `t.after` hooks in the order they were added, so its own hook added
449
- after `t.after(fx.cleanup)` runs too late (`test/worktree-event.test.mjs`
450
- ends them inside its cleanup hook, ahead of `fx.cleanup`).
451
+ must not signal) ends it itself before that check, on failure too, through
452
+ `fx.beforeCleanup(fn)`: the cleanup runs those synchronous functions first,
453
+ in order, and still runs when one throws. Never end it with a later `t.after`: node:test
454
+ runs `t.after` hooks in the order they were added, so a hook added after the
455
+ fixture's runs after the check (`test/worktree-event.test.mjs`).
456
+ - **Cleanup even when a test fails.** Pass the test context,
457
+ `v2Deployment({ t })`: the fixture registers its own cleanup with
458
+ `t.after` when it is created, so a test that throws, rejects or times out
459
+ still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
460
+ and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
461
+ `t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
462
+ built removes its base itself.
@@ -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.8.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
12
+ | `oats.framework` | `oats-framework/v1.9.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
13
  | `oats.okf` | `v5.0.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.23.2` | `oats.aweb` (messaging) | |
14
+ | `oats.aweb` | `v1.24.0` | `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` |
package/docs/packages.md CHANGED
@@ -51,7 +51,7 @@ packages:
51
51
  - **Bare version** (`v5.0.0`, `5.0.0`, `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.0` or `oats-framework/v1.8.0`) and the payload path. An id
54
+ convention (`v5.0.0` or `oats-framework/v1.9.0`) 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.8.0
77
+ oats.framework: v1.9.0
78
78
  oats.okf: v5.0.0
79
- oats.aweb: v1.23.2
79
+ oats.aweb: v1.24.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -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.23.2 # a catalog version
137
+ oats package add oats.aweb v1.24.0 # 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
  ```
@@ -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:
@@ -339,11 +353,11 @@ A soul that names one of the package's capabilities with
339
353
  "policy": "docs/official-catalog.md",
340
354
  "packages": {
341
355
  "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.0", "path": "oats-package" },
342
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.8.0", "path": "oats-package" }
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.0", "path": "oats-package" }
343
357
  }
344
358
  }
345
359
  ```
346
360
 
347
- `ref` carries the tag convention: a workspace's `oats.framework: v1.8.0`
348
- resolves to tag `oats-framework/v1.8.0`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.9.0`
362
+ resolves to tag `oats-framework/v1.9.0`. Resolving through the catalog never
349
363
  advances a lock by itself: `oats sync` does, and says so.
@@ -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.