@awebai/oats 0.27.2 → 0.29.0

package/docs/schedules.md

@@ -10,7 +10,7 @@ is `E_LOCAL_MISSING`. Scheduled spawns materialize exactly like `oats spawn`.
 Execution belongs to the host that holds the scope, so a schedule on a
 registered server keeps running while your laptop sleeps.
 
-There is no daemon. One host timer (a launchd user agent on macOS, a systemd
+[Triggers](#triggers) are evaluated by the same tick. There is no daemon. One host timer (a launchd user agent on macOS, a systemd
 user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
 is a short-lived process that evaluates only the current minute, launches
 what is due through the same `spawn`, `session start` and `session input`
@@ -39,7 +39,7 @@ see [Captured definitions](#captured-definitions-removed-in-026).
 ## Kinds
 
 - **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
-  repo?, backend?, purpose?, task, harness?, model?, yolo?, wake?}` — every
+  repo?, backend?, purpose?, task, launchConfig?, harness?, model?, yolo?, wake?}` — every
   due minute launches one disposable instance of `agent` with the same
   options `oats spawn` takes. `agentsRoot` names the exact agents root that
   holds the soul (it must lie inside the workspace and defaults to the
@@ -89,6 +89,220 @@ required IANA zone; both are evaluated by the croner library. `--wake-every
 N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
 then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
 
+## Triggers
+
+A **trigger** (OATS 0.28.0, feature `triggers`) is an event-driven schedule:
+"when EVENT matches, spawn a NEW instance of SOUL with TASK, in TEAMS". It is
+stored in the same `oats-schedules.json` as a job of `kind: "trigger"`,
+managed with `oats trigger …` (never `oats schedule …`, which neither lists nor
+edits one), and evaluated by the same host tick (`oats schedule tick --host`,
+and `oats schedule tick` for one scope). There is no daemon and no webhook: it
+runs only on the host that holds the scope, with **that host's own
+credentials**; a definition carries none.
+
+**Credentials reach the tick through the host timer, not your shell.** The
+timer (a user LaunchAgent on macOS, a `systemd --user` unit on Linux) runs the
+tick with its own environment, which sets only `PATH` and `OATS_HOME_DIR`. `gh`
+logged in with the keyring or its config file under your HOME works there. A
+`GH_TOKEN` or `GITHUB_TOKEN` exported in your shell does not reach it.
+`oats trigger test` reports where `gh`'s credential comes from (`gh.credentialSource`:
+`keyring`, `config`, `env:<VAR>`) and warns when the timer cannot reach it.
+
+```json
+{ "id": "okf-harvest-review", "enabled": true, "kind": "trigger",
+  "on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
+          "events": ["opened", "reopened", "ready_for_review"],
+          "labels": ["okf-harvest"], "base": "main", "poll": "2m" },
+  "spawn": { "soul": "oats.okf/knowledge-maintainer", "purpose": "review-pr-{number}",
+             "task": "Review knowledge-base PR {repo}#{number}. Load knowledge-review first.",
+             "teams": ["okf"], "harness": "claude", "model": "opus" },
+  "concurrency": { "max": 2, "perKey": 1 } }
+```
+
+- **Source** `github.pull_request` (the only one in v1): the tick polls the
+  repository's open pull requests with the host's `gh` (`gh api repos/<owner>/<repo>/pulls`,
+  `state=open`, most recently updated first) every `poll` (default `2m`, at
+  least `1m`). `labels` (all must be present) and `base` filter them. A repo is
+  `github.com/<owner>/<repo>`; another host is passed to `gh` as `--hostname`.
+- **Events** are inferred poll over poll: `opened` (a PR first seen, not a
+  draft; the first poll sees every open PR), `reopened` (seen closed, open
+  again), `ready_for_review` (was a draft), `labeled` (now carries the filter
+  labels it lacked; without a filter, any new label), `synchronize` (a new
+  head commit).
+- **Dedup and retry.** Each event has a key
+  `<trigger>:<repo>#<number>:<event>:<stamp>` (`created_at` for `opened`, the
+  head SHA for `synchronize`, `updated_at` otherwise). A key is recorded as
+  fired **only after a successful spawn**; until then the event stays pending
+  and is retried at every poll, and dropped when its PR closes.
+- **At least once, not exactly once.** The fired key is written after the
+  spawn returns. If the tick dies in between (a crash, a kill, the host going
+  down), the spawned instance exists but the key does not, and the next poll
+  spawns the event again. Concurrency still applies to that retry: with the
+  default `perKey: 1` the first instance is live, so the event is `held` rather
+  than spawned twice, and it fires once that instance retires. A trigger's soul
+  should therefore tolerate a second run on the same PR event (a review that
+  finds its own earlier review, for example).
+- **Concurrency.** `max` (default 1) bounds the live instances of the trigger,
+  `perKey` (default 1) those of one PR; both are counted from the homes'
+  `instance.json.trigger` records, so a retired instance frees its slot. An
+  event over the bound stays pending (`held`).
+- **The spawn** is `oats spawn` (the same path as a scheduled spawn). `soul` is
+  bare or qualified (`<package>/<soul>`). `purpose` (default
+  `{trigger}-{number}`, must render to a slug) and `task` are templated from
+  **only** `{repo} {number} {url} {event} {headSha} {trigger}`: a pull
+  request's title and body are untrusted and never reach the task (a template
+  naming any other field is refused). `teams` becomes the messaging
+  capability's `join=` setting (as `--provider <messaging cap> join=<labels>`).
+  `launchConfig` (a launch configuration in the running host's
+  `oats-local.yaml` `launch-configs`), `harness`, `model`, `yolo`, `backend`
+  are as for schedules; a package template may expose any of them as a
+  parameter (`"path": "spawn.launchConfig"`).
+- **The event reaches the instance** as `OATS_TRIGGER_EVENT_FILE`
+  (`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number, url,
+  event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
+  harness; `instance.json.trigger` records `{ id, key, source, repo, number,
+  url, event, headSha, observedAt, eventFile }`. The task ends with a short
+  block naming the event file.
+- **State** lives in `<scope>/.agents/schedules/triggers.json` (last poll, the
+  PRs seen, pending events, fired keys, the last error).
+
+```sh
+oats trigger add --file trigger.json                 # or:
+oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>]
+oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
+oats trigger test <id>      # dry run: gh auth + credential source, repo + permissions (push/maintain/admin), the soul resolves,
+                            # its messaging capability, the teams declared, what WOULD fire now; spawns nothing
+oats trigger status [<id>]  # last poll, next due, pending, fired keys (time, instance), live vs max, last error
+```
+
+All take `--dir` and `--json` (`triggerApi: 1`). `remove` leaves the instances
+it spawned running. `oats schedule list` does not list triggers, but it counts
+them (`triggers: { count, command: "oats trigger list" }`, and a line in text
+mode). Errors: `E_TRIGGER_INVALID { field }`, `E_TRIGGER_EXISTS`,
+`E_TRIGGER_UNKNOWN`, `E_BAD_ARGS`.
+
+**Package trigger templates.** A package may declare `triggers: [{ id, file }]`
+in `oats-package.json`. Each file is `{ parameters: { <name>: { path,
+required?, default?, description? } }, definition: { …a trigger… } }`.
+`oats trigger add --from <package>:<id>` reads it at the locked commit;
+`--set <name>=<value>` fills a parameter at its dotted `path` (a list value is
+comma-separated); a required parameter without a value is `E_BAD_ARGS
+{ missing }` naming it. The trigger records `template: { package, version,
+commit, template }`.
+
+## Workspace triggers and schedules
+
+(OATS 0.29.0, feature `automations`.) A trigger or a schedule is defined at one of
+two levels:
+
+- **in the workspace**: a file committed in a confirmed member repository, shared
+  through Git and named `<member>/<id>`. This is the default for anything a team
+  relies on.
+- **locally**: in the deployment's `oats-schedules.json` (`oats trigger add`,
+  `oats schedule add`), machine-private and named `local/<id>`.
+
+The two kinds stay separate at every step. Each has its own folder, its own file
+kind, its own ids, its own commands, its own list and its own opt-out.
+
+| | trigger | schedule |
+| --- | --- | --- |
+| canonical folder (at the member's root) | `oats-triggers/` | `oats-schedules/` |
+| file name anywhere in the member | `*.oats-trigger.yaml` | `*.oats-schedule.yaml` |
+| `kind:` | `oats-trigger` | `oats-schedule` |
+| body | `from:` + `set:` (a package template), or `on`, `spawn`, `concurrency` as above | `run: spawn \| command`, `cron`, `tz`, `agent`, `task`, `purpose`, `launchConfig`, `harness`, `model`, `yolo`, `backend`, `wake`, `argv`, `cwd` |
+| commands | `oats trigger …` | `oats schedule …` |
+| opt-out on this host | `triggers.disabled` | `schedules.disabled` |
+
+Every `.yaml`/`.yml` under a canonical folder is a candidate, and so is a file with
+the kind's suffix anywhere in the member (`.yml` works too), e.g.
+`services/billing/nightly.oats-schedule.yaml` beside the code it concerns.
+`oats-package/`, `.git/` and `node_modules/` are never scanned.
+
+```yaml
+# <member>/oats-triggers/okf-harvest-review.yaml
+kind: oats-trigger
+schemaVersion: 1
+description: Review every harvest PR on the knowledge base
+from: oats.okf:harvest-review        # a package template at the locked commit, then its parameters
+set: { repo: github.com/acme/knowledge }
+runsOn: kb-bot-server                # the host.name that runs it
+owner: github.com/acme-kb-bot        # the GitHub account it acts as
+```
+
+```yaml
+# <member>/services/billing/nightly.oats-schedule.yaml
+kind: oats-schedule
+schemaVersion: 1
+run: spawn
+cron: "0 7 * * *"
+tz: Europe/Madrid
+agent: digest-writer                 # resolved like `oats spawn <soul>` (member or package soul)
+task: Write the nightly digest.
+runsOn: ana-laptop
+owner: github.com/ana
+```
+
+- **The file describes itself.** It carries `kind` and `schemaVersion: 1`. A
+  candidate of the wrong kind (a schedule in `oats-triggers/`) or without one is an
+  `E_AUTOMATION_SCHEMA` problem, never silently skipped.
+- **The id** is `id:`, else the filename stem. The same id twice in one member for
+  one kind is `E_AUTOMATION_DUPLICATE`, naming both paths; the second file is not
+  listed. A trigger and a schedule may share an id: they are different things.
+- **A workspace schedule is `run: spawn` or `run: command`.** A `command`'s `cwd` is
+  relative to the deployment. `wake` and `operation` target an instance home on one
+  machine, so they stay local.
+
+**Who runs it.** A host runs a workspace trigger or schedule only when both of these
+hold:
+
+1. its `runsOn` is this host's `host.name` in `oats-local.yaml`;
+2. the host's authenticated `gh` account (`gh api user`, asked once per tick) is its
+   `owner`.
+
+Otherwise the item is listed with a reason:
+
+- `assigned-elsewhere`: another host runs it;
+- `owner-mismatch`: this host is named, but its `gh` is logged in as someone else or
+  not at all. Nothing runs, the tick reports it, and `oats trigger test` says so;
+- `host-unnamed`: this host has no `host.name`.
+
+So exactly one machine runs it, and consent is explicit: the machine's operator
+named the host and is logged in as the account.
+
+**Opting out** without a commit: `oats trigger disable <member>/<id>` writes
+`triggers.disabled`, and `oats schedule disable <member>/<id>` writes
+`schedules.disabled`, in `oats-local.yaml`. `enable` removes the entry. A
+workspace definition is never edited or removed here (`update` and `remove` are
+`E_AUTOMATION_WORKSPACE`): change the file in Git.
+
+**Refresh.**
+
+- `oats sync` discovers the workspace triggers and schedules of the confirmed
+  members into a snapshot, `.agents/automations/snapshot.json` in the deployment,
+  with one list per kind. It takes one tree listing per member commit.
+- The host tick reads that snapshot. It refreshes it (`oats automations refresh`)
+  when the snapshot is more than ten minutes old, at most once per interval. When
+  the refresh fails, the last good snapshot keeps serving.
+- A change in Git therefore reaches the named host within about ten minutes.
+- The run state (dedup keys, last poll, last run) stays per host and local. A
+  workspace schedule's job lock and state are keyed `<member>~<id>`.
+- A trigger template (`from:`) is instantiated when the snapshot is taken, at the
+  commit the host's lock pins.
+
+**Writing one.** Add `--workspace <member> --runs-on <host> --owner <host>/<login>`
+to `oats trigger add` or `oats schedule add`:
+
+- Run inside a checkout of that member, it writes `oats-triggers/<id>.yaml` or
+  `oats-schedules/<id>.yaml` there, for you to commit and push.
+- Anywhere else, it prints the file.
+- Either way, the file is read back and validated first.
+- `oats trigger test <member>/<id>` checks the placement, and everything else it
+  checked before, on this host.
+
+Everything above still holds: the soul must resolve here, templates name only the
+whitelisted fields, a PR's text is never interpolated, and no definition carries a
+credential.
+
 ## Captured definitions (removed in 0.26)
 
 0.24–0.25 could save captured command definitions: `definitionVersion`,
@@ -119,6 +333,7 @@ oats schedule add <id> --file spec.json --dir <workspace> --json
 oats schedule update <id> --file spec.json
 oats schedule list | show <id> | enable <id> | disable <id> | remove <id>
 oats schedule run <id>            # now, under the same lock and bound
+oats schedule test <id>           # dry run: where it runs, whether its soul resolves, when it is next due; spawns nothing
 oats schedule tick --dry-run      # what would run this minute, launching nothing
 oats schedule reconcile <id> [--clear]   # resolve an attempt whose result was never recorded
 oats schedule host install        # register this scope and install the ONE host timer (idempotent while active)
@@ -129,8 +344,9 @@ oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --w
 Every subcommand takes `--server <id>` instead of `--dir`: it then runs on
 that host, in its registered workspace, because schedules are host-owned.
 
-`list --json` answers `{schedules: [{id, ...definition, nextRun, lastRun,
-running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
+`list --json` answers `{schedules: [{id, ...definition, nextDue, lastRun,
+running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`
+(`oats trigger list --json` carries the same `scheduler`).
 `active` is what the OS reports about the timer, not whether a file exists.
 
 ## What a run reports
@@ -194,6 +410,16 @@ the instance is neither hidden nor spawned again.
 
 ## OKF v2 source jobs
 
+> **oats.okf 4.0.0:** a source and its job exist only where harvest is
+> effectively on (`harvest: on|off`, default off), and the job spawns the
+> harvester package soul. The review of its PR runs as a **trigger**, run by
+> the same host tick: a workspace file (`oats-triggers/okf-harvest-review.yaml`
+> in a member repo, `kind: oats-trigger`, with `runsOn` and `owner`), or a
+> local one in this file. See
+> [knowledge.md](knowledge.md#knowledge-operations), [Triggers](#triggers) and
+> [Workspace triggers and schedules](#workspace-triggers-and-schedules); the
+> trigger commands are `oats trigger …`.
+
 The [prepared OKF v2 runtime](knowledge.md) registers **one command job per
 source**, not a fleet sweep or a home-bound operation job. It runs from stable
 deployment context with argv equivalent to:

package/docs/souls-and-instances.md

@@ -196,9 +196,13 @@ refused (`E_INSTANCE_NAME_TAKEN`).
 
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
 discovers the workspace over its remotes and confirms membership → finds the
-soul among the confirmed members (or `external:`; an ambiguous bare name is
-`E_SOUL_AMBIGUOUS` — say `<repo>/<soul>`) → fetches the soul's source into
-`<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
+soul among the confirmed members, `external:` souls and the locked packages'
+souls (an ambiguous bare name is `E_SOUL_AMBIGUOUS`, naming each qualified
+form: `<member>/<soul>` or `<package>/<soul>`; a soul listed in
+`oats-local.yaml` `souls.disabled` is `E_SOUL_DISABLED`) → fetches the soul's
+source into `<agents-root>/<soul>/souls/<commit12>/` at its commit (a package
+soul at the locked commit, verified against the lock's digest — see
+[package souls](packages.md#package-souls); the home links that
 directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
 every capability by
 `from:` (member = latest, package = locked) → creates the home →
@@ -512,14 +516,12 @@ Default layout:
     docs-expert/         # a workspace soul, defined in a member repository's
       souls/<commit12>/  #   souls/docs-expert/ and copied here per commit
       instances/
-    memory-harvest/      # a capability-defined agent: only instances/, no soul
-      instances/
 ```
 
-A capability-defined agent (declared by a package or member module, such as
-the OKF harvester) homes under the agents root exactly like a soul; its
-directory holds only `instances/`. A name that is both a workspace soul and a
-capability agent is ambiguous (`E_SOUL_AMBIGUOUS`).
+Every agent is a soul — a member soul, or a package soul homed under
+`agents/<package>--<soul>/`. A capability-defined agent (a manifest's
+`agents:`) was removed in 0.29.0; a home an earlier kernel left for one (its
+directory holds only `instances/`) is still listed and retirable.
 
 There are no local souls. A soul is a member repository's `souls/<name>`
 (`soul.yaml` + `AGENTS.md`); author it there and run `oats sync`. OATS 0.25

package/docs/workspaces.md

@@ -59,8 +59,8 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v2.1.5
+  oats.framework: v1.3.0                   # bare version → resolves through the official catalog
+  oats.okf: v4.0.0
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -168,9 +168,18 @@ settings:                                  # host-owned values the manifests ask
     bindings-file: /Users/ana/.oats/okf-bindings.json
     state-dir: /Users/ana/.oats/okf
 souls:
-  disabled: [data-analyst]                 # not run on this machine
+  disabled: [data-analyst]                 # not run on this machine (E_SOUL_DISABLED); oats.okf/knowledge-harvester names a package soul
+host:
+  name: ana-laptop                         # this machine's name: runs the workspace triggers/schedules whose runsOn names it
+triggers:
+  disabled: [knowledge/okf-harvest-review] # workspace triggers this host does not run (oats trigger disable)
+schedules:
+  disabled: [platform/nightly-digest]      # workspace schedules this host does not run (oats schedule disable)
 ```
 
+`host`, `triggers.disabled` and `schedules.disabled` (0.29.0) are machine facts:
+see [schedules.md#workspace-triggers-and-schedules](schedules.md#workspace-triggers-and-schedules).
+
 See [configuration.md](configuration.md). `oats-config.yaml` no longer exists.
 
 ### `oats-lock.json` — lock v3
@@ -230,6 +239,12 @@ read; the soul gets no member-tier capabilities of its own repo; it is
 "source-complete" (its skills travel with it) and the workspace's defaults fill
 its slots. An `external[].team` overrides the soul's own `team`.
 
+**Package souls.** A package may ship souls (`souls:` in `oats-package.json`,
+0.28.0): they are listed from the lock for each package the workspace declares,
+named `<package>/<soul>` (a bare name when unique), resolved like any soul
+(`from: here` = their own package at the locked commit) and trusted as the
+package is. See [packages](packages.md#package-souls).
+
 ## Member tier vs package tier — the non-collapse rule
 
 A repository may be a **member** (it completed the handshake; its `souls/*` and