@awebai/oats 0.69.1 → 0.69.2
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 +79 -15
- package/docs/capabilities.md +24 -5
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
- package/docs/design/2026-10-22-module-upgrade.md +1 -1
- package/docs/desktop-cli-api.md +260 -28
- package/docs/desktop-instance-start.md +8 -37
- package/docs/desktop.md +76 -9
- package/docs/execution-targets.md +27 -5
- package/docs/implementation.md +6 -5
- package/docs/integrations.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/servers.md +7 -2
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +35 -2
- package/docs/tui.md +100 -9
- package/docs/upgrading.md +9 -5
- package/docs/workspaces.md +2 -2
- package/injects/instance-boundary.md +19 -33
- package/injects/work-attached.md +8 -13
- package/injects/work-checkout.md +16 -30
- package/injects/work-directory.md +9 -15
- package/injects/work-workspace.md +8 -19
- package/injects/work-worktree.md +18 -33
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +162 -49
- package/lib/instance-background.mjs +54 -0
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +35 -0
- package/lib/instance-resolution.mjs +3 -2
- package/lib/instance-same-work.mjs +67 -0
- package/lib/instance-upgrade.mjs +18 -0
- package/lib/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/servers.mjs +19 -4
- package/lib/session-resume-contract.mjs +1 -0
- package/lib/session-resume.mjs +36 -9
- package/lib/soul-composition.mjs +13 -10
- package/lib/workspace.mjs +3 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +30 -8
- package/packages/client/deployment-data.mjs +9 -0
- package/packages/client/deployment-panel.mjs +4 -0
- package/packages/client/instance-tree.mjs +64 -14
- package/packages/client/panel-views.mjs +11 -3
- package/packages/client/remote-roster.mjs +5 -1
- package/packages/client/roster-sections.mjs +50 -6
- package/packages/client/same-work.mjs +49 -0
- package/packages/client/session-resume.mjs +1 -1
- package/packages/client/soul-rows.mjs +2 -0
- package/packages/client/spawn-apply-contract.mjs +2 -1
- package/packages/client/spawn-decision.mjs +4 -1
- package/packages/client/spawn-preview-contract.mjs +12 -1
- package/packages/client/spawn-preview.mjs +2 -0
- package/packages/tui/README.md +2 -2
- package/packages/tui/lib/client.mjs +6 -2
- package/packages/tui/lib/main.mjs +44 -11
- package/packages/tui/lib/model.mjs +101 -43
- package/packages/tui/lib/store.mjs +76 -20
- package/packages/tui/lib/views/frame.mjs +2 -0
- package/packages/tui/lib/views/help.mjs +2 -0
- package/packages/tui/lib/views/instances.mjs +38 -1
- package/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -1,42 +1,28 @@
|
|
|
1
1
|
## Your two directories
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repository
|
|
6
|
-
root, and not the work tree. Anything that says "your home" means this directory.
|
|
3
|
+
**IMPORTANT: ALWAYS FOLLOW THESE INSTRUCTIONS FOR WORKING**, here and in your
|
|
4
|
+
work-mode block below.
|
|
7
5
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
and from where), and whatever working state your role keeps — your knowledge
|
|
11
|
-
layer names those files, if you have one. They belong here, not in the work
|
|
12
|
-
tree.
|
|
13
|
-
- **Run OATS operational/lifecycle commands, and commands from active
|
|
14
|
-
capabilities, from instance home** — `oats status`, `oats doctor`, `oats spawn`,
|
|
15
|
-
and whatever your own capabilities add; for example, when the
|
|
16
|
-
aweb messaging capability is active, run `aw` there too. They resolve their
|
|
17
|
-
scope from the directory you run them in, so running them from the work tree
|
|
18
|
-
points them at the wrong deployment. To act on a different package or config
|
|
19
|
-
scope deliberately, pass an explicit resolved path: `oats <cmd> --dir <path>`.
|
|
20
|
-
- **Soul work is repository work.** If your TASK is to change soul content that
|
|
21
|
-
lives in this repository, that is ordinary code work — do it on tracked paths
|
|
22
|
-
under `work/`, reviewed like the rest. How your own learnings reach your soul
|
|
23
|
-
is your knowledge capability's business, and its instructions below say so if you
|
|
24
|
-
have one.
|
|
6
|
+
**Your home is where this session starts** (`$OATS_INSTANCE_HOME`). It is not
|
|
7
|
+
your user home (`~`), not the repository root, and not the work tree.
|
|
25
8
|
|
|
26
|
-
|
|
27
|
-
|
|
9
|
+
- It holds your brain and state: `AGENTS.md`, `TASK.md`, `instance.json` and
|
|
10
|
+
your role's working state. Never put them in `./work`.
|
|
11
|
+
- **ALWAYS run OATS commands, and commands from active capabilities, from
|
|
12
|
+
instance home** (for example, when the aweb messaging capability is active,
|
|
13
|
+
`aw` too): they resolve their scope from where you run them. For another
|
|
14
|
+
scope on purpose: `oats <cmd> --dir <path>`.
|
|
15
|
+
|
|
16
|
+
**`<instance-home>/work` is your repository or workspace view**, as your work
|
|
17
|
+
mode grants it.
|
|
28
18
|
|
|
29
19
|
- **Repository work happens there, or in the extra trees your mode block
|
|
30
20
|
grants, and nowhere else**: reading, editing, building, testing, git and
|
|
31
21
|
commits, on repository content. Never from the main checkout or from your
|
|
32
22
|
home root, beyond what your mode block names.
|
|
33
|
-
- **What your mode permits is the mode block's call
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
script), go where your task and tooling direct.
|
|
40
|
-
|
|
41
|
-
Move between the two as the task needs — the boundary is what each directory is
|
|
42
|
-
*for*, not a place to settle in.
|
|
23
|
+
- **What your mode permits is the mode block's call**: your mode block, below,
|
|
24
|
+
is the authority.
|
|
25
|
+
- If your TASK is to change soul content that lives in this repository, that is
|
|
26
|
+
ordinary repository work. How your own learnings reach your soul is your
|
|
27
|
+
knowledge capability's business.
|
|
28
|
+
- Reports and scratch files go where your task and tooling direct.
|
package/injects/work-attached.md
CHANGED
|
@@ -1,16 +1,11 @@
|
|
|
1
1
|
## Work mode: attached
|
|
2
2
|
|
|
3
|
-
Your `./work` is
|
|
4
|
-
|
|
3
|
+
Your `./work` is **another instance's work tree**, its branch and uncommitted
|
|
4
|
+
state. You are a guest.
|
|
5
5
|
|
|
6
|
-
- **
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
- Retiring you never removes the shared tree — cleanup of the tree is the
|
|
13
|
-
owner's concern, not yours.
|
|
14
|
-
|
|
15
|
-
This mode fits service agents (harvesters, reviewers, fixers) that operate
|
|
16
|
-
on a live instance's work in flight.
|
|
6
|
+
- **NEVER switch branches, rebase or reset.** Make focused additions on top of
|
|
7
|
+
the owner's current state; keep changes and commits small, and name yourself
|
|
8
|
+
in commit messages where authorship could be unclear.
|
|
9
|
+
- Leave files the owner is editing alone unless your task says otherwise; when
|
|
10
|
+
unsure, ask through your messaging capability or your spawner.
|
|
11
|
+
- The tree's cleanup is its owner's; retiring you never removes it.
|
package/injects/work-checkout.md
CHANGED
|
@@ -1,40 +1,26 @@
|
|
|
1
1
|
## Work mode: checkout
|
|
2
2
|
|
|
3
|
-
Your `./work` is
|
|
4
|
-
in the same tree
|
|
3
|
+
Your `./work` is the repository's **shared checkout**: the human and other
|
|
4
|
+
agents work in the same tree.
|
|
5
5
|
|
|
6
|
-
- **
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
of another branch) without an explicit human instruction.
|
|
6
|
+
- **Stay on the checked-out branch; never switch unless explicitly asked.**
|
|
7
|
+
- **NO destructive git** (reset --hard, rebase, force-push, checking out
|
|
8
|
+
another branch) without an explicit human instruction.
|
|
10
9
|
- Work that needs its own branch goes in an extra tree, not in `work/`.
|
|
11
10
|
|
|
12
11
|
### Extra trees
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
existing one):
|
|
13
|
+
For another branch or repository, from your home (`--preview` first; `--repo
|
|
14
|
+
<member key|clone path>` for another repository; `<base>`: the remote branch
|
|
15
|
+
to start from, or the one you rework):
|
|
18
16
|
|
|
19
17
|
oats worktree add --purpose <purpose> --branch <branch> --base <base>
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
Never `-C`/`-B`, which reset a branch someone else may own.
|
|
30
|
-
- If a capability of yours sets up new trees, `add` runs that setup, which
|
|
31
|
-
may take minutes: give it a long timeout, or run it in the background and
|
|
32
|
-
wait for it to exit. A killed `add` rolls back; run it again. Once it has
|
|
33
|
-
finished, running it again with the same arguments does nothing.
|
|
34
|
-
- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
|
|
35
|
-
(`<base>` when you rework an existing branch).
|
|
36
|
-
- Before your task closes, merge each extra tree into your PR branch, or push its
|
|
37
|
-
branch and name it in your hand-back; then
|
|
38
|
-
`oats worktree remove --purpose <purpose>`, which keeps the branch and
|
|
39
|
-
refuses a tree with uncommitted work.
|
|
40
|
-
Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
|
|
19
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
20
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
21
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
22
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
23
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
24
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
25
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
26
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
|
@@ -1,18 +1,12 @@
|
|
|
1
1
|
## Work mode: directory
|
|
2
2
|
|
|
3
|
-
Your `./work` is an **instance-owned execution directory
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
to edit that directory.
|
|
3
|
+
Your `./work` is an **instance-owned execution directory**, not a Git worktree,
|
|
4
|
+
checkout or link. The `repo` recorded for you supplies configuration only; it
|
|
5
|
+
grants no permission to edit the `repo` directory.
|
|
7
6
|
|
|
8
|
-
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
- Keep canonical instructions in the instance's `AGENTS.md`; `CLAUDE.md` is its
|
|
15
|
-
compatibility symlink. Run OATS lifecycle/capability commands from home.
|
|
16
|
-
- Retirement removes the execution directory only after nonempty work has a
|
|
17
|
-
verified copy in the reported recovery storage beside the home. Recovery is
|
|
18
|
-
not publication: deliver your results through the task's own protocol first.
|
|
7
|
+
- Work inside `./work`. **Never initialize a fake repository**; a containing
|
|
8
|
+
repository Git discovers is not yours.
|
|
9
|
+
- Use external inputs and destinations only as your task and capabilities
|
|
10
|
+
explicitly authorize.
|
|
11
|
+
- Deliver results through your task's own protocol before you finish: the
|
|
12
|
+
recovery copy kept at retirement is not publication.
|
|
@@ -1,22 +1,11 @@
|
|
|
1
1
|
## Work mode: workspace
|
|
2
2
|
|
|
3
|
-
Your `./work` is the **whole workspace
|
|
4
|
-
|
|
5
|
-
cross-repo coordinator: your product is routing, analysis, and coordination —
|
|
6
|
-
not code changes.
|
|
3
|
+
Your `./work` is the **whole workspace**, not one repository. You route,
|
|
4
|
+
analyse and coordinate; you do not change code.
|
|
7
5
|
|
|
8
|
-
- **Read freely across
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
and needs no git ceremony.
|
|
15
|
-
- If one of your capabilities delivers durable updates into a repo, its own
|
|
16
|
-
instructions define where and how — including whether anything is committed at
|
|
17
|
-
all, and by whom. That is its business, not an exception you take into a
|
|
18
|
-
member repo yourself.
|
|
19
|
-
|
|
20
|
-
This mode fits coordinators, dispatchers, architects, and analysts whose
|
|
21
|
-
scope is the workspace itself; if a task needs actual edits in one repo, ask
|
|
22
|
-
for (or route to) a worktree-mode instance of that repo's agent instead.
|
|
6
|
+
- **Read freely across member repositories; never edit or commit inside them,
|
|
7
|
+
and NEVER change their Git state** (no branch switches, resets, pulls,
|
|
8
|
+
stashes or worktrees). Route a repository change to that repository's agents
|
|
9
|
+
or to your human.
|
|
10
|
+
- A capability that delivers updates into a repository follows its own
|
|
11
|
+
instructions; that is not an exception you take yourself.
|
package/injects/work-worktree.md
CHANGED
|
@@ -1,42 +1,27 @@
|
|
|
1
1
|
## Work mode: worktree
|
|
2
2
|
|
|
3
|
-
Your `./work` is a **git worktree on your own branch
|
|
4
|
-
|
|
3
|
+
Your `./work` is a **git worktree on your own branch**, yours alone: build,
|
|
4
|
+
test and commit there.
|
|
5
5
|
|
|
6
|
-
- **
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
and merged like code.
|
|
12
|
-
- Leave your branch and the worktree list clean when your task closes.
|
|
6
|
+
- **NEVER work in a shared checkout** (the main checkout, or a clone others
|
|
7
|
+
use). Touch a clone only through `oats worktree add`/`remove`. If unsure, `pwd`.
|
|
8
|
+
- Every repository change, **your own soul included**, is a change on your
|
|
9
|
+
branch or an extra tree's, reviewed and merged like code. Leave your branch
|
|
10
|
+
and worktree list clean at the end.
|
|
13
11
|
|
|
14
12
|
### Extra trees
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
existing one):
|
|
14
|
+
For another branch or repository, from your home (`--preview` first; `--repo
|
|
15
|
+
<member key|clone path>` for another repository; `<base>`: the remote branch
|
|
16
|
+
to start from, or the one you rework):
|
|
20
17
|
|
|
21
18
|
oats worktree add --purpose <purpose> --branch <branch> --base <base>
|
|
22
19
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
Never `-C`/`-B`, which reset a branch someone else may own.
|
|
32
|
-
- If a capability of yours sets up new trees, `add` runs that setup, which
|
|
33
|
-
may take minutes: give it a long timeout, or run it in the background and
|
|
34
|
-
wait for it to exit. A killed `add` rolls back; run it again. Once it has
|
|
35
|
-
finished, running it again with the same arguments does nothing.
|
|
36
|
-
- The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
|
|
37
|
-
(`<base>` when you rework an existing branch).
|
|
38
|
-
- Before your task closes, merge each extra tree into your PR branch, or push its
|
|
39
|
-
branch and name it in your hand-back; then
|
|
40
|
-
`oats worktree remove --purpose <purpose>`, which keeps the branch and
|
|
41
|
-
refuses a tree with uncommitted work.
|
|
42
|
-
Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
|
|
20
|
+
- Name `<branch>` by the repository's rules, else `agents/<instance>-<purpose>`
|
|
21
|
+
(if taken, `<instance>/<branch>`). Never reset a branch with `-B`/`-C`.
|
|
22
|
+
- `add` may take minutes: use a long timeout; if killed, rerun it.
|
|
23
|
+
- Push with `git push origin HEAD:<remote-branch>` (`<base>` when reworking).
|
|
24
|
+
- Before you finish, merge each tree into your PR branch, or push it and name
|
|
25
|
+
it in your hand-back; then `oats worktree remove --purpose <purpose>`.
|
|
26
|
+
Retirement may keep a tree with uncommitted work; don't rely on it.
|
|
27
|
+
Details: `oats worktree --help`, and `/oats-operate` if you have it.
|
|
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
|
|
|
181
181
|
* declaration may not cover them: these exact names, and every exact name
|
|
182
182
|
* starting with one of these prefixes (the events log; the stop, restart and
|
|
183
183
|
* start receipts and locks; the rollback marker; AGENTS.md backups; the
|
|
184
|
-
* attachments directory; the instance colour, `.oats-color.json`). This is the one list: a new kernel-written top-level
|
|
184
|
+
* attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
|
|
185
185
|
* home entry MUST be added here and to the `not` patterns of
|
|
186
186
|
* `retirement.disposable.home` in docs/capability-manifest.schema.json. A
|
|
187
187
|
* prefix declaration can reach none of them except through `.oats-`, which is
|
|
188
188
|
* refused whole; `.oats-<provider>` as an exact name stays declarable. */
|
|
189
189
|
const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
|
|
190
|
-
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color"];
|
|
190
|
+
const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-same-work"];
|
|
191
191
|
|
|
192
192
|
/** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
|
|
193
193
|
* name or prefix), "kernel-owned", or undefined when it is sound. */
|