@awebai/oats 0.60.0 → 0.62.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 +15 -19
- package/bin/oats.mjs +68 -21
- package/docs/capabilities.md +1 -1
- package/docs/configuration.md +9 -0
- package/docs/desktop-cli-api.md +28 -5
- package/docs/desktop.md +7 -0
- package/docs/execution-targets.md +49 -3
- package/docs/first-team.md +8 -0
- package/docs/implementation.md +2 -1
- package/docs/named-test-runs.md +382 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.61.0.md +155 -0
- package/docs/release-notes/v0.62.0.md +223 -0
- package/docs/tui.md +10 -4
- package/docs/upgrading.md +133 -11
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +2 -2
- package/lib/doctor-capture.mjs +35 -0
- package/lib/session-viewer.mjs +86 -7
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/instance-presentation.mjs +10 -0
- package/packages/client/instance-tree.mjs +48 -6
- package/packages/record/README.md +87 -13
- package/packages/record/bin/capture-hook.mjs +8 -0
- package/packages/record/bin/capture.mjs +143 -124
- package/packages/record/bin/recall.mjs +8 -3
- package/packages/record/bin/setup.mjs +115 -225
- package/packages/record/bin/turn-record.mjs +2 -2
- package/packages/record/docs/capture-service.md +1443 -28
- package/packages/record/docs/capture-status.schema.json +429 -12
- package/packages/record/lib/capture-admission.mjs +82 -0
- package/packages/record/lib/capture-aw-unit.mjs +137 -0
- package/packages/record/lib/capture-aw.mjs +31 -12
- package/packages/record/lib/capture-budget.mjs +31 -0
- package/packages/record/lib/capture-cc.mjs +39 -6
- package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
- package/packages/record/lib/capture-cleanup-work.mjs +77 -0
- package/packages/record/lib/capture-command-operation.mjs +37 -0
- package/packages/record/lib/capture-command-output.mjs +61 -0
- package/packages/record/lib/capture-command-worker.mjs +6 -0
- package/packages/record/lib/capture-command.mjs +48 -0
- package/packages/record/lib/capture-completion.mjs +152 -0
- package/packages/record/lib/capture-context.mjs +50 -0
- package/packages/record/lib/capture-default-roots.mjs +30 -0
- package/packages/record/lib/capture-discovery.mjs +114 -0
- package/packages/record/lib/capture-failures.mjs +45 -0
- package/packages/record/lib/capture-health-doctor.mjs +13 -0
- package/packages/record/lib/capture-health-installation.mjs +117 -0
- package/packages/record/lib/capture-health.mjs +116 -0
- package/packages/record/lib/capture-hook-ownership.mjs +58 -0
- package/packages/record/lib/capture-hook-runner.mjs +17 -0
- package/packages/record/lib/capture-hook.mjs +26 -0
- package/packages/record/lib/capture-index-inventory.mjs +205 -0
- package/packages/record/lib/capture-index-outcomes.mjs +113 -0
- package/packages/record/lib/capture-index-reset.mjs +109 -0
- package/packages/record/lib/capture-index-work.mjs +77 -0
- package/packages/record/lib/capture-issue-preparation.mjs +73 -0
- package/packages/record/lib/capture-issues.mjs +15 -2
- package/packages/record/lib/capture-lock.mjs +102 -16
- package/packages/record/lib/capture-native-unit.mjs +322 -0
- package/packages/record/lib/capture-pass.mjs +102 -0
- package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
- package/packages/record/lib/capture-retained-scratch.mjs +213 -0
- package/packages/record/lib/capture-retry.mjs +102 -0
- package/packages/record/lib/capture-run.mjs +125 -0
- package/packages/record/lib/capture-scratch.mjs +12 -3
- package/packages/record/lib/capture-service-definition.mjs +104 -0
- package/packages/record/lib/capture-service-install.mjs +362 -0
- package/packages/record/lib/capture-service-ownership.mjs +137 -0
- package/packages/record/lib/capture-service-runner.mjs +18 -0
- package/packages/record/lib/capture-small-snapshot.mjs +85 -0
- package/packages/record/lib/capture-source-discovery.mjs +319 -0
- package/packages/record/lib/capture-source-queue.mjs +199 -0
- package/packages/record/lib/capture-source-work.mjs +85 -0
- package/packages/record/lib/capture-state.mjs +16 -71
- package/packages/record/lib/capture-status.mjs +171 -0
- package/packages/record/lib/capture-supervisor.mjs +117 -0
- package/packages/record/lib/capture-watch.mjs +32 -0
- package/packages/record/lib/capture-work-session.mjs +238 -0
- package/packages/record/lib/capture-worker.mjs +58 -0
- package/packages/record/lib/derived-state.mjs +28 -15
- package/packages/record/lib/file-lines.mjs +22 -6
- package/packages/record/lib/formats.mjs +4 -3
- package/packages/record/lib/index-capture.mjs +97 -0
- package/packages/record/lib/index-db.mjs +3 -17
- package/packages/record/lib/index-reset.mjs +19 -0
- package/packages/record/lib/store.mjs +36 -11
- package/packages/record/lib/transcript-prefix.mjs +125 -0
- package/packages/tui/lib/client.mjs +2 -2
- package/packages/tui/lib/model.mjs +15 -5
- package/packages/tui/lib/views/palette.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +1 -1
- package/docs/macos-test-runs.md +0 -246
package/README.md
CHANGED
|
@@ -1,33 +1,29 @@
|
|
|
1
1
|
# OATS: an open framework for specialised agent teams
|
|
2
2
|
|
|
3
|
-
**Free, open source, provider-agnostic, and decentralised by design.**
|
|
3
|
+
**Free, open source, provider- and harness-agnostic, and decentralised by design.**
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@awebai/oats)
|
|
6
6
|
[](https://github.com/awebai/oats/releases)
|
|
7
7
|
[](https://nodejs.org/)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
OATS—**Open Agent Team Specification**—is a framework for building
|
|
10
|
+
OATS—**Open Agent Team Specification**—is a provider- and harness-agnostic framework for building distributed agent teams: on one laptop, across machines or across a large organisation, as flexibly as you need. It is completely free and open source.
|
|
11
11
|
|
|
12
|
-
**
|
|
12
|
+
- **Every agent keeps the full power of its harness.** Claude Code, Codex or pi: OATS connects them, so agents on different harnesses and providers communicate and work together.
|
|
13
|
+
- **The CLI and contracts set up the team; capabilities shape it.** Choose the agents, the tools you already use and how they coordinate. We ship opinionated defaults that we think work well, and you can change or replace any of them.
|
|
14
|
+
- **You keep control** of messaging, knowledge, coordination and anything else your team does, so your knowledge, workflows and team structure outlast any model or platform.
|
|
15
|
+
- **So you don't lose your head as the threads multiply,** there are two clients: **OATS Desktop**, a free, fully integrated ADE (an agentic IDE), and **`oats tui`** for the terminal (in preview).
|
|
16
|
+
- **Built on what you already use:** Git, GitHub or GitLab, and your agent harnesses. No OATS account, central server or OATS-hosted database; integrations you choose may run their own.
|
|
13
17
|
|
|
14
|
-
|
|
18
|
+
For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has its own for its area. Through capabilities you decide:
|
|
15
19
|
|
|
16
|
-
|
|
20
|
+
- which specialists make up the team;
|
|
21
|
+
- which models and harnesses their instances use;
|
|
22
|
+
- where their knowledge lives and how it grows;
|
|
23
|
+
- which skills, tools and workflows they receive;
|
|
24
|
+
- how they communicate and coordinate.
|
|
17
25
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- Which specialists make up the team.
|
|
21
|
-
- Which models and harnesses their instances use.
|
|
22
|
-
- Where their knowledge lives and how it develops.
|
|
23
|
-
- Which skills, tools and workflows they receive.
|
|
24
|
-
- How they communicate and coordinate.
|
|
25
|
-
|
|
26
|
-
These choices determine how your team operates and where the value of its work accumulates. Keeping them under your control means your knowledge, workflows and team structure can outlast any particular model or platform.
|
|
27
|
-
|
|
28
|
-
OATS also provides **OATS Desktop: a free, fully integrated ADE—an agentic IDE**. It brings your team, its work and its agent sessions into one place, making day-to-day collaboration with your agents clearer and more pleasant.
|
|
29
|
-
|
|
30
|
-
OATS builds on tools you already use—**Git, GitHub or GitLab, and your preferred agent harnesses**. People can share agent definitions, knowledge and workflows across projects without an OATS account, a central OATS server or an OATS-hosted database. Selected integrations may use their own servers or databases; those are your choices, not a mandatory OATS service.
|
|
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.
|
|
31
27
|
|
|
32
28
|
## Why OATS
|
|
33
29
|
|
|
@@ -235,7 +231,7 @@ This README explains the framework and its direction. Advanced mechanisms such a
|
|
|
235
231
|
|
|
236
232
|
## Contributing and releases
|
|
237
233
|
|
|
238
|
-
Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS can be run on a
|
|
234
|
+
Source, issues and pull requests live at [awebai/oats](https://github.com/awebai/oats). See the [implementation guide](docs/implementation.md) for repository details and the [release lane](docs/release-lane.md) for artifact verification and publication. Tests that depend on macOS, or on a Linux user's systemd manager, can be run by hand on a hosted runner: see [named test runs](docs/named-test-runs.md).
|
|
239
235
|
|
|
240
236
|
Versioned releases publish the kernel, Pi bridge and Desktop installers. Check the [release notes](docs/release-notes/) before changing an existing deployment; installing software does not automatically migrate knowledge or reconfigure live agents.
|
|
241
237
|
|
package/bin/oats.mjs
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* oats — the OATS command line.
|
|
4
4
|
*
|
|
5
|
-
* oats doctor [dir] [--soul <s>] [--json] show
|
|
5
|
+
* oats doctor [dir] [--soul <s>] [--json] show deployment and offline capture warnings; --soul: composition only
|
|
6
6
|
* oats onboard [<dir>] --workspace <ref> realize a workspace here (oats-local.yaml +
|
|
7
7
|
* agents/), then sync
|
|
8
8
|
* oats sync [--dir <d>] [--plan] [--json] discover the workspace, confirm membership,
|
|
@@ -25,6 +25,7 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
|
|
|
25
25
|
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
|
+
import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
|
|
28
29
|
import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
29
30
|
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
|
|
30
31
|
import {
|
|
@@ -44,7 +45,7 @@ import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlo
|
|
|
44
45
|
import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
|
|
45
46
|
import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
|
|
46
47
|
import { terminalText } from "../lib/refused-text.mjs";
|
|
47
|
-
import { soulsOffered } from "../lib/instance-resolution.mjs";
|
|
48
|
+
import { qualifiedSoulName, soulCandidates, soulsOffered } from "../lib/instance-resolution.mjs";
|
|
48
49
|
import { parseConfigData } from "../lib/config-data.mjs";
|
|
49
50
|
import * as remoteModule from "../lib/remote.mjs";
|
|
50
51
|
import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
|
|
@@ -829,7 +830,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
829
830
|
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
830
831
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
831
832
|
...(problems.length ? { problems } : {}),
|
|
832
|
-
warnings: hookEvents.warnings,
|
|
833
|
+
warnings: [...hookEvents.warnings, ...(soulName ? [] : doctorCaptureWarnings())],
|
|
833
834
|
};
|
|
834
835
|
}
|
|
835
836
|
/** Kernel/bridge version skew (published in lockstep from one tag), in every pi folder a launch
|
|
@@ -876,6 +877,7 @@ async function doctor(dir) {
|
|
|
876
877
|
for (const p of launchPreferences.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
877
878
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
878
879
|
for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
|
|
880
|
+
if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
|
|
879
881
|
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
880
882
|
for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
|
|
881
883
|
if (soulName) {
|
|
@@ -3463,7 +3465,13 @@ async function sessionCmd() {
|
|
|
3463
3465
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3464
3466
|
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3465
3467
|
// status 20. Without it every key reaches the agent and there is no keyboard exit.
|
|
3466
|
-
|
|
3468
|
+
// What earlier attaches left (a viewer whose attach died without detaching): one line, on
|
|
3469
|
+
// stderr, before the client takes the terminal, and only when something was removed.
|
|
3470
|
+
const onSwept = ({ sessions, tables }) => {
|
|
3471
|
+
const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
|
|
3472
|
+
if (sessions + tables > 0) console.error(`oats: removed ${n(sessions, "leftover viewer session")} and ${n(tables, "key table")} of earlier attaches`);
|
|
3473
|
+
};
|
|
3474
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), onSwept });
|
|
3467
3475
|
return;
|
|
3468
3476
|
}
|
|
3469
3477
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -3536,7 +3544,7 @@ async function tuiCmd() {
|
|
|
3536
3544
|
* instance homes), then runs exactly the `oats sync` path — discover over the
|
|
3537
3545
|
* remotes, confirm membership, resolve `packages:`, write `oats-lock.json`. Nothing is installed, no soul
|
|
3538
3546
|
* is created, nothing is spawned, no `oats-config.yaml` is written: the member
|
|
3539
|
-
* clones and the
|
|
3547
|
+
* clones and the workspace's setup expert are the operator's next steps, printed here. */
|
|
3540
3548
|
async function onboardCmd() {
|
|
3541
3549
|
const bail = (code, message, details) => (JSON_MODE ? jsonFail(code, message, details) : die(message));
|
|
3542
3550
|
const usage = "usage: oats onboard [<dir>] --workspace <repo ref> [--json] (or --dir <dir>)";
|
|
@@ -3615,12 +3623,15 @@ async function onboardCmd() {
|
|
|
3615
3623
|
// (4) The taught layout as next steps (design doc §4), and the envelope.
|
|
3616
3624
|
const standalone = synced.discovery.standalone === true;
|
|
3617
3625
|
const members = synced.report.members;
|
|
3618
|
-
// The
|
|
3619
|
-
//
|
|
3626
|
+
// The setup expert is suggested only when THIS workspace lists one (setupExpertOf); otherwise
|
|
3627
|
+
// any listed soul is spawnable.
|
|
3620
3628
|
const soulNames = synced.items.souls.map((s) => s.name);
|
|
3621
|
-
const
|
|
3622
|
-
const
|
|
3623
|
-
const
|
|
3629
|
+
const { OPERATOR_CAPABILITY } = await import("../lib/operator-coverage.mjs");
|
|
3630
|
+
const wsName = standalone ? null : synced.discovery.workspace?.name;
|
|
3631
|
+
const conventional = typeof wsName === "string" && wsName ? `${wsName}-oats-setup-expert` : null;
|
|
3632
|
+
const setupExpert = setupExpertOf(synced.discovery, { conventional, capability: OPERATOR_CAPABILITY });
|
|
3633
|
+
const spawnHint = setupExpert ? `oats spawn ${setupExpert} --dir ${shortPath(dir)}` : null;
|
|
3634
|
+
const anySoulHint = `oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
|
|
3624
3635
|
// A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
|
|
3625
3636
|
// homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
|
|
3626
3637
|
// listed exactly like any other member when it is one: a clone of it is needed only if someone
|
|
@@ -3660,10 +3671,38 @@ Next:
|
|
|
3660
3671
|
2. Check who may read the host: ${synced.discovery.key}${hostIsMember ? " is itself a member" : " is a dedicated host"}. The workspace file
|
|
3661
3672
|
names every member, so if any member is private the host must be a private repo that is not
|
|
3662
3673
|
a public member; public contributors then get the standalone case (from: here + oats.core).
|
|
3663
|
-
3. ${setupExpert ?
|
|
3674
|
+
3. ${setupExpert ? `Spawn ${setupExpert}, this workspace's OATS setup expert
|
|
3675
|
+
(it holds ${OPERATOR_CAPABILITY}), to guide the rest:` : `No soul here holds ${OPERATOR_CAPABILITY} — add a ${conventional ? `${conventional} soul` : "soul"} that declares it,
|
|
3676
|
+
or spawn any listed soul:`}
|
|
3664
3677
|
${spawnHint ?? anySoulHint}`);
|
|
3665
3678
|
}
|
|
3666
3679
|
|
|
3680
|
+
/** The soul `oats onboard` names as the workspace's OATS setup expert (awebai/oats#1314), among the
|
|
3681
|
+
* souls a spawn can name (soulCandidates) whose own soul.yaml declares `capability` (oats.setup) with
|
|
3682
|
+
* `{ from: … }`, from any source (`off` is no declaration): the one named `conventional`
|
|
3683
|
+
* (`<workspace name>-oats-setup-expert`, null in a standalone view, which has no workspace name);
|
|
3684
|
+
* else the first by name; else null. A soul is never chosen by its name alone. Only the soul's own declaration is read, never
|
|
3685
|
+
* a resolution: oats.setup that reaches a soul through the workspace defaults alone is not seen. → the
|
|
3686
|
+
* name to spawn it by: the bare name, else `<member>/<soul>` (`<package>/<soul>`), else
|
|
3687
|
+
* `<member repo key>/<soul>`, the first that names this soul alone. */
|
|
3688
|
+
function setupExpertOf(discovery, { conventional, capability }) {
|
|
3689
|
+
const candidates = soulCandidates(discovery);
|
|
3690
|
+
const declares = (entry) => {
|
|
3691
|
+
const caps = entry.definition?.capabilities;
|
|
3692
|
+
const choice = caps !== null && typeof caps === "object" && Object.hasOwn(caps, capability) ? caps[capability] : null;
|
|
3693
|
+
return choice !== null && typeof choice === "object" && typeof choice.from === "string" && choice.from !== "";
|
|
3694
|
+
};
|
|
3695
|
+
const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
3696
|
+
const entries = candidates.map((c) => c.entry).sort((a, b) => order(a.name, b.name) || order(qualifiedSoulName(a), qualifiedSoulName(b)));
|
|
3697
|
+
const chosen = (conventional && entries.find((e) => e.name === conventional && declares(e))) || entries.find(declares);
|
|
3698
|
+
if (!chosen) return null;
|
|
3699
|
+
// The shortest name a spawn resolves to exactly this soul: two members can share a repository
|
|
3700
|
+
// basename (github.com/a/agents, github.com/b/agents), so the last form is the full repo key.
|
|
3701
|
+
const forms = [chosen.name, qualifiedSoulName(chosen), ...(typeof chosen.package === "string" ? [] : [`${chosen.repoKey}/${chosen.name}`])];
|
|
3702
|
+
const only = (name) => { const hits = candidates.filter((c) => c.matches(name)); return hits.length === 1 && hits[0].entry === chosen; };
|
|
3703
|
+
return forms.find(only) ?? forms[forms.length - 1];
|
|
3704
|
+
}
|
|
3705
|
+
|
|
3667
3706
|
/** `oats onboard <dir> [--workspace <ref>] --check`: what onboarding <dir> here would meet, read-only (the
|
|
3668
3707
|
* question `oats server connect` asks a host before onboarding there, and `oats server check` asks of a
|
|
3669
3708
|
* registered deployment). A leading ~ is this machine's home. `state` is absent | empty | not-empty |
|
|
@@ -4039,12 +4078,12 @@ const EXPERIMENTAL_CMDS = new Set(["dress", "spawn", "segments", "mind"]);
|
|
|
4039
4078
|
async function recordCmd(sub) {
|
|
4040
4079
|
process.argv.splice(2, 1);
|
|
4041
4080
|
if (sub === "setup") {
|
|
4042
|
-
// setup writes a node into the user's Claude settings and into the capture
|
|
4081
|
+
// setup writes a node into the user's Claude settings and into the capture service's unit,
|
|
4043
4082
|
// and nothing rewrites them but setup run again: it is handed the rule's answer for the node
|
|
4044
4083
|
// running this kernel (docs/capabilities.md, "The node a hook writes down"). The script is
|
|
4045
4084
|
// imported into this process, so the variable is set here, over whatever the caller's
|
|
4046
4085
|
// environment held; packages/record imports nothing of the kernel.
|
|
4047
|
-
const { node, warning } = stableNode({ consequence: "the capture hooks and the capture
|
|
4086
|
+
const { node, warning } = stableNode({ consequence: "the capture hooks and the capture service stop when it goes away", remedy: "run `oats setup` again" });
|
|
4048
4087
|
if (warning) console.error(`oats: warning: ${warning}`);
|
|
4049
4088
|
process.env.OATS_NODE_BIN = node;
|
|
4050
4089
|
}
|
|
@@ -4734,8 +4773,9 @@ Usage:
|
|
|
4734
4773
|
oats onboard [<dir>] --workspace <repo ref> realize a workspace here: writes <dir>/oats-local.yaml
|
|
4735
4774
|
[--json] and agents/, then runs the oats sync path (lock v3)
|
|
4736
4775
|
and prints the
|
|
4737
|
-
next steps (clone members you work IN, spawn
|
|
4738
|
-
|
|
4776
|
+
next steps (clone members you work IN, spawn the
|
|
4777
|
+
workspace's setup expert (the soul holding oats.setup));
|
|
4778
|
+
creates no soul, spawns nothing
|
|
4739
4779
|
[--check] --check: write nothing; report <dir> (~ = this home),
|
|
4740
4780
|
its state and whether Git reads the workspace remote
|
|
4741
4781
|
oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
|
|
@@ -4853,8 +4893,8 @@ Usage:
|
|
|
4853
4893
|
[--launch-config <name>|none] command and preflight; read-only, nothing
|
|
4854
4894
|
[--harness r] [--model m] started; a named configuration is a unit, so
|
|
4855
4895
|
[--yolo | --no-yolo] --json a disagreeing --harness is refused
|
|
4856
|
-
oats doctor [dir] [--soul <name>] [--json] resolved targets
|
|
4857
|
-
--soul shows final composed AGENTS.md
|
|
4896
|
+
oats doctor [dir] [--soul <name>] [--json] resolved targets and offline capture warnings;
|
|
4897
|
+
--soul shows final composed AGENTS.md only
|
|
4858
4898
|
oats update [--check] [--yes] check npm for a newer kernel and move the pi bridge
|
|
4859
4899
|
[--dir <deployment>] in every pi folder the deployment's launches use
|
|
4860
4900
|
(docs/upgrading.md); then run oats doctor
|
|
@@ -4962,15 +5002,22 @@ Usage:
|
|
|
4962
5002
|
|
|
4963
5003
|
The turn record (core — every conversation captured, searchable, replicated):
|
|
4964
5004
|
oats capture [--watch|--status] land Claude Code/pi/codex sessions and aw
|
|
4965
|
-
[--owner <name>] [--root <dir>] client logs in the record
|
|
4966
|
-
|
|
5005
|
+
[--owner <name>] [--root <dir>] client logs in the record: one bounded
|
|
5006
|
+
supervised reconciliation pass; partial
|
|
5007
|
+
passes exit 0 with work pending
|
|
5008
|
+
oats capture --hook launch a detached pass; exit 0 means
|
|
5009
|
+
capture launched, not completed
|
|
5010
|
+
oats capture --health [--json] offline installation, run and issue
|
|
5011
|
+
diagnosis; captures nothing
|
|
4967
5012
|
oats capture --file <path> --format cc|pi|codex --home <instance home> [--json]
|
|
4968
5013
|
one session file (an archived session),
|
|
4969
5014
|
captured as --home capture would
|
|
4970
5015
|
oats recall [--kind k] [--thread t] search the whole record — mail, chat,
|
|
4971
5016
|
[--from f] [--show id] <query> sessions — with exact turn provenance
|
|
4972
|
-
oats setup [--owner <name>] [--
|
|
4973
|
-
[--no-service] [--no-hooks]
|
|
5017
|
+
oats setup [--owner <name>] [--root <dir>] [--replace-service]
|
|
5018
|
+
[--no-service] [--no-hooks] [--dry-run]
|
|
5019
|
+
install hooks + periodic capture
|
|
5020
|
+
(launchd/systemd), then run the first pass
|
|
4974
5021
|
|
|
4975
5022
|
oats experimental <dress|spawn|segments|mind> EXPERIMENTAL tools over the record —
|
|
4976
5023
|
selection and agent synthesis; unproven by
|
package/docs/capabilities.md
CHANGED
|
@@ -842,7 +842,7 @@ A package that also runs under a kernel older than the variable falls back to
|
|
|
842
842
|
`oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
|
|
843
843
|
own process, over any value the caller's environment held, before it runs the
|
|
844
844
|
turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
|
|
845
|
-
into the capture hooks and the capture
|
|
845
|
+
into the capture hooks and the capture service's unit. In the third case
|
|
846
846
|
`oats setup` carries the warning, a dry run included.
|
|
847
847
|
|
|
848
848
|
### The worktree event
|
package/docs/configuration.md
CHANGED
|
@@ -305,6 +305,15 @@ configuration is a host choice: a soul never names one.
|
|
|
305
305
|
environment, command and preflight checks) and starts nothing.
|
|
306
306
|
- The old key `runtime` is still read as `harness`, with a
|
|
307
307
|
`deprecated-runtime-name` warning.
|
|
308
|
+
- **Claude's permissions** are Claude's own settings, not OATS keys. They go
|
|
309
|
+
in the user settings of the Claude config a launch uses (its
|
|
310
|
+
`CLAUDE_CONFIG_DIR`, else `~/.claude`), or `--permission-mode` goes in a
|
|
311
|
+
configuration's `args`. Never in a home's `.claude/settings.json`: the
|
|
312
|
+
capabilities manage it at every start, and Claude ignores auto mode there.
|
|
313
|
+
oats.setup's `/oats-agent-permissions` (oats.framework 1.13.0) teaches the
|
|
314
|
+
setup: auto mode, narrow allow rules for the `oats` and `gh` reads,
|
|
315
|
+
`oats spawn` and reading `aw` mail and chat, and what stays gated.
|
|
316
|
+
`yolo` is separate and is meant for isolated machines.
|
|
308
317
|
|
|
309
318
|
### The harness default
|
|
310
319
|
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -882,8 +882,8 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
882
882
|
"hosting":{"host":"github.com/acme/agents","hostIsMember":true,"rule":"If any member is private, host oats-workspace.yaml in a private repo …"},
|
|
883
883
|
"next":{"clone":[{"key":"github.com/acme/agents","name":"agents","url":"https://github.com/acme/agents.git","dir":"/w/agents-repo","present":false,"host":true},
|
|
884
884
|
{"key":"github.com/acme/platform","name":"platform","url":"https://github.com/acme/platform.git","dir":"/w/platform","present":true,"host":false}],
|
|
885
|
-
"spawn":"oats spawn oats-
|
|
886
|
-
"souls":["oats-
|
|
885
|
+
"spawn":"oats spawn acme-oats-setup-expert --dir /w",
|
|
886
|
+
"souls":["acme-oats-setup-expert","platform-engineer","release-manager"]}}
|
|
887
887
|
```
|
|
888
888
|
|
|
889
889
|
- `sync` is the full [`oats sync`](#oats-sync) report (abridged above).
|
|
@@ -895,9 +895,32 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
895
895
|
existing clone (the `clones:` entry, else `<dir>/<name>`), else where to
|
|
896
896
|
clone it: `<dir>/<name>`, or `<dir>/agents-repo` for a member named
|
|
897
897
|
`agents`. `url` is `null` when unknown.
|
|
898
|
-
- `next.spawn` is `oats spawn
|
|
899
|
-
|
|
900
|
-
|
|
898
|
+
- `next.spawn` is `oats spawn <soul> --dir <dir>` naming the workspace's
|
|
899
|
+
OATS setup expert, else `null` (OATS 0.61.0; before it, only a soul named
|
|
900
|
+
`oats-operator-expert` was named). Among the souls onboarding lists
|
|
901
|
+
(confirmed members', external and package souls; standalone, the
|
|
902
|
+
repository's own), the setup expert is:
|
|
903
|
+
1. the soul named `<workspace name>-oats-setup-expert` that declares
|
|
904
|
+
`oats.setup`, where the workspace name is the `name:` of
|
|
905
|
+
`oats-workspace.yaml` (`sync.workspace.name`); a standalone view has no
|
|
906
|
+
workspace name, so this step does not apply there;
|
|
907
|
+
2. otherwise the first soul by name that declares `oats.setup`;
|
|
908
|
+
3. otherwise none: `null`.
|
|
909
|
+
|
|
910
|
+
A soul declares `oats.setup` when its own `soul.yaml` names it under
|
|
911
|
+
`capabilities:` as `{ from: … }`, from any source (`package`, `here` or a
|
|
912
|
+
member key); `oats.setup: off` does not count. A soul is never chosen by
|
|
913
|
+
its name alone: one named `<workspace name>-oats-setup-expert` that does
|
|
914
|
+
not declare `oats.setup` falls through to step 2.
|
|
915
|
+
|
|
916
|
+
Only the soul's own declaration is read, not its resolved composition:
|
|
917
|
+
`oats.setup` that reaches a soul only through the workspace's `defaults:`
|
|
918
|
+
is not seen, and a declared `oats.setup` is not checked to resolve. A soul
|
|
919
|
+
whose name another listed soul shares is named so that `oats spawn` finds
|
|
920
|
+
it alone: `<member>/<soul>` or `<package>/<soul>`, else, when two members
|
|
921
|
+
share a repository name, `<member repo key>/<soul>`. The text output's step 3 names
|
|
922
|
+
the same soul, or, with none, the conventional name to add.
|
|
923
|
+
`next.souls` is the first three soul names, sorted.
|
|
901
924
|
- Errors: `E_BAD_ARGS` (usage, no `--workspace`, a repeated directory, an
|
|
902
925
|
unknown flag), `E_REPO_REF`, `E_ALREADY_ONBOARDED {local, dir}` (this
|
|
903
926
|
directory already has `oats-local.yaml`), `E_ONBOARD_FAILED {dir}`. A
|
package/docs/desktop.md
CHANGED
|
@@ -529,6 +529,13 @@ has reached the execution host. Both CLI installations must advertise
|
|
|
529
529
|
`session-upload`. A failed transfer leaves the draft unchanged and shows an
|
|
530
530
|
error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
|
|
531
531
|
|
|
532
|
+
## The sidebar's instance tree
|
|
533
|
+
|
|
534
|
+
The sidebar lists a workspace's instances as a tree: a child sits one step
|
|
535
|
+
right of its parent, and related instances are grouped together. Siblings are
|
|
536
|
+
joined by a dotted line through their dots. A parent's line to its children
|
|
537
|
+
runs just to the right of the dotted line, so the two never merge.
|
|
538
|
+
|
|
532
539
|
## Identity marks and harness badges
|
|
533
540
|
|
|
534
541
|
Souls, capabilities and workspaces carry a coloured two-letter mark beside
|
|
@@ -1103,6 +1103,50 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1103
1103
|
another session, another agent's terminal. Your own sessions keep your
|
|
1104
1104
|
setting.
|
|
1105
1105
|
|
|
1106
|
+
**An attach that dies without detaching leaves nothing behind.** A
|
|
1107
|
+
cgroup-wide `systemctl kill`, a stop timeout, oomd or a killed ssh can end
|
|
1108
|
+
`oats` and its tmux client together. `oats` itself then removes nothing, so
|
|
1109
|
+
the tmux server does. Once its client has attached, the viewer's client
|
|
1110
|
+
sets a `client-detached` hook on the viewer session alone: when a client
|
|
1111
|
+
leaves and none is left, the hook kills the viewer session. It is set after
|
|
1112
|
+
the attach, so a viewer whose client never attached is removed by `oats`
|
|
1113
|
+
or by the next attach's sweep. From then on, the server removes the viewer
|
|
1114
|
+
when its last client's connection drops without a word from the client:
|
|
1115
|
+
`oats` and its client SIGKILLed together (oomd, a stop timeout). A client
|
|
1116
|
+
that ends any other way (a hang-up, a termination, a `detach-client` from
|
|
1117
|
+
another client) is not seen by that hook: `oats` removes the viewer as it
|
|
1118
|
+
ends, or, if `oats` has died, the next attach's sweep does. The viewer never uses
|
|
1119
|
+
`destroy-unattached`: on tmux 3.4 it crashes the agents' server when another
|
|
1120
|
+
client detaches the viewer. A keyed viewer's key table (below)
|
|
1121
|
+
belongs to the server, not to the session, and its `client-detached` hook
|
|
1122
|
+
unbinds the table as it kills the session. For a viewer session that ends
|
|
1123
|
+
another way (its agent's window ends, a `kill-session`), a keyed viewer sets
|
|
1124
|
+
one global hook entry on the agents' server, `session-closed[900]`: when a
|
|
1125
|
+
session whose name is a viewer's closes, the entry unbinds the key table of
|
|
1126
|
+
that name. It is the only global hook entry OATS owns there.
|
|
1127
|
+
Every keyed viewer sets the same entry again, which leaves it unchanged,
|
|
1128
|
+
and no other index is touched. Keep your own `session-closed` hooks
|
|
1129
|
+
(`set-hook -g` in `~/.tmux.conf`) at other indexes: an entry of yours at
|
|
1130
|
+
900 is replaced. A global `client-detached` hook of yours does not run
|
|
1131
|
+
for a viewer's client whose connection dropped: the viewer session's own
|
|
1132
|
+
hook takes its place there. The entry needs `run-shell -C`, which tmux has from 3.2.
|
|
1133
|
+
Before 3.2 it does nothing, and the next attach's sweep removes the table.
|
|
1134
|
+
|
|
1135
|
+
Every attach also sweeps the server before it opens its viewer. It removes:
|
|
1136
|
+
|
|
1137
|
+
- a viewer session (`oatsview-<pid>-<8 hex>`) with no client attached,
|
|
1138
|
+
whose attaching process, the pid in its name, no longer exists;
|
|
1139
|
+
- a viewer key table whose session no longer exists.
|
|
1140
|
+
|
|
1141
|
+
The sweep keeps a viewer whose attach is alive, even with no client: its
|
|
1142
|
+
client may not have attached yet. It also never removes an attached
|
|
1143
|
+
viewer, anything not named as a viewer, or the `oatsview-locked` table
|
|
1144
|
+
that every viewer without a key shares. When it removed something, the
|
|
1145
|
+
attach prints one line on stderr before the viewer opens:
|
|
1146
|
+
`oats: removed <n> leftover viewer session(s) and <m> key table(s) of
|
|
1147
|
+
earlier attaches`. A failed sweep is not the attach's failure; the next
|
|
1148
|
+
attach sweeps again.
|
|
1149
|
+
|
|
1106
1150
|
On tmux 3.2 and later the viewer's tmux client asks for synchronized
|
|
1107
1151
|
output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
|
|
1108
1152
|
DEC mode 2026, so a terminal that receives a redraw in two pieces does not
|
|
@@ -1119,9 +1163,11 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1119
1163
|
The key is taken from the agent's input: the agent never receives it while
|
|
1120
1164
|
this viewer is attached. A keyed viewer reads a tmux key table of its own,
|
|
1121
1165
|
named as its temporary session and removed with it, so the key is bound
|
|
1122
|
-
for that viewer alone.
|
|
1123
|
-
|
|
1124
|
-
|
|
1166
|
+
for that viewer alone. The key's binding also removes the viewer session's
|
|
1167
|
+
`client-detached` hook before it detaches: the session outlives its client
|
|
1168
|
+
until `oats` has read that the key was used, and `oats` then removes it.
|
|
1169
|
+
Check the feature in `oats version --json` before passing the flag: a
|
|
1170
|
+
kernel without it ignores the flag and opens a viewer with no exit.
|
|
1125
1171
|
|
|
1126
1172
|
The key is one of these, spelled exactly (case-sensitive):
|
|
1127
1173
|
|
package/docs/first-team.md
CHANGED
|
@@ -69,6 +69,14 @@ runs before adding its pin. Then clone the
|
|
|
69
69
|
member you will work in beside `oats-local.yaml` (only a soul's work target
|
|
70
70
|
needs a clone — discovery and resolution run over the remotes).
|
|
71
71
|
|
|
72
|
+
The last next step names the workspace's OATS setup expert to spawn, among the
|
|
73
|
+
souls that declare `oats.setup` in their own `soul.yaml`: the one named
|
|
74
|
+
`<workspace name>-oats-setup-expert` (`acme-oats-setup-expert` for a
|
|
75
|
+
workspace named `acme`), else the first by name. With neither, it says so and suggests
|
|
76
|
+
adding that conventional soul, or spawning any listed soul. The full rule and
|
|
77
|
+
its limits are in
|
|
78
|
+
[desktop-cli-api.md](desktop-cli-api.md#oats-onboard-onboardapi-2).
|
|
79
|
+
|
|
72
80
|
`--json` returns `onboardApi: 2` (`local`, `dir`, `agents`, `lock`, the full
|
|
73
81
|
`sync` report, `hosting`, `next.clone[]`, `next.spawn`); running it twice is
|
|
74
82
|
`E_ALREADY_ONBOARDED` (use `oats sync`); a mistyped ref is `E_REPO_REF`, an
|
package/docs/implementation.md
CHANGED
|
@@ -79,7 +79,7 @@ and the rules its tests pin.
|
|
|
79
79
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
80
80
|
| `docs/` | the reference pages, schemas, design records and release notes |
|
|
81
81
|
| `packages/` | the pi adapter, the Desktop, the terminal client (`tui/`), the readers both clients share (`client/`), the turn-record package and experiments |
|
|
82
|
-
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane
|
|
82
|
+
| `scripts/` | the test runner (`run-tests.mjs`), its reporter of unasserted warnings and the preload that gives each test file a temporary directory of its own, the session-inheritance check (`test-session-inheritance.mjs`), validators, packaging checks, the release lane, the assembly of release-notes entries, and the hand-started named test runs on macOS and Linux (`named-test-run.mjs`, with `macos-tests.mjs` and `linux-tests.mjs`: [named test runs](named-test-runs.md)) |
|
|
83
83
|
| `test/` | the kernel and CLI suites, with their fixtures |
|
|
84
84
|
|
|
85
85
|
## Kernel modules
|
|
@@ -96,6 +96,7 @@ and the rules its tests pin.
|
|
|
96
96
|
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
97
97
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
98
98
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
99
|
+
| `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
|
|
99
100
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
100
101
|
| `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
|
|
101
102
|
| `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |
|