@awebai/oats 0.57.0 → 0.58.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 +24 -11
- package/docs/configuration.md +19 -28
- package/docs/desktop-cli-api.md +38 -15
- package/docs/desktop.md +14 -0
- package/docs/execution-targets.md +10 -1
- package/docs/implementation.md +7 -1
- package/docs/integrations.md +3 -1
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/release-notes/v0.58.0.md +107 -0
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +9 -0
- package/docs/tui.md +224 -87
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +11 -4
- package/lib/session-viewer.mjs +29 -4
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +19 -8
- package/packages/client/spawn-apply.mjs +216 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-cli.mjs +2 -1
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +164 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/record/lib/directory-identity.mjs +14 -0
- package/packages/record/lib/native-history.mjs +6 -5
- package/packages/tui/README.md +32 -11
- package/packages/tui/lib/actions.mjs +10 -1
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +165 -57
- package/packages/tui/lib/model.mjs +28 -24
- package/packages/tui/lib/panel.mjs +1019 -0
- package/packages/tui/lib/read.mjs +5 -14
- package/packages/tui/lib/store.mjs +77 -30
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/frame.mjs +126 -40
- package/packages/tui/lib/views/help.mjs +12 -10
- package/skills/oats-getting-started/SKILL.md +3 -2
- package/packages/tui/lib/open.mjs +0 -45
package/bin/oats.mjs
CHANGED
|
@@ -104,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
104
104
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
105
105
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
106
106
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
107
|
-
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key"];
|
|
107
|
+
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age"];
|
|
108
108
|
/** Commands `--server <id>` runs on a registered server. */
|
|
109
109
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
110
110
|
const flag = (name) => {
|
|
@@ -1484,16 +1484,24 @@ function sayReadNotices() {
|
|
|
1484
1484
|
for (const notice of readSession?.notices.splice(0) ?? []) process.stderr.write(`oats: warning: ${notice}\n`);
|
|
1485
1485
|
}
|
|
1486
1486
|
/** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
|
|
1487
|
-
* → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`.
|
|
1488
|
-
|
|
1487
|
+
* → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`.
|
|
1488
|
+
* Write verbs refuse it: a writer acting on a reused observation could persist a fact the workspace no
|
|
1489
|
+
* longer holds. A preview-bound spawn apply is the exception: its fence (--expect-decision) binds it to
|
|
1490
|
+
* the decision the operator confirmed, so a reused head applies nothing beyond that decision. */
|
|
1491
|
+
const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, spawn --expect-decision <revision>, trigger poll, and the read forms of teams and soul teams";
|
|
1489
1492
|
function maxAgeRefusal(command, head) {
|
|
1490
1493
|
const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
|
|
1491
|
-
const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
|
|
1494
|
+
const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs and a preview-bound spawn apply reuse observations (${MAX_AGE_READS})`;
|
|
1492
1495
|
if (head.includes("--server")) return "--max-age cannot be combined with --server: observation reuse is local to this machine";
|
|
1493
1496
|
switch (command) {
|
|
1494
1497
|
case "status": case "souls": case "capabilities": case "inspect": return null;
|
|
1495
|
-
// A preview reads (feature spawn-preview-max-age); an apply
|
|
1496
|
-
|
|
1498
|
+
// A preview reads (feature spawn-preview-max-age); an apply only when a confirmed decision binds it
|
|
1499
|
+
// (feature spawn-apply-max-age), with a value as spawn reads it: a bare --expect-decision binds nothing.
|
|
1500
|
+
case "spawn": {
|
|
1501
|
+
const expected = flag("expect-decision");
|
|
1502
|
+
if (head.includes("--preview") || (expected !== undefined && expected !== true)) return null;
|
|
1503
|
+
return "--max-age is not accepted by `oats spawn` without --expect-decision: a spawn apply reuses observations only with --expect-decision <revision>, which binds it to the decision a preview showed";
|
|
1504
|
+
}
|
|
1497
1505
|
case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
|
|
1498
1506
|
case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
|
|
1499
1507
|
// `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
|
|
@@ -2686,8 +2694,8 @@ async function status() {
|
|
|
2686
2694
|
const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
|
|
2687
2695
|
/** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
|
|
2688
2696
|
* `--instance` is refused by a local spawn (with its replacement) but still travels to an older
|
|
2689
|
-
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview
|
|
2690
|
-
* dispatch allow-list (maxAgeRefusal) refuses it
|
|
2697
|
+
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
|
|
2698
|
+
* apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
|
|
2691
2699
|
const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
|
|
2692
2700
|
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
|
|
2693
2701
|
/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
|
|
@@ -4803,7 +4811,8 @@ Usage:
|
|
|
4803
4811
|
instance.json providers.<capability>)
|
|
4804
4812
|
[--preview [--max-age <s>]] decide everything, create nothing; the JSON's
|
|
4805
4813
|
decision binds an apply (--expect-decision <rev>);
|
|
4806
|
-
--max-age reuses recent heads
|
|
4814
|
+
--max-age reuses recent heads, on a preview and
|
|
4815
|
+
on an apply bound by --expect-decision only
|
|
4807
4816
|
oats retire <instance> [--force] retire an instance (window, hooks,
|
|
4808
4817
|
[--self] worktree, home); --self = retire the
|
|
4809
4818
|
[--keep-dir] [--json] CALLING instance: the window dies, then
|
|
@@ -4981,9 +4990,13 @@ Observation reuse (feature observe-max-age):
|
|
|
4981
4990
|
remote again; the JSON
|
|
4982
4991
|
then carries observation { observedAt (the oldest
|
|
4983
4992
|
head used), reused, localRevision (a digest of
|
|
4984
|
-
the local configuration read) }.
|
|
4993
|
+
the local configuration read) }. A spawn apply
|
|
4994
|
+
bound by --expect-decision takes it too (feature
|
|
4995
|
+
spawn-apply-max-age): its decision fence holds,
|
|
4996
|
+
and its JSON carries no observation. Refused
|
|
4985
4997
|
(E_BAD_ARGS) by every other command, an edit form,
|
|
4986
|
-
a spawn apply, and with
|
|
4998
|
+
a spawn apply without --expect-decision, and with
|
|
4999
|
+
--server
|
|
4987
5000
|
|
|
4988
5001
|
Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
|
|
4989
5002
|
}
|
package/docs/configuration.md
CHANGED
|
@@ -87,9 +87,14 @@ Loading development channels” prompt through the **approved route**: the
|
|
|
87
87
|
development prompt. Claude admits the plugin when a root-owned machine
|
|
88
88
|
managed-settings file lists it. The route does not depend on the Claude
|
|
89
89
|
version and needs no OATS mechanism beyond these settings. The operator's
|
|
90
|
-
ordered procedure is the `oats.setup` host
|
|
91
|
-
|
|
92
|
-
|
|
90
|
+
ordered procedure is the `oats.setup` skill `/oats-host-delivery`, whose
|
|
91
|
+
Choice 1 is this route and whose Choice 2 is the host wake broker;
|
|
92
|
+
`/oats-onboarding` card 4 makes both choices and card 8 checks them. The provider's side is
|
|
93
|
+
`/oats-aweb` §4.
|
|
94
|
+
|
|
95
|
+
An unset `claudeChannelMode` is development mode, so a host that never makes
|
|
96
|
+
the choice runs every Claude home with the development prompt. Set the key
|
|
97
|
+
explicitly, to `approved` or, as a recorded fallback, `development`.
|
|
93
98
|
|
|
94
99
|
**The managed-settings file** is a host change made by a human admin with
|
|
95
100
|
sudo. OATS never writes it.
|
|
@@ -127,7 +132,11 @@ settings:
|
|
|
127
132
|
```
|
|
128
133
|
|
|
129
134
|
With channel delivery, pi uses its `@awebai/pi` extension and Codex always
|
|
130
|
-
uses the host broker.
|
|
135
|
+
uses the host broker. The broker (`aw wake run`, one per host user) also wakes
|
|
136
|
+
every joined team and every `delivery: session` home. Without it, joined teams
|
|
137
|
+
are poll-only. It runs as a per-user launchd or systemd service that the
|
|
138
|
+
operator installs, with `AW_WAKE_OATS_BIN` and a `PATH` that reaches `oats`,
|
|
139
|
+
`node` and `tmux`. That procedure is Choice 2 of `/oats-host-delivery`.
|
|
131
140
|
|
|
132
141
|
**The plugin.** `aweb-channel` must be installed from the marketplace named
|
|
133
142
|
`awebai-marketplace` (GitHub `awebai/claude-plugins`) and enabled, in the
|
|
@@ -142,29 +151,10 @@ without the operator's word.
|
|
|
142
151
|
confirm: [the development-channel confirmation](#the-development-channel-confirmation)
|
|
143
152
|
applies only to a launch with the development-channel flag.
|
|
144
153
|
|
|
145
|
-
**Verify
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
2. The started session shows no development prompt, and its banner shows
|
|
150
|
-
“Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace
|
|
151
|
-
inject directly in this session”, followed by “restart without --channels
|
|
152
|
-
to stop”. At normal terminal widths the banner wraps over two rows: look
|
|
153
|
-
for each part, not for one string.
|
|
154
|
-
3. The banner says none of `not on the approved channels allowlist`,
|
|
155
|
-
`not on your org's approved channels list`, `blocked by org policy` or
|
|
156
|
-
`plugin not installed`.
|
|
157
|
-
4. Receive is proven only by the `/oats-aweb` nonce exchange.
|
|
158
|
-
|
|
159
|
-
**Failure banners**, their cause and remedy:
|
|
160
|
-
|
|
161
|
-
| What the session shows | Cause | Remedy |
|
|
162
|
-
|---|---|---|
|
|
163
|
-
| `not on the approved channels allowlist` | the effective managed policy has no `allowedChannelPlugins` (no file, the file not read, or the key missing), so Anthropic's default list applied | write or fix the file |
|
|
164
|
-
| `not on your org's approved channels list` | the effective policy has an `allowedChannelPlugins` without this plugin and marketplace pair: the names in the file are wrong, or a higher source (server-managed settings or MDM) supplies its own list | fix the entry, or have the organization admin add it |
|
|
165
|
-
| `blocked by org policy` (then “Inbound messages will be silently dropped”) | the effective policy lacks `channelsEnabled: true`, which Team/Enterprise subscribers need, and API-key use whenever any managed policy exists | add the key, or have the organization admin set it |
|
|
166
|
-
| `plugin:aweb-channel@awebai-marketplace · plugin not installed` | the plugin is not installed in the launch's Claude config directory | install and enable it there |
|
|
167
|
-
| the development prompt still appears | the home started in development mode, not approved: the host setting is missing, or the home was spawned before the change | set `claudeChannelMode: approved`, then respawn the home |
|
|
154
|
+
**Verify** with the success list and the failure-banner table of
|
|
155
|
+
`/oats-host-delivery`, Choice 1: the preview's mode, the admitted banner
|
|
156
|
+
with no failure banner, then the `/oats-aweb` nonce exchange, which alone
|
|
157
|
+
proves receive.
|
|
168
158
|
|
|
169
159
|
**Limits.** Channels are an Anthropic research preview. Anthropic's
|
|
170
160
|
account-level feature flag gates channels on every route. The allowlist
|
|
@@ -621,5 +611,6 @@ the bounded parsed-read cache and the observations `--max-age` reuses; all of
|
|
|
621
611
|
it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
|
|
622
612
|
catalog file. The read verbs (`status`, `workspace status`, `souls`,
|
|
623
613
|
`capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
|
|
624
|
-
`spawn --preview`)
|
|
614
|
+
`spawn --preview`), and a spawn apply bound by `--expect-decision`, take
|
|
615
|
+
`--max-age <seconds>` to reuse a remote head observed that recently
|
|
625
616
|
([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -45,7 +45,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
45
45
|
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
46
|
"server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
|
|
47
47
|
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
|
-
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key"],
|
|
48
|
+
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age"],
|
|
49
49
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
50
50
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
51
51
|
"capabilityShowApi":1}
|
|
@@ -131,6 +131,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
131
131
|
| `retire-plan-own-worktree` | a retire plan carries `facts.ownWorktree`, a boolean: whether `work/` is the instance's own work tree, the one the retire retains or removes; in `oats retire --plan` and in the fresh plan (`details.plan`) of `E_PLAN_STALE` and `E_CHILDREN_RUNNING`; a stop plan does not carry it; OATS 0.53.0 ([the retire plan](#retire)) | |
|
|
132
132
|
| `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
|
|
133
133
|
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
134
|
+
| `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
|
|
134
135
|
|
|
135
136
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
136
137
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -308,6 +309,7 @@ it and answer live, without the block.
|
|
|
308
309
|
oats status | workspace status | souls | capabilities | inspect --soul|--home
|
|
309
310
|
| teams | soul teams <soul> … --max-age <seconds> --json
|
|
310
311
|
oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
|
|
312
|
+
oats spawn <soul> … --expect-decision <revision> --max-age <seconds> --json (feature spawn-apply-max-age)
|
|
311
313
|
oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
|
|
312
314
|
oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
|
|
313
315
|
```
|
|
@@ -327,10 +329,13 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
327
329
|
- **Spawn preview** (feature `spawn-preview-max-age`, OATS 0.33.0): the
|
|
328
330
|
preview's `result` gains the same block, so you can say "as of
|
|
329
331
|
`<observedAt>`". The `decision` covers the heads the preview used, reused
|
|
330
|
-
or live: a reused head the member has since moved from makes
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
332
|
+
or live: a reused head the member has since moved from makes an apply
|
|
333
|
+
that observes live refuse `E_DECISION_STALE`, and the apply records the
|
|
334
|
+
head it observed, so the next preview under `--max-age` shows it with a new
|
|
335
|
+
`decision.revision`. The preview-bound apply takes the flag from
|
|
336
|
+
`spawn-apply-max-age` (OATS 0.58.0): with `--expect-decision`, it reuses
|
|
337
|
+
heads as the preview does, and its decision fence is unchanged
|
|
338
|
+
([Apply](#apply)). Its answer carries no block.
|
|
334
339
|
- **`localRevision`:** 24 lowercase hex characters, opaque. It digests every
|
|
335
340
|
piece of local configuration the kernel read for this answer:
|
|
336
341
|
`oats-local.yaml` (and each closer `oats-local.yaml` it looked for and did
|
|
@@ -361,18 +366,25 @@ oats trigger poll <id> --run-source … --max-age <seconds> --json (feature tr
|
|
|
361
366
|
spelling of the same repository (ssh vs https) or for a different ref; its
|
|
362
367
|
commit can no longer be fetched. Each is observed live, as without the flag.
|
|
363
368
|
A live observation that fails is the usual error, never an older head.
|
|
364
|
-
- **Refusals:** every other command,
|
|
365
|
-
`--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`)
|
|
369
|
+
- **Refusals:** every other command, every edit form (`teams add|remove|default`)
|
|
366
370
|
and any `--server`
|
|
367
371
|
invocation refuse the flag before reading or writing anything (the removed
|
|
368
372
|
`soul teams --add|--remove|--default|--clear-default` answer their own
|
|
369
373
|
`E_BAD_ARGS` first), with
|
|
370
374
|
`E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
|
|
371
|
-
verbs reuse observations (status, workspace
|
|
372
|
-
capabilities show, inspect --soul|--home,
|
|
373
|
-
|
|
375
|
+
verbs and a preview-bound spawn apply reuse observations (status, workspace
|
|
376
|
+
status, souls, capabilities, capabilities show, inspect --soul|--home,
|
|
377
|
+
spawn --preview, spawn --expect-decision <revision>, trigger poll, and the
|
|
378
|
+
read forms of teams and soul teams)" and,
|
|
374
379
|
with `--server`, "--max-age cannot be combined with --server: observation
|
|
375
|
-
reuse is local to this machine".
|
|
380
|
+
reuse is local to this machine". A spawn apply without `--expect-decision`
|
|
381
|
+
(or with no value after it) refuses it with `E_BAD_ARGS` "--max-age is not
|
|
382
|
+
accepted by \`oats spawn\` without --expect-decision: a spawn apply reuses
|
|
383
|
+
observations only with --expect-decision <revision>, which binds it to the
|
|
384
|
+
decision a preview showed". Write verbs refuse the flag because a writer
|
|
385
|
+
acting on a reused observation could persist a fact the workspace no longer
|
|
386
|
+
holds; a preview-bound apply is the exception because its fence binds it to
|
|
387
|
+
the decision the operator confirmed.
|
|
376
388
|
A capability command's argv (`oats <namespace> …`) is its provider's: the
|
|
377
389
|
kernel neither reads nor refuses `--max-age` there. The same holds for
|
|
378
390
|
`capture`, `recall`, `setup` and `experimental`, which parse their own argv:
|
|
@@ -2316,10 +2328,11 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2316
2328
|
localRevision}`, shaped exactly as the read verbs' block; without it the
|
|
2317
2329
|
preview is exactly as before, and no other field changes shape.
|
|
2318
2330
|
- `decision.revision` covers the heads the preview used, reused or live.
|
|
2319
|
-
|
|
2320
|
-
reused observation refuses `E_DECISION_STALE`, and the
|
|
2321
|
-
it observed, so re-preview under `--max-age` to get the
|
|
2322
|
-
revision.
|
|
2331
|
+
An apply without `--max-age` (or with `--max-age 0`) observes live: a head
|
|
2332
|
+
that moved since the reused observation refuses `E_DECISION_STALE`, and the
|
|
2333
|
+
apply records what it observed, so re-preview under `--max-age` to get the
|
|
2334
|
+
new head and revision. An apply with `--expect-decision` may reuse heads
|
|
2335
|
+
too (feature `spawn-apply-max-age`, [Apply](#apply)).
|
|
2323
2336
|
|
|
2324
2337
|
**Provider settings.**
|
|
2325
2338
|
- `providers` is the `--provider` map as typed.
|
|
@@ -2363,6 +2376,16 @@ Feature `spawn-apply-2`, `spawnApplyApi: 1`. The Desktop gates on
|
|
|
2363
2376
|
`E_INSTANCE_NAME_TAKEN` (for `--name`) or `E_PLACEMENT_TAKEN`.
|
|
2364
2377
|
- A refused child spawn appends `child-spawn-refused` to the parent's log (on
|
|
2365
2378
|
apply only).
|
|
2379
|
+
- `--max-age <s>` with `--expect-decision <revision>` (feature
|
|
2380
|
+
`spawn-apply-max-age`, OATS 0.58.0) reuses member heads this machine
|
|
2381
|
+
observed at most `<s>` seconds ago, exactly as the preview does (the same
|
|
2382
|
+
values and fallbacks to a live observation), so an apply right after its
|
|
2383
|
+
preview asks no remote again. The decision is computed from those heads, and
|
|
2384
|
+
one that differs from `<revision>` is `E_DECISION_STALE`, as without the
|
|
2385
|
+
flag. The answer (success, replay, every refusal) has no `observation`
|
|
2386
|
+
block: the preview already gave its "as of".
|
|
2387
|
+
Without `--expect-decision` the flag is `E_BAD_ARGS`
|
|
2388
|
+
([Observation reuse](#observation-reuse-feature-observe-max-age-oats-0311)).
|
|
2366
2389
|
|
|
2367
2390
|
**Idempotency** (feature `spawn-idempotency-2`): `--idempotency-key <key>`
|
|
2368
2391
|
with `--expect-decision` records the key and decision in `instance.json`.
|
package/docs/desktop.md
CHANGED
|
@@ -166,6 +166,16 @@ workspace on a server: `name — server`).
|
|
|
166
166
|
- Tabs belong to their window: a workspace's terminals and tabs stay in the
|
|
167
167
|
window they were opened in, and switching that window back to the
|
|
168
168
|
workspace brings them back.
|
|
169
|
+
- A tab's terminal ends ("session ended") when its instance's tmux window
|
|
170
|
+
goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
|
|
171
|
+
another instance's terminal. Stopping an instance leaves its tab open.
|
|
172
|
+
- When a roster read shows an instance retired, from the Desktop, the CLI,
|
|
173
|
+
another agent or another machine, every tab of that instance closes, in
|
|
174
|
+
every split. In each split the next tab (or else the previous one) becomes
|
|
175
|
+
active, and the focus moves to it only if it was in a closed tab. A
|
|
176
|
+
workspace that isn't shown closes them the next time its roster is read.
|
|
177
|
+
An instance respawned under the same name is a new instance: opening it
|
|
178
|
+
opens a new tab.
|
|
169
179
|
|
|
170
180
|
## Capabilities and spawning
|
|
171
181
|
|
|
@@ -442,6 +452,10 @@ any other exit code. Closing the tab ends the reconnecting. Reconnecting
|
|
|
442
452
|
never stops or restarts the agent on the server: only the local ssh viewer
|
|
443
453
|
ends.
|
|
444
454
|
|
|
455
|
+
A remote instance's tabs close only when its server answers without it
|
|
456
|
+
(retired there, or gone from it), never because the server can't be reached
|
|
457
|
+
or its roster read is out of date.
|
|
458
|
+
|
|
445
459
|
## Copy from a terminal
|
|
446
460
|
|
|
447
461
|
Drag over an agent's output to select it, as in any terminal. The selection
|
|
@@ -349,6 +349,10 @@ than the server's checked one account and launched with another
|
|
|
349
349
|
given the pane's `PATH` as the pane reads it, a relative entry (and an
|
|
350
350
|
empty one) resolved against the pane's working directory, the home.
|
|
351
351
|
The command a refusal names keeps the harness's name as declared.
|
|
352
|
+
The Claude probe (`claude plugin list --json`) sets `DISABLE_TELEMETRY=1`
|
|
353
|
+
for its own run, so Claude skips its telemetry flush at exit: that selects
|
|
354
|
+
no account and changes no answer, and no launch, install step or other
|
|
355
|
+
probe gets it.
|
|
352
356
|
- **The folder-trust check only warns**: `<harness> folder trust: the
|
|
353
357
|
configuration file this launch will read could not be established
|
|
354
358
|
(<why, and what would make it readable>); nothing is said about its
|
|
@@ -1076,7 +1080,12 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1076
1080
|
acceptance evidence remain separate contracts.
|
|
1077
1081
|
- **attach** is interactive and takes no `--json`. It opens a temporary tmux
|
|
1078
1082
|
session linked to the agent's window alone.
|
|
1079
|
-
Closing the viewer leaves the agent running.
|
|
1083
|
+
Closing the viewer leaves the agent running. When the agent's window ends
|
|
1084
|
+
(for example, the instance is stopped or retired), the viewer ends too: it
|
|
1085
|
+
sets tmux's `detach-on-destroy on` for its own session, so a server
|
|
1086
|
+
configured with `detach-on-destroy off` never moves the viewer's client to
|
|
1087
|
+
another session, another agent's terminal. Your own sessions keep your
|
|
1088
|
+
setting.
|
|
1080
1089
|
|
|
1081
1090
|
On tmux 3.2 and later the viewer's tmux client asks for synchronized
|
|
1082
1091
|
output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
|
package/docs/implementation.md
CHANGED
|
@@ -665,7 +665,13 @@ and acts on every existing session through its recorded socket
|
|
|
665
665
|
(`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
|
|
666
666
|
bytes a terminal sends (`send-keys -l`). A pane program that must show the
|
|
667
667
|
keys it reads puts its terminal in raw mode first: in cooked mode a control
|
|
668
|
-
byte is a signal or an edit, not input.
|
|
668
|
+
byte is a signal or an edit, not input. A signal to the command's process
|
|
669
|
+
group (what a pty hang-up or a C-c delivers) needs the command to be a group
|
|
670
|
+
of its own: the pane's script starts `trap : INT; set -m`, so the shell
|
|
671
|
+
survives to record the status (bash would otherwise end itself after a job
|
|
672
|
+
that INT ended). A `tmux` first on the command's `PATH` times the signal
|
|
673
|
+
against one of the command's tmux calls; it finds the group with
|
|
674
|
+
`ps -o pgid= -p $PPID`.
|
|
669
675
|
- A test of a full-screen program (`oats tui`) uses a pane of a private
|
|
670
676
|
server as its terminal (`test/tui-terminal.test.mjs`): the real CLI is typed
|
|
671
677
|
at an interactive shell in the pane, keys go in with `send-keys`, the screen
|
package/docs/integrations.md
CHANGED
|
@@ -100,7 +100,9 @@ operations in full.
|
|
|
100
100
|
becomes quiet after the kernel records a completed confirmation. If Claude
|
|
101
101
|
ignored the flag, readiness reports `claude-channels-unavailable`.
|
|
102
102
|
`settings.oats.aweb.delivery: session` or
|
|
103
|
-
`settings.oats.aweb.claudeChannelMode: approved` stop the prompt.
|
|
103
|
+
`settings.oats.aweb.claudeChannelMode: approved` stop the prompt. Which one a
|
|
104
|
+
host uses, and its host wake broker, are the operator's choices in
|
|
105
|
+
oats.setup's `/oats-host-delivery`. `oats aweb roster` lists the team:
|
|
104
106
|
its membership certificates and workspaces, one entry per alias with its
|
|
105
107
|
sources, status and kind (global identities first), and says when either
|
|
106
108
|
source is incomplete. After `oats server connect`, `oats aweb connect
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,7 +9,7 @@ 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.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.12.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v5.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.27.3` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v5.2.0`, `5.2.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.2.0` or `oats-framework/v1.
|
|
54
|
+
convention (`v5.2.0` or `oats-framework/v1.12.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,7 +74,7 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
77
|
+
oats.framework: v1.12.0
|
|
78
78
|
oats.okf: v5.2.0
|
|
79
79
|
oats.aweb: v1.27.3
|
|
80
80
|
teams:
|
|
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
|
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
355
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.2.0", "path": "oats-package" },
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.12.0", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
362
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.12.0`
|
|
362
|
+
resolves to tag `oats-framework/v1.12.0`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|