@awebai/oats 0.63.0 → 0.64.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/README.md +14 -1
- package/bin/oats.mjs +57 -22
- package/docs/desktop-cli-api.md +43 -1
- package/docs/execution-targets.md +9 -5
- package/docs/first-team.md +6 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.64.0.md +105 -0
- package/docs/souls-and-instances.md +26 -6
- package/docs/upgrading.md +2 -1
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +29 -7
- package/lib/session-input.mjs +12 -2
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/instance-tree.mjs +53 -3
- package/packages/client/roster-sections.mjs +22 -6
- package/skills/oats-getting-started/SKILL.md +438 -170
package/README.md
CHANGED
|
@@ -25,6 +25,19 @@ For example, a kernel expert, a UX expert and a customer-support expert can shar
|
|
|
25
25
|
|
|
26
26
|
The [official catalog](docs/official-catalog.md) is the reviewed list of official packages. A workspace trusts a package by declaring it; being listed doesn't declare it.
|
|
27
27
|
|
|
28
|
+
## Start here
|
|
29
|
+
|
|
30
|
+
Ask your coding agent (Claude Code, Codex, pi or any other) to download the `oats-getting-started` skill verbatim and follow it:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- **It asks first:** your project, its repositories and the knowledge tools you use.
|
|
37
|
+
- **It installs OATS and OATS Desktop,** then creates your workspace with its own setup expert, or joins this machine to an existing workspace.
|
|
38
|
+
- **It hands over to that setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
|
|
39
|
+
- **Download it, don't web-fetch it:** a tool that summarises pages would lose its exact commands.
|
|
40
|
+
|
|
28
41
|
## Why OATS
|
|
29
42
|
|
|
30
43
|
OATS grew from a practical need: we wanted control over our agent setups—not just which model answered a prompt, but also:
|
|
@@ -212,7 +225,7 @@ oats onboard ~/acme --workspace git:github.com/acme/agents # this machine's de
|
|
|
212
225
|
oats spawn <soul> --task "First concrete task"
|
|
213
226
|
```
|
|
214
227
|
|
|
215
|
-
The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
|
|
228
|
+
[Start here](#start-here) does all of this for you. The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
|
|
216
229
|
|
|
217
230
|
Further documentation:
|
|
218
231
|
|
package/bin/oats.mjs
CHANGED
|
@@ -2839,9 +2839,8 @@ async function spawnCmd() {
|
|
|
2839
2839
|
// Lineage is explicit: --relation child|sibling|parent|unrelated anchors the new
|
|
2840
2840
|
// instance to --relative-to <instance>. --parent X is sugar for
|
|
2841
2841
|
// --relative-to X --relation child (agents spawning sub-agents pass their own
|
|
2842
|
-
// name, e.g. --parent "$OATS_INSTANCE"). Without a relation, the spawn
|
|
2843
|
-
//
|
|
2844
|
-
// never treated as parentage.
|
|
2842
|
+
// name, e.g. --parent "$OATS_INSTANCE"). Without a relation, the spawn lands
|
|
2843
|
+
// top-level; caller attribution never supplies parentage.
|
|
2845
2844
|
const parent = flag("parent");
|
|
2846
2845
|
if (parent !== undefined && (parent === true || !String(parent).trim())) bail("E_BAD_ARGS", "--parent needs an instance name");
|
|
2847
2846
|
let relation = flag("relation");
|
|
@@ -4829,30 +4828,66 @@ Usage:
|
|
|
4829
4828
|
spawn hooks); --model replaces the recorded model
|
|
4830
4829
|
for this and later starts; a live harness is refused
|
|
4831
4830
|
oats spawn <agent> [--task <text> | --task-file <f>] spawn an instance (tmux; --no-launch
|
|
4832
|
-
[--purpose <slug>
|
|
4833
|
-
[--
|
|
4834
|
-
|
|
4835
|
-
|
|
4836
|
-
|
|
4837
|
-
[--
|
|
4838
|
-
|
|
4839
|
-
[--
|
|
4840
|
-
|
|
4841
|
-
|
|
4842
|
-
|
|
4843
|
-
|
|
4831
|
+
[--purpose <slug> | --name <slug>] = scaffold only); the agent is a workspace
|
|
4832
|
+
[--repo <path>] soul or a capability-defined agent
|
|
4833
|
+
--purpose derives <agent>-<purpose>;
|
|
4834
|
+
--name is exact (no prefix), unused in the
|
|
4835
|
+
deployment, a slug and not a soul name
|
|
4836
|
+
[--dir <scope>] [--agents-root <abs>] deployment scope; --agents-root must match
|
|
4837
|
+
that deployment's agents root
|
|
4838
|
+
[--parent <instance>] sugar for --relative-to X --relation child
|
|
4839
|
+
[--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
|
|
4840
|
+
[--relative-to <instance>] default: unrelated, top-level
|
|
4841
|
+
[--relative-root <agents-root>] disambiguates same-named anchors
|
|
4842
|
+
[--work worktree|checkout|attached|workspace|directory] override the soul's work mode
|
|
4843
|
+
[--work-dir <owner-work>] attached: the owner's work tree (always a child)
|
|
4844
|
+
[--branch <b>] [--base <ref>] worktree branch and starting ref;
|
|
4845
|
+
--base: worktree only; defaults to the soul
|
|
4846
|
+
commit observed by spawn (#445)
|
|
4844
4847
|
directory: owned home/work, config context may
|
|
4845
4848
|
be non-Git; rejects --work-dir and --branch
|
|
4846
|
-
[--
|
|
4847
|
-
|
|
4848
|
-
|
|
4849
|
+
[--harness pi|claude|codex] [--launch-config <name>|none] explicit launch selection;
|
|
4850
|
+
otherwise oats-local.yaml souls.launch.<soul>,
|
|
4851
|
+
then souls.launch."*", then the soul's launch:, then pi;
|
|
4852
|
+
a harness uses its host default configuration if set;
|
|
4853
|
+
none selects the bare harness; a named configuration
|
|
4854
|
+
is a unit (a conflicting --harness is refused)
|
|
4855
|
+
[--model <id>|@native-default] override the selected model; @native-default
|
|
4856
|
+
selects the harness's own model default
|
|
4857
|
+
[--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
|
|
4858
|
+
[--no-launch] [--json] scaffold without launching; JSON result envelope
|
|
4859
|
+
[--allow-child-spawns|--no-child-spawns] this instance's child-spawn policy (default:
|
|
4860
|
+
allowed); enforced by OATS, not an OS sandbox
|
|
4849
4861
|
[--provider <capability> <key>=<value>] a provider setting for this spawn only
|
|
4850
4862
|
(repeatable; dotted keys nest; recorded in
|
|
4851
4863
|
instance.json providers.<capability>)
|
|
4852
|
-
[--preview
|
|
4853
|
-
|
|
4854
|
-
|
|
4855
|
-
|
|
4864
|
+
[--preview] decide everything, create no instance; --json
|
|
4865
|
+
includes the decision revision for confirmation
|
|
4866
|
+
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
4867
|
+
[--idempotency-key <key>] with --expect-decision, replay the completed receipt
|
|
4868
|
+
for the same key and confirmed decision; a different
|
|
4869
|
+
decision conflicts, an unfinished spawn refuses
|
|
4870
|
+
[--max-age <s>] reuse heads up to <s> seconds old (0-86400; 0 live),
|
|
4871
|
+
on preview or --expect-decision apply only;
|
|
4872
|
+
refused with --server; decision binding still holds
|
|
4873
|
+
[--wake-file <json-file> | --wake-json <json-text>] wake object: {cron, tz, message, enabled}
|
|
4874
|
+
--wake-json wins over --wake-file; either overrides
|
|
4875
|
+
--wake-every and --wake-cron
|
|
4876
|
+
[--wake-every <N> | --wake-cron <expr>] alternative: cron */N minutes (1-59) or explicit cron
|
|
4877
|
+
requires --wake-message <text> or --wake-message-file <f>;
|
|
4878
|
+
--wake-message-file wins over --wake-message
|
|
4879
|
+
[--wake-tz <zone>] optional for cron/every (default: local zone);
|
|
4880
|
+
saved after spawn, bound to the new home
|
|
4881
|
+
--runtime <harness> compatibility alias for --harness (deprecated)
|
|
4882
|
+
--instance <name> compatibility token for older routed hosts;
|
|
4883
|
+
refused locally: use --purpose or --name
|
|
4884
|
+
--trigger-event <json-file> internal trigger-runner event input, copied to
|
|
4885
|
+
<home>/.oats/trigger-event.json, exposed through
|
|
4886
|
+
OATS_TRIGGER_EVENT_FILE and recorded in
|
|
4887
|
+
instance.json.trigger (docs/schedules.md)
|
|
4888
|
+
[--help|-h] global help switches: show usage and exit
|
|
4889
|
+
oats spawn <agent> ... --server <id> routed spawn on the server's installed oats;
|
|
4890
|
+
--server is consumed before the local flag scanner
|
|
4856
4891
|
oats retire <instance> [--force] retire an instance (window, hooks,
|
|
4857
4892
|
[--self] worktree, home); --self = retire the
|
|
4858
4893
|
[--keep-dir] [--json] CALLING instance: the window dies, then
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -2241,6 +2241,11 @@ containing them ships. For operator recovery, see
|
|
|
2241
2241
|
|
|
2242
2242
|
## Spawn
|
|
2243
2243
|
|
|
2244
|
+
Use `oats spawn --help` (also the spawn section of `oats help`) for the
|
|
2245
|
+
existing flag inventory, including compatibility and internal inputs. Help
|
|
2246
|
+
needs no deployment; the preview and apply contracts below govern confirmation
|
|
2247
|
+
and replay.
|
|
2248
|
+
|
|
2244
2249
|
### The preview
|
|
2245
2250
|
|
|
2246
2251
|
```text
|
|
@@ -2287,7 +2292,8 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2287
2292
|
([Instance names](#instance-names)). `home` and `worktree` (worktree mode,
|
|
2288
2293
|
else `null`) are canonical: never derive paths.
|
|
2289
2294
|
- `repo`: `--repo`, else the `clones:` entry, else `<deployment>/<member>`.
|
|
2290
|
-
- `branch` defaults to `agents/<instance>` (`--branch
|
|
2295
|
+
- In worktree mode, `branch` defaults to `agents/<instance>` (`--branch <b>`
|
|
2296
|
+
overrides); `base` is
|
|
2291
2297
|
`--base` resolved to `oid`. Without `--base`, when `repo` is a clone of the
|
|
2292
2298
|
soul's repository, `base` is `{ref: <repo key>, oid: <the commit the spawn
|
|
2293
2299
|
observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
|
|
@@ -2495,6 +2501,42 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2495
2501
|
a silent `-2`.
|
|
2496
2502
|
- The name is part of the decision.
|
|
2497
2503
|
|
|
2504
|
+
### Spawn origin
|
|
2505
|
+
|
|
2506
|
+
For new instances from OATS 0.64.0, `spawnOrigin` describes the caller:
|
|
2507
|
+
`instance` when `OATS_INSTANCE` and/or `OATS_INSTANCE_HOME` identify an extant
|
|
2508
|
+
instance home in this deployment, otherwise `operator`. It is recorded in
|
|
2509
|
+
`instance.json` and reported unchanged by the spawn result and status JSON.
|
|
2510
|
+
|
|
2511
|
+
- A home alone must be absolute and resolve canonically to a home here, with a
|
|
2512
|
+
readable instance record whose name agrees with its directory.
|
|
2513
|
+
- A name alone must resolve uniquely to such a home here.
|
|
2514
|
+
- With both supplied, the name and canonical home must agree. An explicit
|
|
2515
|
+
valid home can disambiguate a duplicated historical name.
|
|
2516
|
+
- Invalid, stale, foreign or contradictory supplied evidence records
|
|
2517
|
+
`operator`, with no fallback to another signal. The working directory,
|
|
2518
|
+
`OATS_HOME`, `PI_AGENT_*`, relation and attached ownership do not supply
|
|
2519
|
+
caller identity. A stopped but extant home counts; no process or tmux
|
|
2520
|
+
liveness check is made.
|
|
2521
|
+
|
|
2522
|
+
A shell, Desktop or console caller without valid instance context records
|
|
2523
|
+
`operator`, even with `--parent`. A caller with valid instance context records
|
|
2524
|
+
`instance`, even without a relation. A shell that inherits that context also
|
|
2525
|
+
records `instance`. `parentInstance`, `relativeTo` and `relation` still describe
|
|
2526
|
+
lineage independently; existing child-spawn policy enforcement is unchanged.
|
|
2527
|
+
This field is informational attribution, not agent-authorship proof, an
|
|
2528
|
+
identity credential, a security boundary or an authorization input. There is
|
|
2529
|
+
no flag to choose it.
|
|
2530
|
+
|
|
2531
|
+
For a remote spawn (`--server`), attribution uses the host-side caller context.
|
|
2532
|
+
Caller identity is not forwarded, so the origin is normally `operator`.
|
|
2533
|
+
|
|
2534
|
+
Existing homes keep their recorded value, including the relation-based meaning
|
|
2535
|
+
recorded by earlier kernels; an absent value stays absent in local status.
|
|
2536
|
+
Idempotent spawn replay returns the recorded value. Remote rows relay the
|
|
2537
|
+
host's value unchanged, including historical values, and use `null` when the
|
|
2538
|
+
host does not supply one. Consumers must allow for those historical meanings.
|
|
2539
|
+
|
|
2498
2540
|
<a id="spawn-errors"></a>
|
|
2499
2541
|
### Spawn errors
|
|
2500
2542
|
|
|
@@ -58,7 +58,7 @@ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
|
|
|
58
58
|
a retained dead pane also reads `false`. A wrapper shell with a live non-shell
|
|
59
59
|
descendant still reads `true`. Status shares session inspection's pane rule,
|
|
60
60
|
with one batched pane read per socket/session and one lazy process scan across
|
|
61
|
-
all
|
|
61
|
+
all panes that need it. A recorded server or pane that cannot be read gives
|
|
62
62
|
`running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
|
|
63
63
|
inspect --json` reports the session a new spawn would open in as `session`
|
|
64
64
|
(`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
|
|
@@ -1073,12 +1073,16 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1073
1073
|
wrapper shell included; `false` for a fallback shell (`state: shell`, where
|
|
1074
1074
|
`present` stays `true`), an absent or dead pane or a missing home
|
|
1075
1075
|
(`stopped`) and a home that never launched (`not-launched`). It costs no
|
|
1076
|
-
second observation: at most one process-table read,
|
|
1077
|
-
|
|
1076
|
+
second observation: at most one process-table read, only for a pane whose
|
|
1077
|
+
command is a shell, empty or the literal `unset`. An empty or `unset` label
|
|
1078
|
+
uses the pane PID's own process name from that same scan to establish a shell
|
|
1079
|
+
before checking descendants; an unreadable or non-shell own process stays
|
|
1080
|
+
`unknown` (`running: true`). `running` is activity at the authorized
|
|
1078
1081
|
endpoint. It does not say the agent is generating, idle, healthy or ready
|
|
1079
1082
|
for input, nor that it consumed a wake, and it does not prove which
|
|
1080
|
-
executable runs if a process inside the pane was replaced. When the
|
|
1081
|
-
|
|
1083
|
+
executable runs if a process inside the pane was replaced. When the backend
|
|
1084
|
+
cannot be read, a required process-table read for an explicitly labelled
|
|
1085
|
+
shell fails, or the pane answer is
|
|
1082
1086
|
malformed or split, inspect is an error as before, never `running: false`.
|
|
1083
1087
|
That includes a tmux server that is gone (`no server running on` its
|
|
1084
1088
|
socket, as after a reboot): status reads that row as `running: false`, and
|
package/docs/first-team.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# Run your first OATS team
|
|
2
2
|
|
|
3
|
+
**The quick way:** the README's [Start here](../README.md#start-here): your
|
|
4
|
+
coding agent downloads the `oats-getting-started` skill verbatim and follows
|
|
5
|
+
it. It installs OATS, creates your workspace with its own setup expert soul (or joins
|
|
6
|
+
an existing workspace), and hands over to that expert. This page is the manual
|
|
7
|
+
path, for writing a workspace by hand.
|
|
8
|
+
|
|
3
9
|
The model is in [workspaces.md](workspaces.md), packages in
|
|
4
10
|
[packages.md](packages.md), and the deployment layout this page creates in
|
|
5
11
|
[configuration.md](configuration.md).
|
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.13.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.13.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v5.2.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.29.0` | `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.1`, `5.2.1`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.2.1` or `oats-framework/v1.13.
|
|
54
|
+
convention (`v5.2.1` or `oats-framework/v1.13.3`) 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.13.
|
|
77
|
+
oats.framework: v1.13.3
|
|
78
78
|
oats.okf: v5.2.1
|
|
79
79
|
oats.aweb: v1.29.0
|
|
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.1", "path": "oats-package" },
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.13.3", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.13.
|
|
362
|
-
resolves to tag `oats-framework/v1.13.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.13.3`
|
|
362
|
+
resolves to tag `oats-framework/v1.13.3`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# OATS 0.64.0
|
|
2
|
+
|
|
3
|
+
Unreleased
|
|
4
|
+
|
|
5
|
+
## Upgrade
|
|
6
|
+
|
|
7
|
+
- **Install the Desktop first and the CLI second,** as
|
|
8
|
+
[Upgrading](../upgrading.md) says: a 0.63 Desktop refuses a 0.64.0 CLI. The
|
|
9
|
+
0.64.0 Desktop accepts OATS CLIs `>=0.26.0 <0.65.0`.
|
|
10
|
+
|
|
11
|
+
- **The official catalog moves oats.framework 1.13.2 → 1.13.3** (oats.core
|
|
12
|
+
2.6.5 and oats.setup 2.8.2, see Provider updates). The other packages are
|
|
13
|
+
unchanged. A deployment takes it by moving its `oats.framework` pin and
|
|
14
|
+
running `oats sync`. Only new spawns use it.
|
|
15
|
+
|
|
16
|
+
- **Coming from 0.61 or earlier:** do 0.62.0's Upgrade steps too (the capture
|
|
17
|
+
service's `oats setup`, once per user on each host, from that user's shell).
|
|
18
|
+
|
|
19
|
+
## Changed
|
|
20
|
+
|
|
21
|
+
- **One way in: the README's "Start here" points to the
|
|
22
|
+
`oats-getting-started` skill**, which a person's own coding agent
|
|
23
|
+
downloads verbatim and follows ([#1314](https://github.com/awebai/oats/issues/1314)).
|
|
24
|
+
- **The skill is rewritten.** It asks one round of questions: the use case,
|
|
25
|
+
the existing repositories, the knowledge tools, new or existing
|
|
26
|
+
workspace, messaging, harness and deployment directory.
|
|
27
|
+
- **It installs what is missing,** then OATS Desktop and the CLI at the
|
|
28
|
+
same version (with the pi bridge, `@awebai/oats-pi`, when the harness is
|
|
29
|
+
pi). The Desktop comes from the release asset, downloaded with
|
|
30
|
+
`gh` and checked against `SHA256SUMS.txt` and its attestation; on Linux it
|
|
31
|
+
installs per user and shows in the app launcher.
|
|
32
|
+
- **The GitHub login** is gh's device flow, which the agent starts and the
|
|
33
|
+
person approves in their browser.
|
|
34
|
+
- **A new workspace** becomes a private repository holding the workspace
|
|
35
|
+
file, its membership and one thin soul,
|
|
36
|
+
`<workspace>-oats-setup-expert`, which holds `oats.setup` and has no
|
|
37
|
+
knowledge of its own, so it spawns on a machine before knowledge is set
|
|
38
|
+
up there. It takes the workspace's messaging, so it stays the
|
|
39
|
+
workspace's operator. **An existing workspace** is onboarded as it is;
|
|
40
|
+
when it has messaging, the skill sets it up on the machine before the
|
|
41
|
+
spawn, with an invite token the person types in their own terminal.
|
|
42
|
+
- **Then** the skill spawns the setup expert with the person's answers as
|
|
43
|
+
its task, and the expert does the rest (`/oats-setup-expert`,
|
|
44
|
+
oats.framework 1.13.0). An existing workspace without a setup soul gets
|
|
45
|
+
one first, from its owner, by pull request.
|
|
46
|
+
- The Desktop is started on the new deployment, and the TUI is offered.
|
|
47
|
+
- The person types only passwords, logins and tokens, and no secret passes through
|
|
48
|
+
the agent.
|
|
49
|
+
|
|
50
|
+
- `spawnOrigin` now describes the caller independently of lineage: valid
|
|
51
|
+
instance context in this deployment records `instance`; otherwise `operator`,
|
|
52
|
+
including operator spawns with `--parent`. Existing instances keep their
|
|
53
|
+
recorded values, whose older meaning followed the relation. Attribution is
|
|
54
|
+
informational and does not change permissions (#1371).
|
|
55
|
+
|
|
56
|
+
- Desktop: the command palette (⌘K / Ctrl+Shift+K) now shows the sidebar's
|
|
57
|
+
tree, with the sidebar's lines and state dots, ordered by the instance you
|
|
58
|
+
focused most recently. A group or a parent moves up when you focus any
|
|
59
|
+
instance under it, and a child stays under its parent. This replaces the
|
|
60
|
+
flat Recent group. The palette still opens on the agent you were on before,
|
|
61
|
+
and the sidebar keeps its own name order (#1383).
|
|
62
|
+
|
|
63
|
+
- **OATS Desktop accepts an `oats` CLI 0.64.x.** Its band is now
|
|
64
|
+
`>=0.26.0 <0.65.0`. 0.64 adds no new gate on the band: `spawnOrigin` keeps
|
|
65
|
+
its `instance`/`operator` values, which the Desktop passes through without
|
|
66
|
+
reading, and the Desktop already shows a fallback shell as `shell` (#1387).
|
|
67
|
+
|
|
68
|
+
## Fixed
|
|
69
|
+
|
|
70
|
+
- Shared spawn help now lists the existing `--base <ref>` flag beside `--branch`
|
|
71
|
+
and explains its worktree-only scope and default to the soul commit observed
|
|
72
|
+
by spawn (#1370, #445).
|
|
73
|
+
|
|
74
|
+
- `oats spawn --help` and `oats help` now list the full existing spawn flag
|
|
75
|
+
inventory, including decision replay, scope, launch, child policy and wake
|
|
76
|
+
options, with compatibility and internal inputs labelled. Flag behavior is
|
|
77
|
+
unchanged (#1373).
|
|
78
|
+
|
|
79
|
+
- Status and session inspection now recognize a fallback shell when tmux
|
|
80
|
+
reports an empty or `unset` pane command, so a stopped harness no longer
|
|
81
|
+
appears to be running in that case (#1381).
|
|
82
|
+
|
|
83
|
+
## Provider updates
|
|
84
|
+
|
|
85
|
+
- **oats.framework 1.13.3: oats.core 2.6.5 and oats.setup 2.8.2.** Text
|
|
86
|
+
only: neither capability's floor (`compatibility.oats`) changes.
|
|
87
|
+
- **`/oats-operate`** says what `spawnOrigin` records from OATS 0.64.0: the
|
|
88
|
+
caller's context (`instance` from a valid instance environment in this
|
|
89
|
+
deployment, otherwise `operator`), independent of the relation. It is
|
|
90
|
+
attribution, not a permission check, and a remote spawn records the
|
|
91
|
+
host side. The skill also says how `--branch` and `--base` choose a
|
|
92
|
+
worktree's branch and start point
|
|
93
|
+
([#1371](https://github.com/awebai/oats/issues/1371),
|
|
94
|
+
[#1370](https://github.com/awebai/oats/issues/1370)).
|
|
95
|
+
- **oats.setup names the right OATS version for the getting-started entry
|
|
96
|
+
path.** `/oats-setup-expert`, `/oats-setup-model` and the oats.setup
|
|
97
|
+
briefing said the `oats-getting-started` skill writes the setup expert's
|
|
98
|
+
hand-over and creates its soul from OATS 0.62.0. That skill first ships
|
|
99
|
+
in 0.64.0, and they now say so
|
|
100
|
+
([#1314](https://github.com/awebai/oats/issues/1314)).
|
|
101
|
+
|
|
102
|
+
## Documentation
|
|
103
|
+
|
|
104
|
+
- `docs/first-team.md` opens with the getting-started skill as the quick
|
|
105
|
+
way; the page remains the manual path.
|
|
@@ -306,6 +306,12 @@ soul would, run it from the deployment with `OATS_INSTANCE_HOME` and
|
|
|
306
306
|
|
|
307
307
|
### Spawn
|
|
308
308
|
|
|
309
|
+
`oats spawn --help` lists the existing spawn flags and their conditions; the
|
|
310
|
+
spawn section of `oats help` contains the same inventory. Both work outside a
|
|
311
|
+
deployment. Compatibility and internal inputs are labelled, including the
|
|
312
|
+
locally refused legacy instance selector. For preview confirmation and receipt
|
|
313
|
+
replay, see the [spawn decision and apply contract](desktop-cli-api.md#the-decision).
|
|
314
|
+
|
|
309
315
|
```bash
|
|
310
316
|
oats spawn release-manager --purpose cut-3.2 --task "…" # a soul of a confirmed member
|
|
311
317
|
oats spawn release-manager --preview --json # decide everything, create nothing
|
|
@@ -384,8 +390,7 @@ Spawn lineage is **explicit** and relation-based:
|
|
|
384
390
|
declares what the new instance IS to an existing one (`--parent <instance>` is
|
|
385
391
|
sugar for `--relative-to <instance> --relation child`):
|
|
386
392
|
|
|
387
|
-
- **child**: nests under the anchor: `parentInstance` = anchor
|
|
388
|
-
`spawnOrigin: instance`.
|
|
393
|
+
- **child**: nests under the anchor: `parentInstance` = anchor.
|
|
389
394
|
- **parent**: the NEW instance becomes the anchor's parent: it inherits the
|
|
390
395
|
anchor's old lineage slot, and the anchor's `instance.json` is re-pointed so
|
|
391
396
|
its `parentInstance` is the new instance (a reviewer/maintainer of your work
|
|
@@ -400,15 +405,27 @@ sugar for `--relative-to <instance> --relation child`):
|
|
|
400
405
|
when one exists; when the anchor is a root, the new instance records an
|
|
401
406
|
explicit `siblingInstance` link so the cluster is still derivable from
|
|
402
407
|
`oats status --json` (`parentInstance` + `siblingInstance` edges).
|
|
403
|
-
- **unrelated** (default): no link,
|
|
408
|
+
- **unrelated** (default): no link, top-level.
|
|
404
409
|
|
|
405
410
|
Attached-mode spawns are ALWAYS children of the owner of the shared work tree
|
|
406
411
|
(the instance in whose home the tree is, as its `work/` or as one of its
|
|
407
412
|
extra trees: see [`attached`](#attached--another-instances-tree)),
|
|
408
413
|
because an attached agent serves that owner; relation flags other than a
|
|
409
|
-
redundant child-of-owner are rejected.
|
|
410
|
-
|
|
411
|
-
|
|
414
|
+
redundant child-of-owner are rejected.
|
|
415
|
+
|
|
416
|
+
`spawnOrigin` records the caller independently of these links. For new spawns
|
|
417
|
+
from OATS 0.64.0, it is `instance` when the caller's `OATS_INSTANCE` and/or
|
|
418
|
+
`OATS_INSTANCE_HOME` resolve consistently to an extant home in this deployment;
|
|
419
|
+
otherwise it is `operator`. A stopped home counts. A shell, Desktop or console
|
|
420
|
+
caller without that context records `operator` even with `--parent`; an instance
|
|
421
|
+
caller records `instance` even without a relation. A shell inheriting valid
|
|
422
|
+
instance context also records `instance`. This is informational attribution,
|
|
423
|
+
not a security boundary or a permission check. Existing instances keep their
|
|
424
|
+
recorded value, including the relation-based meaning recorded by older kernels.
|
|
425
|
+
For a remote spawn (`--server`), attribution uses the host-side caller context;
|
|
426
|
+
caller identity is not forwarded, so the origin is normally `operator`.
|
|
427
|
+
See [the caller resolution rules](desktop-cli-api.md#spawn-origin).
|
|
428
|
+
|
|
412
429
|
Agents spawning sub-agents should pass `--parent "$OATS_INSTANCE"` (or the
|
|
413
430
|
relation that fits).
|
|
414
431
|
|
|
@@ -1623,6 +1640,9 @@ as `--repo`, then `oats-local.yaml` `clones:`, then `<deployment>/<member name>`
|
|
|
1623
1640
|
(`E_CLONE_MISSING` / `E_CLONE_MISMATCH` otherwise — see
|
|
1624
1641
|
[configuration.md](configuration.md)).
|
|
1625
1642
|
|
|
1643
|
+
`--branch <b>` overrides the branch name; `--base <ref>` overrides its start
|
|
1644
|
+
point. These options apply to worktree mode.
|
|
1645
|
+
|
|
1626
1646
|
The branch starts at the commit of the soul's repository that the spawn
|
|
1627
1647
|
observed (the one it resolved the soul at), not at what the clone has checked
|
|
1628
1648
|
out: the clone may be a human's checkout or a shared reference, far behind.
|
package/docs/upgrading.md
CHANGED
|
@@ -92,7 +92,8 @@ Desktop accepts CLIs `>=0.26.0 <0.62.0`, and a 0.60 Desktop refuses a 0.61.0 CLI
|
|
|
92
92
|
Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
|
|
93
93
|
release. Read 0.62.0's Upgrade section and keep this order: install the
|
|
94
94
|
Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
|
|
95
|
-
`>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0
|
|
95
|
+
`>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
|
|
96
|
+
Desktop `>=0.26.0 <0.65.0`), then that
|
|
96
97
|
release's CLI and matching pi bridge. Only **after
|
|
97
98
|
installing that CLI**, run its setup conversion once per user on each host,
|
|
98
99
|
from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.13.
|
|
57
|
+
oats.framework: v1.13.3 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.2.1
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
package/lib/core.mjs
CHANGED
|
@@ -3696,6 +3696,30 @@ export function spawnInstance(root, agent, o = {}) {
|
|
|
3696
3696
|
function localMissingForSpawn(agent) {
|
|
3697
3697
|
return oatsError("E_LOCAL_MISSING", `spawning ${agent?.name ?? "an instance"} needs a workspace deployment (oats-local.yaml, found walking up from the deployment): a soul's capabilities are the workspace's resolution, prepared before the spawn — \`oats onboard\` creates the deployment`);
|
|
3698
3698
|
}
|
|
3699
|
+
/** Informational caller attribution, never permission or lineage. Only consistent
|
|
3700
|
+
* runtime identity evidence resolving to an extant home in this deployment counts;
|
|
3701
|
+
* a stopped home still counts. Invalid evidence must not refuse a spawn. */
|
|
3702
|
+
function callerSpawnOrigin(root) {
|
|
3703
|
+
const name = process.env.OATS_INSTANCE, home = process.env.OATS_INSTANCE_HOME;
|
|
3704
|
+
if (name === undefined && home === undefined) return "operator";
|
|
3705
|
+
try {
|
|
3706
|
+
if (name !== undefined && !INSTANCE_NAME_RE.test(name)) return "operator";
|
|
3707
|
+
if (home !== undefined && !isAbsolute(home)) return "operator";
|
|
3708
|
+
let matches;
|
|
3709
|
+
if (home === undefined) {
|
|
3710
|
+
matches = findInstanceHomes(root, name);
|
|
3711
|
+
if (matches.length !== 1) return "operator";
|
|
3712
|
+
}
|
|
3713
|
+
const canonical = realpathSync(home ?? matches[0].home);
|
|
3714
|
+
// Name lookup's immediate-child check also applies to the agents root: an
|
|
3715
|
+
// instances/ directory symlinked to another deployment cannot qualify it.
|
|
3716
|
+
if (basename(dirname(canonical)) !== "instances" || dirname(dirname(dirname(canonical))) !== realpathSync(root)) return "operator";
|
|
3717
|
+
const record = readHomeRecord(canonical);
|
|
3718
|
+
if (record.state !== "record" || record.meta.instance !== basename(canonical) || (name !== undefined && record.meta.instance !== name)) return "operator";
|
|
3719
|
+
matches ??= findInstanceHomes(root, record.meta.instance);
|
|
3720
|
+
return matches.some((m) => realpathSync(m.home) === canonical) ? "instance" : "operator";
|
|
3721
|
+
} catch { return "operator"; }
|
|
3722
|
+
}
|
|
3699
3723
|
export async function spawnInstanceAsync(root, agent, o = {}) {
|
|
3700
3724
|
const it = spawnBody(root, agent, o);
|
|
3701
3725
|
let step = it.next();
|
|
@@ -3714,6 +3738,8 @@ function unconfirmedSpawn(error) {
|
|
|
3714
3738
|
return error;
|
|
3715
3739
|
}
|
|
3716
3740
|
function* spawnBody(root, agent, o = {}) {
|
|
3741
|
+
// Capture the caller before target scaffolding or hooks supply the new instance's identity.
|
|
3742
|
+
const spawnOrigin = callerSpawnOrigin(root);
|
|
3717
3743
|
if (!o.prepared) throw localMissingForSpawn(agent);
|
|
3718
3744
|
const deliver = (r) => r;
|
|
3719
3745
|
const work = o.work || agent.work || "checkout";
|
|
@@ -3845,12 +3871,8 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3845
3871
|
// never leaves a half-created home behind. ATTACHED mode is special by design
|
|
3846
3872
|
// decision: an attached agent shares its owner's work tree and is ALWAYS the
|
|
3847
3873
|
// owner's child — relation flags that say anything else are contradictory and
|
|
3848
|
-
// rejected.
|
|
3849
|
-
//
|
|
3850
|
-
// opened inside an agent's tmux window inherits those vars, and env inheritance
|
|
3851
|
-
// is not evidence of intent — human spawns from such shells were misattributed
|
|
3852
|
-
// as instance-origin. Manual spawns land top-level unless a relation is
|
|
3853
|
-
// explicitly given (operator directive).
|
|
3874
|
+
// rejected. Caller identity is attribution only: it never supplies a lineage
|
|
3875
|
+
// edge. Without an explicit relation a spawn stays top-level.
|
|
3854
3876
|
const legacyParent = typeof o.parent === "string" && o.parent.trim() ? o.parent.trim() : undefined;
|
|
3855
3877
|
let relation = typeof o.relation === "string" && o.relation.trim() ? o.relation.trim() : undefined;
|
|
3856
3878
|
let relativeTo = typeof o.relativeTo === "string" && o.relativeTo.trim() ? o.relativeTo.trim() : undefined;
|
|
@@ -4900,7 +4922,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4900
4922
|
siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
|
|
4901
4923
|
relation: relation || undefined,
|
|
4902
4924
|
relativeTo: relation ? relativeTo : undefined,
|
|
4903
|
-
spawnOrigin
|
|
4925
|
+
spawnOrigin,
|
|
4904
4926
|
policy: { childSpawns: ownChildPolicy },
|
|
4905
4927
|
...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo ?? null, number: o.triggerEvent.number ?? null, subject: o.triggerEvent.subject ?? null, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile,
|
|
4906
4928
|
// A capability source's event carries its declared fields (a pull request's never does).
|
package/lib/session-input.mjs
CHANGED
|
@@ -5,6 +5,7 @@ import { randomUUID } from "node:crypto";
|
|
|
5
5
|
import { performance } from "node:perf_hooks";
|
|
6
6
|
|
|
7
7
|
const shells = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "login"]);
|
|
8
|
+
const isShellProcess = (name) => shells.has(basename(name).replace(/^-/, ""));
|
|
8
9
|
function tmux(target, args, { exec = execFileSync, input, timeout = 10000, killSignal } = {}) {
|
|
9
10
|
// launchd does not supply a UTF-8 locale. In that environment tmux replaces
|
|
10
11
|
// the tab delimiters in list-panes output with underscores unless forced.
|
|
@@ -55,7 +56,16 @@ export function createSessionPaneInspector(io) {
|
|
|
55
56
|
throw new Error("invalid tmux pane response");
|
|
56
57
|
}
|
|
57
58
|
let state = dead === "1" ? "stopped" : "unknown";
|
|
58
|
-
|
|
59
|
+
let shell = shells.has(command);
|
|
60
|
+
if (dead === "0" && (command === "" || command === "unset") && /^\d+$/.test(panePid)) {
|
|
61
|
+
// A missing tmux label can still be a fallback shell. Only the pane's
|
|
62
|
+
// own comm can establish that; an optional failed read stays unknown.
|
|
63
|
+
try {
|
|
64
|
+
const own = readProcesses().find(([, pid]) => pid === panePid);
|
|
65
|
+
shell = own ? isShellProcess(own[3]) : false;
|
|
66
|
+
} catch { /* missing process information is not proof of a fallback shell */ }
|
|
67
|
+
}
|
|
68
|
+
if (dead === "0" && shell) {
|
|
59
69
|
// macOS tmux can report the wrapper shell while the harness is its child.
|
|
60
70
|
// Only a shell with no non-shell descendants is a fallback prompt.
|
|
61
71
|
if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
|
|
@@ -67,7 +77,7 @@ export function createSessionPaneInspector(io) {
|
|
|
67
77
|
for (const [, pid, parent, name] of processes) {
|
|
68
78
|
if (descendants.has(parent) && !descendants.has(pid)) {
|
|
69
79
|
descendants.add(pid); changed = true;
|
|
70
|
-
if (!
|
|
80
|
+
if (!isShellProcess(name)) active = true;
|
|
71
81
|
}
|
|
72
82
|
}
|
|
73
83
|
}
|
package/package-catalog.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.64.0",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.65.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
|
|
|
52
52
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
53
53
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
54
54
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 65, 0] };
|
|
56
56
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
57
|
* rejection reason, the backend's /api status and the degradation card can
|
|
58
58
|
* never disagree with the numbers actually enforced above. */
|