@awebai/oats 0.50.0 → 0.51.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +48 -18
- package/docs/capabilities.md +3 -2
- package/docs/desktop-cli-api.md +92 -4
- package/docs/execution-targets.md +87 -2
- package/docs/implementation.md +8 -0
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +20 -7
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +23 -1
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +126 -0
- package/lib/core.mjs +156 -22
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/worktree-hooks.mjs +24 -9
- package/lib/worktree.mjs +14 -86
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/bin/oats.mjs
CHANGED
|
@@ -30,7 +30,7 @@ import {
|
|
|
30
30
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
31
31
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
32
32
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
33
|
-
findInstanceHome, findInstanceHomes, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
33
|
+
findInstanceHome, findInstanceHomes, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
34
34
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
35
35
|
} from "../lib/core.mjs";
|
|
36
36
|
import {
|
|
@@ -98,7 +98,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]
|
|
|
98
98
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
99
99
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
100
100
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
101
|
-
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources"];
|
|
101
|
+
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key"];
|
|
102
102
|
/** Commands `--server <id>` runs on a registered server. */
|
|
103
103
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
104
104
|
const flag = (name) => {
|
|
@@ -2874,27 +2874,42 @@ function retireCmd() {
|
|
|
2874
2874
|
// resolved the home). A guarded apply acts on the children of the plan it
|
|
2875
2875
|
// revalidated; a plain or --self retire computes them as the plan does, and
|
|
2876
2876
|
// passes none when there are none.
|
|
2877
|
-
let replayPath = null,
|
|
2877
|
+
let replayPath = null, fresh, revalidate, stalePlan, planFailure;
|
|
2878
2878
|
if (planRev !== undefined) {
|
|
2879
2879
|
if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
|
|
2880
2880
|
// Replay first: after a successful retire the home is gone, so the receipt
|
|
2881
2881
|
// (beside the instances dir, keyed by the idempotency key) is the answer.
|
|
2882
2882
|
const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
|
|
2883
2883
|
for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
|
|
2884
|
-
|
|
2885
|
-
|
|
2886
|
-
|
|
2887
|
-
|
|
2888
|
-
|
|
2889
|
-
|
|
2890
|
-
|
|
2884
|
+
// Before the claim, only the home: where the receipt goes, and the answers of a name that
|
|
2885
|
+
// resolves to no home, to several or to another one.
|
|
2886
|
+
let target;
|
|
2887
|
+
try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
|
|
2888
|
+
replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
|
|
2889
|
+
// The plan the revision is checked against is read once, by retireInstance, when it holds the
|
|
2890
|
+
// home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
|
|
2891
|
+
// the state the retire starts from. Against another retire of this home the answer is that one
|
|
2892
|
+
// is running (E_LIFECYCLE_BUSY), and no plan is read. A revision that no longer matches is
|
|
2893
|
+
// refused there, and nothing was done. What the retire takes from the plan: its children, and
|
|
2894
|
+
// its extra trees as it names them (the retire refuses as stale rather than move or remove one
|
|
2895
|
+
// that no longer reads that way when it gets to them).
|
|
2896
|
+
revalidate = () => {
|
|
2897
|
+
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
|
|
2898
|
+
if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
|
|
2899
|
+
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
|
|
2900
|
+
};
|
|
2891
2901
|
} else {
|
|
2892
|
-
|
|
2893
|
-
|
|
2902
|
+
// A plain or --self retire reads its recorded children the same way: under the claim, as they
|
|
2903
|
+
// are when the retire starts (an earlier retire that kept the home has repaired lineage by
|
|
2904
|
+
// then), and none when there are none.
|
|
2905
|
+
revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
|
|
2894
2906
|
}
|
|
2895
2907
|
let r;
|
|
2896
|
-
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"),
|
|
2908
|
+
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
|
|
2897
2909
|
catch (e) {
|
|
2910
|
+
// The plan could not be read, or its revision is not the one shown: the answers they always had.
|
|
2911
|
+
if (e === planFailure) return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message);
|
|
2912
|
+
if (e === stalePlan) return args.includes("--json") ? jsonFail(e.code, e.message, e.details) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
|
|
2898
2913
|
if (!e?.code) throw e;
|
|
2899
2914
|
// A child still running (or whose stop could not be established) refused the retirement: the
|
|
2900
2915
|
// guarded apply returns the plan it acted on, and the text names each child's reason.
|
|
@@ -3224,7 +3239,9 @@ async function sessionCmd() {
|
|
|
3224
3239
|
let result;
|
|
3225
3240
|
if (args[1] === "attach") {
|
|
3226
3241
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3227
|
-
|
|
3242
|
+
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3243
|
+
// status 20. Without it every key reaches the agent and there is no keyboard exit.
|
|
3244
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
|
|
3228
3245
|
return;
|
|
3229
3246
|
}
|
|
3230
3247
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -3264,7 +3281,7 @@ async function sessionCmd() {
|
|
|
3264
3281
|
const file = flag("file");
|
|
3265
3282
|
if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
|
|
3266
3283
|
result = uploadAttachment({ file, home: home === true ? undefined : home });
|
|
3267
|
-
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3284
|
+
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3268
3285
|
if (JSON_MODE) jsonOk(result);
|
|
3269
3286
|
else {
|
|
3270
3287
|
console.log(JSON.stringify(result, null, 2));
|
|
@@ -4091,8 +4108,14 @@ async function serverRouteCmd() {
|
|
|
4091
4108
|
return;
|
|
4092
4109
|
}
|
|
4093
4110
|
if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session restart`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
|
|
4111
|
+
// --detach-key travels only to a host that advertises session-attach-detach-key (attachArgv
|
|
4112
|
+
// probes for it, under --print too). The key may be C-\, the tty's QUIT character: pressed
|
|
4113
|
+
// once ssh has given the tty back, it reaches this process as SIGQUIT, whose default action
|
|
4114
|
+
// would replace the relayed status with 131. Held from here until this process exits.
|
|
4115
|
+
const detachKey = valueFlag("detach-key");
|
|
4116
|
+
if (detachKey !== undefined) process.on("SIGQUIT", () => {});
|
|
4094
4117
|
let route;
|
|
4095
|
-
try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
|
|
4118
|
+
try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
|
|
4096
4119
|
// ssh failing before the viewer (the version probe, a name resolved through the host's roster)
|
|
4097
4120
|
// is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
|
|
4098
4121
|
// and an ssh that never started (no link can come back), exits 1.
|
|
@@ -4102,7 +4125,7 @@ async function serverRouteCmd() {
|
|
|
4102
4125
|
// ssh exits 255 for its own failures: a link that died under the viewer
|
|
4103
4126
|
// (keepalives unanswered, the master or the host's sshd gone), or one
|
|
4104
4127
|
// never made. Say what is known rather than ending silently.
|
|
4105
|
-
if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}`);
|
|
4128
|
+
if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}${detachKey !== undefined ? ` --detach-key ${shellQuote(detachKey)}` : ""}`);
|
|
4106
4129
|
process.exit(r.status ?? 1);
|
|
4107
4130
|
}
|
|
4108
4131
|
// A spawn's argv is checked here, before the server is contacted.
|
|
@@ -4386,7 +4409,9 @@ Usage:
|
|
|
4386
4409
|
--instance <name> [--json] saved home on its host
|
|
4387
4410
|
oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
|
|
4388
4411
|
--instance <name> | --home <abs> remote instance, by its saved route or the server's
|
|
4389
|
-
|
|
4412
|
+
[--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
|
|
4413
|
+
attach --detach-key: as below; the server must
|
|
4414
|
+
advertise session-attach-detach-key
|
|
4390
4415
|
oats session start --server <id> start a stopped remote instance in its existing home
|
|
4391
4416
|
--instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
|
|
4392
4417
|
[--model <m>] [--json] session-start (oats 0.22.9 or later)
|
|
@@ -4409,6 +4434,11 @@ Usage:
|
|
|
4409
4434
|
[--check] --check: write nothing; report <dir> (~ = this home),
|
|
4410
4435
|
its state and whether Git reads the workspace remote
|
|
4411
4436
|
oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
|
|
4437
|
+
oats session attach --home <absolute-home> [--detach-key <key>]
|
|
4438
|
+
a viewer of one instance. <key> (C-<letter>, M-<letter
|
|
4439
|
+
or digit>, F1 to F12; 'C-\\' is the suggested one)
|
|
4440
|
+
leaves it with exit status 20; without one no key
|
|
4441
|
+
leaves it: every key goes to the agent
|
|
4412
4442
|
oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
|
|
4413
4443
|
enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
|
|
4414
4444
|
tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
|
package/docs/capabilities.md
CHANGED
|
@@ -205,8 +205,9 @@ A self-contained package has an `oats.json`:
|
|
|
205
205
|
Whether the process exists is the operating system's answer (`kill -0`:
|
|
206
206
|
"no such process" is gone, another user's process exists), the same on
|
|
207
207
|
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
|
-
|
|
209
|
-
|
|
208
|
+
where there is no `/proc`, as on macOS: the system `ps`, from
|
|
209
|
+
`/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
|
|
210
|
+
`TZ=UTC` environment. A start that cannot be read is never taken to mean the process is
|
|
210
211
|
gone, nor shown as alive: `oats status` shows the quarantine
|
|
211
212
|
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
212
213
|
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -43,7 +43,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
43
43
|
"preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
|
|
44
44
|
"workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
|
|
45
45
|
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
|
-
"server-probe-features","worktree-event"],
|
|
46
|
+
"server-probe-features","worktree-event","session-attach-detach-key"],
|
|
47
47
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
48
48
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
49
49
|
"capabilityShowApi":1}
|
|
@@ -119,6 +119,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
119
119
|
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
120
120
|
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
121
121
|
| `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
|
|
122
|
+
| `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
|
|
122
123
|
|
|
123
124
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
124
125
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -3234,7 +3235,8 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
3234
3235
|
`capabilityMeta`, `warnings`, `wakeSchedulesRemoved`.
|
|
3235
3236
|
- A deferred self-retire (`--self`) prints `{retired, agent, deferred: true,
|
|
3236
3237
|
pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
|
|
3237
|
-
`{…, alreadyScheduled: true, requestedAt}
|
|
3238
|
+
`{…, alreadyScheduled: true, requestedAt}` while one is scheduled and its
|
|
3239
|
+
completion has not started (below).
|
|
3238
3240
|
|
|
3239
3241
|
**Recorded children**, on every apply (plain, guarded and `--self`), as the
|
|
3240
3242
|
plan says: each child the plan lists is stopped first (bounded SIGTERM,
|
|
@@ -3259,12 +3261,96 @@ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
|
|
|
3259
3261
|
`--idempotency-key` together.
|
|
3260
3262
|
- A used key replays its receipt as an **envelope** with `replayed: true`
|
|
3261
3263
|
(receipts live beside the instances directory and outlive the home).
|
|
3262
|
-
- The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
|
|
3264
|
+
- The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`. That
|
|
3265
|
+
plan is read once, when the retire holds the home's claim (below): it is
|
|
3266
|
+
the state the retire starts from, and one apply appends one
|
|
3267
|
+
`retire-planned` event. Against a retire in flight or a scheduled
|
|
3268
|
+
self-retire the answer is `E_LIFECYCLE_BUSY` and no plan is read, whatever
|
|
3269
|
+
the plan would read by then: a retire in flight has usually changed it (it
|
|
3270
|
+
stops the session of a launched instance before its hooks run). Before the
|
|
3271
|
+
claim an apply only replays a used key and resolves the home
|
|
3272
|
+
(`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`).
|
|
3263
3273
|
- The children stopped are those of the revalidated plan, and a refusal
|
|
3264
3274
|
carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
|
|
3265
3275
|
- A first guarded retire prints the raw receipt with `planRevision`,
|
|
3266
3276
|
`idempotencyKey` and `replayed: false`.
|
|
3267
3277
|
|
|
3278
|
+
**One retire of a home at a time** (0.51.0, #863). Every retire that applies (plain,
|
|
3279
|
+
guarded, `--self` and its detached completion; with `--server`, on the host)
|
|
3280
|
+
holds the home's claim,
|
|
3281
|
+
`<instances>/.oats-retirement/claims/<instance>.lock`, from the moment it
|
|
3282
|
+
has resolved the home until it ends, by success or by any refusal or failure.
|
|
3283
|
+
The claim is a file that names its holder by pid and start time. It lies
|
|
3284
|
+
beside the homes, never inside one: a home's bytes are what its retire
|
|
3285
|
+
observes, copies and removes. A second retire of that home does not wait: it
|
|
3286
|
+
answers `E_LIFECYCLE_BUSY` at once (exit 1; the text form prints the
|
|
3287
|
+
message), before it stops a session or a child, writes a recovery, runs a
|
|
3288
|
+
hook or changes a file of the home. **`--force` does not bypass it**, and
|
|
3289
|
+
`--plan` takes no claim and refuses nothing new. A guarded apply answers it
|
|
3290
|
+
before `E_PLAN_STALE`: under the claim the answers come in this order: the
|
|
3291
|
+
home is gone (`E_SESSION_UNKNOWN`), a self-retire is scheduled
|
|
3292
|
+
(`E_LIFECYCLE_BUSY`), the plan is stale (`E_PLAN_STALE`), then the retire. A claim whose holder has
|
|
3293
|
+
died, for example a retire killed while its hooks ran, is taken over by the
|
|
3294
|
+
next retire of that name. So a killed retire can always be run again. The
|
|
3295
|
+
claim does not end what the killed retire left running: one of its retire
|
|
3296
|
+
hooks may still be running when the next retire takes the claim over and
|
|
3297
|
+
runs the hooks again (#865). Until
|
|
3298
|
+
that name is retired again its claim file stays where it is, and it is safe
|
|
3299
|
+
to remove once its pid is gone. A retire that ends removes its claim file;
|
|
3300
|
+
the `claims/` directory itself stays, empty.
|
|
3301
|
+
|
|
3302
|
+
`details` is `{instance, home, lock, pid, since}`: `lock` is the file that
|
|
3303
|
+
names the holder, `since` when the holder took it. Every message is one
|
|
3304
|
+
line and says that nothing was done:
|
|
3305
|
+
|
|
3306
|
+
- A live holder: `a retire of <name> is already running (pid <pid>, since
|
|
3307
|
+
<at>); nothing was done — wait for it to finish`.
|
|
3308
|
+
- A holder whose start time cannot be read (where `ps` fails, or a claim
|
|
3309
|
+
that records none) is never taken for gone, and its claim is never taken
|
|
3310
|
+
over. `details.unknown` is the reason. The message names the pid, its
|
|
3311
|
+
recorded start, the reason and the way out: check that pid by hand, and if
|
|
3312
|
+
it is not an `oats retire`, remove `<lock>`, then retry.
|
|
3313
|
+
- A claim file that is not a readable claim is never removed. `details` is
|
|
3314
|
+
`{instance, home, lock}`; the message names the file and says to inspect
|
|
3315
|
+
it and remove it if no `oats retire` holds it.
|
|
3316
|
+
- The retire's own start time cannot be read, so it could not hold the claim
|
|
3317
|
+
verifiably: `details` is `{instance, home, lock}`, and the message gives
|
|
3318
|
+
the reader's own reason (the `/proc` read, or what `ps` answered).
|
|
3319
|
+
|
|
3320
|
+
A scheduled self-retire counts from the moment it is scheduled. Its pending
|
|
3321
|
+
marker (`pendingMarker`) records the completion process as `completionPid`
|
|
3322
|
+
and `completionStart` (`null` when the start could not be read). While that
|
|
3323
|
+
process lives, every other retire of the instance is refused the same way,
|
|
3324
|
+
`--self --keep-dir` included: `a retire of <name> is already scheduled (its
|
|
3325
|
+
completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
|
|
3326
|
+
for it to finish`, with `details.lock` the pending marker, `details.pid` the
|
|
3327
|
+
completion and `details.since` the marker's `requestedAt`. A completion
|
|
3328
|
+
whose start cannot be read is refused as a holder's is (`details.unknown`),
|
|
3329
|
+
the file to remove being the pending marker. A second `--self` answers
|
|
3330
|
+
`alreadyScheduled: true` only while the completion has not started. While
|
|
3331
|
+
the first `--self` is still scheduling, or once the completion holds the
|
|
3332
|
+
claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
|
|
3333
|
+
retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
|
|
3334
|
+
left its outcome at `resultPath` (it failed) or is gone (it died), nor when
|
|
3335
|
+
it names no completion (a marker written before 0.51.0): `oats retire
|
|
3336
|
+
<instance>` then retries the retirement, as before. The completion waits up
|
|
3337
|
+
to 3 s for the retire that scheduled it to release the claim, then takes it
|
|
3338
|
+
as any retire does; one that meets another retire still running is refused,
|
|
3339
|
+
and records that at `resultPath` like any failed completion.
|
|
3340
|
+
|
|
3341
|
+
The home is resolved again once the claim is held. One that another retire
|
|
3342
|
+
removed in between answers `E_SESSION_UNKNOWN`, as a retire of a retired
|
|
3343
|
+
instance does. If the name is by then the home of another agent, the retire
|
|
3344
|
+
starts over on that home, under that home's claim; after two such changes it
|
|
3345
|
+
answers `E_LIFECYCLE_BUSY` (`the home of <name> changed while its claim was
|
|
3346
|
+
being taken …; nothing was done — retry`, `details: {instance, home, lock}`).
|
|
3347
|
+
A retire of a name that has no home also removes a claim of that name whose
|
|
3348
|
+
holder is gone, left by a retire that was killed after it removed the home.
|
|
3349
|
+
|
|
3350
|
+
The claim orders retires only. `oats instance stop`, `oats session start`
|
|
3351
|
+
and `oats worktree add` do not take it and are not refused by it, and `oats
|
|
3352
|
+
status` does not show a held claim (#866).
|
|
3353
|
+
|
|
3268
3354
|
Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
|
|
3269
3355
|
`E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
|
|
3270
3356
|
`--discard-worktree` when it is `work/` that could not be re-homed: it does
|
|
@@ -3273,7 +3359,9 @@ message names the entry or the state that could not be read, or the directory
|
|
|
3273
3359
|
Git reads as the top level of a `work/` whose `core.worktree` names another
|
|
3274
3360
|
one),
|
|
3275
3361
|
`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
|
|
3276
|
-
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (
|
|
3362
|
+
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
|
|
3363
|
+
home is running or scheduled, `--force` included: one retire of a home at a
|
|
3364
|
+
time, above; or, feature
|
|
3277
3365
|
`worktree-event`: the home is a spawn still running its `worktree` hooks, a
|
|
3278
3366
|
row with `spawnInProgress: true`, `--force` included; or one whose start time
|
|
3279
3367
|
cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
|
|
@@ -346,8 +346,9 @@ positive whole number of milliseconds replaces the fixed 30-minute timeout of
|
|
|
346
346
|
tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
|
|
347
347
|
10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
|
|
348
348
|
the kernel read a process's start time with `ps`, as on a host without
|
|
349
|
-
`/proc` (macOS), on a host that has it
|
|
350
|
-
|
|
349
|
+
`/proc` (macOS), on a host that has it; an absolute path instead runs that
|
|
350
|
+
file as `ps`, directly and in the same fixed environment; any other value
|
|
351
|
+
reads no start at all. A launch configuration cannot set any of them. Do not set them in a deployment.
|
|
351
352
|
|
|
352
353
|
**An instance creates an agents' session or window without its own
|
|
353
354
|
environment.** Nothing of an instance's environment reaches a server or a
|
|
@@ -777,6 +778,7 @@ stopped ([missing socket file](#missing-socket)).
|
|
|
777
778
|
oats session inspect --home /abs/home --json
|
|
778
779
|
oats session input --home /abs/home --text-file message.txt --json
|
|
779
780
|
oats session attach --home /abs/home
|
|
781
|
+
oats session attach --home /abs/home --detach-key 'C-\'
|
|
780
782
|
```
|
|
781
783
|
|
|
782
784
|
- **inspect** reports `backend`, `present` and `state`: `unknown` for a live
|
|
@@ -826,6 +828,89 @@ oats session attach --home /abs/home
|
|
|
826
828
|
session linked to the agent's window alone.
|
|
827
829
|
Closing the viewer leaves the agent running.
|
|
828
830
|
|
|
831
|
+
**Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
|
|
832
|
+
every key goes to the agent, the tmux prefix included. Close the terminal.
|
|
833
|
+
With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
|
|
834
|
+
`session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
|
|
835
|
+
viewer's client. The agent's window and every other viewer are untouched.
|
|
836
|
+
The key is taken from the agent's input: the agent never receives it while
|
|
837
|
+
this viewer is attached. A keyed viewer reads a tmux key table of its own,
|
|
838
|
+
named as its temporary session and removed with it, so the key is bound
|
|
839
|
+
for that viewer alone. Check the feature in `oats version --json` before
|
|
840
|
+
passing the flag: a kernel without it ignores the flag and opens a viewer
|
|
841
|
+
with no exit.
|
|
842
|
+
|
|
843
|
+
The key is one of these, spelled exactly (case-sensitive):
|
|
844
|
+
|
|
845
|
+
```
|
|
846
|
+
key = control / meta / function
|
|
847
|
+
control = "C-" ( "a"-"g" / "j"-"l" / "n"-"z" / "\" / "]" / "^" / "_" )
|
|
848
|
+
meta = "M-" ( "a"-"z" / "0"-"9" )
|
|
849
|
+
function = [ "C-" / "M-" / "S-" ] "F" ( "1" … "12" )
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
Anything else is `E_BAD_ARGS`, before any tmux or ssh call: a missing
|
|
853
|
+
value, a plain character, `C-i` and `C-m` (Tab and Enter on tmux before
|
|
854
|
+
3.5), `C-h` (the byte, 0x08, that many terminals send for Ctrl+Backspace
|
|
855
|
+
and some for Backspace, so the name is not one key everywhere), `C-[`
|
|
856
|
+
(Escape), `M-[`, `M-]`, `M-\`, `M-O` and the other ESC + C1 introducers (a
|
|
857
|
+
terminal reply can arrive as that key), `Any`, mouse key names, two keys,
|
|
858
|
+
upper case, and anything with a space, `;` or a control character. The
|
|
859
|
+
kernel does not judge whether a harness reads the key: that is the
|
|
860
|
+
caller's choice.
|
|
861
|
+
|
|
862
|
+
**While the pane is scrolled back.** The viewer's wheel and drag bindings
|
|
863
|
+
put the pane in tmux's copy mode, and there copy mode's key table is read
|
|
864
|
+
before the viewer's. A detach key that copy mode binds acts in copy mode
|
|
865
|
+
and does not detach; it detaches once the mode is left (`q`, or scrolling
|
|
866
|
+
back to the bottom). The grammar does not exclude those keys. The
|
|
867
|
+
copy-mode tables are the tmux server's, shared by every session and
|
|
868
|
+
changed by the operator's `~/.tmux.conf`, so no grammar can promise a key
|
|
869
|
+
is free there, and the kernel never binds a detach key in a table other
|
|
870
|
+
sessions read. With tmux's default tables (3.7c), 35 of the 111 keys are
|
|
871
|
+
taken in emacs or vi copy mode (for example `C-e`, `C-c`, `M-w`, `C-u`);
|
|
872
|
+
`C-\` and `F12` are bound in neither and detach from copy mode. Detaching
|
|
873
|
+
while scrolled back leaves the agent's pane in copy mode for the next
|
|
874
|
+
viewer, as closing a viewer mid-scroll does.
|
|
875
|
+
|
|
876
|
+
**The suggested key is `C-\`**, written `--detach-key 'C-\'` (quoted: an
|
|
877
|
+
unquoted trailing backslash continues the line). The kernel fixes no key.
|
|
878
|
+
What was checked:
|
|
879
|
+
|
|
880
|
+
- It has no default binding in Claude Code 2.1.288 (which refuses to let
|
|
881
|
+
a user bind it: "terminal quit signal"), Codex CLI 0.160.0 or pi 1.0.2.
|
|
882
|
+
It is unbound in bash 5.3 (`bind -p`) and in zsh's and fish's documented
|
|
883
|
+
defaults. It is the default detach key of dtach and abduco.
|
|
884
|
+
- A viewer with this key gives up: in a fallback shell, the tty's QUIT (no
|
|
885
|
+
SIGQUIT from the keyboard); in vim and nvim, the `C-\ C-n` prefix; in
|
|
886
|
+
nano, Replace (also on `M-r`).
|
|
887
|
+
- On a layout where `\` needs AltGr, use `F12`: it has no default binding
|
|
888
|
+
in the same three harnesses, bash, nvim or less. Some terminals and
|
|
889
|
+
laptops keep F12 for themselves.
|
|
890
|
+
- `C-]`, `C-_`, `C-g`, `C-t` and `C-b` are each bound by all three
|
|
891
|
+
harnesses.
|
|
892
|
+
|
|
893
|
+
**Exit status.**
|
|
894
|
+
|
|
895
|
+
| How the command ended | Status |
|
|
896
|
+
|---|---|
|
|
897
|
+
| Left by the detach key (the agent keeps running) | 20 |
|
|
898
|
+
| The viewer ended without the key: the agent's window ended, or `oats` itself was stopped by SIGHUP, SIGTERM or SIGINT and closed the viewer | 0 |
|
|
899
|
+
| A refusal (bad arguments, not launched, session gone), or tmux failing under the viewer (its server exited) | 1 |
|
|
900
|
+
|
|
901
|
+
20 is answered only when the key's own binding ran, and only by a kernel
|
|
902
|
+
with the feature. No status an existing caller sees changes meaning. 20 is
|
|
903
|
+
nonzero, so `set -e`, an `&&` chain and tmux's `remain-on-exit failed`
|
|
904
|
+
treat a leave by the key as a failure. The routed form (`--server`) relays
|
|
905
|
+
these statuses and adds ssh's own 255 ([servers.md](servers.md#run-there)).
|
|
906
|
+
|
|
907
|
+
With `--detach-key`, `oats` handles SIGQUIT. `C-\` is also the terminal's
|
|
908
|
+
QUIT character: pressed before the viewer has the terminal, or again once
|
|
909
|
+
the viewer has given it back, it would otherwise end `oats` with status 131
|
|
910
|
+
and leave the viewer's session and key table on the tmux server. A QUIT
|
|
911
|
+
that arrives before the key was used stops the attach, with status 1;
|
|
912
|
+
after a leave by the key it changes nothing, and the status is 20.
|
|
913
|
+
|
|
829
914
|
### Attachments
|
|
830
915
|
|
|
831
916
|
`oats session upload --file <local> --home <abs>` copies a file into
|
package/docs/implementation.md
CHANGED
|
@@ -65,6 +65,7 @@ published to npm. Its developer docs are in
|
|
|
65
65
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
66
66
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
|
|
67
67
|
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
|
|
68
|
+
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`) and by `oats retire` per home (`core.mjs`, `retireInstance`) |
|
|
68
69
|
| `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL |
|
|
69
70
|
| `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
|
|
70
71
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
@@ -387,6 +388,13 @@ and acts on every existing session through its recorded socket
|
|
|
387
388
|
`list-windows`, `new-window` (a window id) and `set-option`.
|
|
388
389
|
- A server a test starts is killed by its socket, never by name and never
|
|
389
390
|
with a bare `tmux kill-server`.
|
|
391
|
+
- A test that needs a terminal (an attached tmux client, a key press) runs
|
|
392
|
+
the command in a pane of a second private server and types at that pane
|
|
393
|
+
with `send-keys`; the pane's shell records the exit status
|
|
394
|
+
(`test/session-attach-detach-key.test.mjs`). A mouse report is sent as the
|
|
395
|
+
bytes a terminal sends (`send-keys -l`). A pane program that must show the
|
|
396
|
+
keys it reads puts its terminal in raw mode first: in cooked mode a control
|
|
397
|
+
byte is a signal or an edit, not input.
|
|
390
398
|
|
|
391
399
|
Nor does a test depend on where or how the suite runs:
|
|
392
400
|
|
package/docs/integrations.md
CHANGED
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.0**. Provider implementation and
|
|
9
|
+
This is the operator guide for **oats.okf 5.0.1**. Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
23
23
|
```yaml
|
|
24
24
|
# oats-workspace.yaml (excerpt)
|
|
25
25
|
packages:
|
|
26
|
-
oats.okf: v5.0.
|
|
26
|
+
oats.okf: v5.0.1
|
|
27
27
|
defaults:
|
|
28
28
|
knowledge: { oats.okf: { from: package } }
|
|
29
29
|
stores:
|
|
@@ -105,7 +105,8 @@ explicit `harvest: off`. A 4.x **recorded manifest default** is ignored by
|
|
|
105
105
|
5.0 readers as nobody's decision, not reinterpreted as an opt-out. Explicit
|
|
106
106
|
removed keys still refuse and name the fix. The harvester has no provider
|
|
107
107
|
runtime/model switch or PR-wait deadline; it uses ordinary kernel/harness
|
|
108
|
-
selection and retires after
|
|
108
|
+
selection and retires after successful handoff or nothing promotable. A
|
|
109
|
+
publication failure retains its live home; see [the flow](#the-flow).
|
|
109
110
|
|
|
110
111
|
## The soul's okf.json
|
|
111
112
|
|
|
@@ -165,10 +166,22 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
165
166
|
notes, edits only owned nodes in its own Git checkout, validates the
|
|
166
167
|
**whole base**, and creates a normal `okf-harvest`-labelled PR with v2
|
|
167
168
|
provenance. Proposal text is data written with the native file tool into
|
|
168
|
-
commit-message/PR-body files, never shell command text.
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
169
|
+
commit-message/PR-body files, never shell command text. A publication ref
|
|
170
|
+
is `okf-harvest/<UTC YYYYMMDD>-<fresh UUID>`, with no source/harvester
|
|
171
|
+
name in it; Git validates the full ref and the push must create a new
|
|
172
|
+
ref, never update or adopt an existing one. Source identity stays in
|
|
173
|
+
commit text and PR provenance. After all PRs are open (or nothing is
|
|
174
|
+
promotable), it hands over and retires rather than waiting for acceptance.
|
|
175
|
+
If source authority is unavailable it stops and reports; a consistent
|
|
176
|
+
instance/soul pair alone does not prove proposer authorship.
|
|
177
|
+
**On any publication failure it does not retire:** it keeps the live home,
|
|
178
|
+
clone/any commit, exact error and commit/PR text locations, and notifies
|
|
179
|
+
the source through existing messaging when reachable. Missing or failed
|
|
180
|
+
messaging does not hide the original error or permit retirement. Existing
|
|
181
|
+
attention may expose the blocked home where supported. No automatic
|
|
182
|
+
retries, new recipient or maintainer preflight; a maintainer exists only
|
|
183
|
+
for a labelled PR. A gh error can leave remote effects, so partial or
|
|
184
|
+
uncertain publication is not completion or permission to clean up.
|
|
172
185
|
4. **Review.** A separate `oats.okf/knowledge-maintainer` reviews the PR.
|
|
173
186
|
Human-accepted decisions are not silently superseded; the review path
|
|
174
187
|
keeps its human gate. A PR is not accepted knowledge until merged.
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ 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.9.
|
|
13
|
-
| `oats.okf` | `v5.0.
|
|
14
|
-
| `oats.aweb` | `v1.24.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.9.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.24.1` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf: v5.0.
|
|
32
|
+
`packages:` map (`oats.okf: v5.0.1`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.0.
|
|
47
|
+
oats.okf: v5.0.1 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.0.
|
|
51
|
+
- **Bare version** (`v5.0.1`, `5.0.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.0.
|
|
54
|
+
convention (`v5.0.1` or `oats-framework/v1.9.1`) 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,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.9.
|
|
78
|
-
oats.okf: v5.0.
|
|
79
|
-
oats.aweb: v1.24.
|
|
77
|
+
oats.framework: v1.9.1
|
|
78
|
+
oats.okf: v5.0.1
|
|
79
|
+
oats.aweb: v1.24.1
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.1 ✓ (@ 96b28d5c)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.24.
|
|
137
|
+
oats package add oats.aweb v1.24.1 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.0.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.0.1",
|
|
164
|
+
"commit": "96b28d5cd4f01e48ed50d8e999e8715749a99e87",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.1", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.1", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.
|
|
362
|
-
resolves to tag `oats-framework/v1.9.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.1`
|
|
362
|
+
resolves to tag `oats-framework/v1.9.1`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|