@awebai/oats 0.47.0 → 0.48.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 +70 -30
- package/docs/capabilities.md +8 -0
- package/docs/configuration.md +1 -1
- package/docs/desktop-cli-api.md +72 -10
- package/docs/execution-targets.md +3 -0
- package/docs/implementation.md +19 -0
- package/docs/official-catalog.md +4 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.48.0.md +106 -0
- package/docs/souls-and-instances.md +17 -2
- package/docs/workspaces.md +16 -1
- package/lib/core.mjs +46 -6
- package/lib/teams-verbs.mjs +40 -9
- package/package-catalog.json +11 -4
- 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, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf,
|
|
33
|
+
findInstanceHome, findInstanceHomes, 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, 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 {
|
|
@@ -53,7 +53,7 @@ import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/sched
|
|
|
53
53
|
import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
|
|
54
54
|
|
|
55
55
|
import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
|
|
56
|
-
import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
|
|
56
|
+
import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
|
|
57
57
|
import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
|
|
58
58
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
59
59
|
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
@@ -61,7 +61,7 @@ import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mj
|
|
|
61
61
|
|
|
62
62
|
const rawArgs = process.argv.slice(2);
|
|
63
63
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
64
|
-
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
|
|
64
|
+
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
|
|
65
65
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
66
66
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
67
67
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -1775,26 +1775,55 @@ async function teamsContext(bail) {
|
|
|
1775
1775
|
}
|
|
1776
1776
|
const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
|
|
1777
1777
|
|
|
1778
|
-
/** `oats teams
|
|
1779
|
-
*
|
|
1778
|
+
/** The flags each `oats teams` form takes (value flags → true), beyond the global `--dir` and `--json`.
|
|
1779
|
+
* Anything else is refused, never ignored: a kernel that ignored `--if-absent` would set unconditionally. */
|
|
1780
|
+
const TEAMS_FLAGS = {
|
|
1781
|
+
"": { "--max-age": true },
|
|
1782
|
+
add: { "--team": true, "--description": true, "--no-default": false },
|
|
1783
|
+
remove: {},
|
|
1784
|
+
default: { "--if-absent": false, "--expect": true },
|
|
1785
|
+
};
|
|
1786
|
+
/** The first flag `oats teams <sub>` does not take, or undefined. A value flag's value is skipped as flag()
|
|
1787
|
+
* reads it (the next word unless it starts with `--`). */
|
|
1788
|
+
function teamsUnknownFlag(sub) {
|
|
1789
|
+
const takes = { "--dir": true, "--json": false, ...TEAMS_FLAGS[sub ?? ""] };
|
|
1790
|
+
for (let i = 1; i < args.length; i++) {
|
|
1791
|
+
const a = args[i];
|
|
1792
|
+
if (!a.startsWith("-")) continue;
|
|
1793
|
+
if (!Object.hasOwn(takes, a)) return a;
|
|
1794
|
+
if (takes[a] && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++;
|
|
1795
|
+
}
|
|
1796
|
+
return undefined;
|
|
1797
|
+
}
|
|
1798
|
+
|
|
1799
|
+
/** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
|
|
1800
|
+
* default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
|
|
1801
|
+
* never a provider call. */
|
|
1780
1802
|
async function teamsCmd() {
|
|
1781
1803
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
1782
|
-
const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] | oats teams remove <label> | oats teams default <label> [--dir <deployment>] [--json]";
|
|
1783
|
-
|
|
1804
|
+
const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
|
|
1805
|
+
// A single-dash word (`-x`) is a flag, never the subcommand: teamsUnknownFlag names it.
|
|
1806
|
+
const sub = positional(1)?.startsWith("-") ? undefined : positional(1);
|
|
1784
1807
|
if (sub !== undefined && !["add", "remove", "default"].includes(sub)) bail("E_USAGE", usage);
|
|
1808
|
+
const unknown = teamsUnknownFlag(sub);
|
|
1809
|
+
if (unknown !== undefined) {
|
|
1810
|
+
const form = sub ? `oats teams ${sub}` : "oats teams";
|
|
1811
|
+
bail("E_USAGE", `${form} does not take ${unknown} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${usage}`, { flag: unknown });
|
|
1812
|
+
}
|
|
1785
1813
|
const label = sub ? positional(2) : undefined;
|
|
1786
1814
|
if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
|
|
1787
1815
|
const ctx = await teamsContext(bail);
|
|
1788
1816
|
const V = await import("../lib/teams-verbs.mjs");
|
|
1789
1817
|
let result = null;
|
|
1790
1818
|
try {
|
|
1791
|
-
if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description") });
|
|
1819
|
+
if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description"), noDefault: args.includes("--no-default") });
|
|
1792
1820
|
else if (sub === "remove") result = V.teamsRemove(ctx, label);
|
|
1793
|
-
else if (sub === "default") result = V.teamsDefault(ctx, label);
|
|
1821
|
+
else if (sub === "default") result = V.teamsDefault(ctx, label, { ifAbsent: args.includes("--if-absent"), expect: valueFlag("expect") });
|
|
1794
1822
|
} catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
|
|
1795
1823
|
const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
|
|
1796
|
-
if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
|
|
1797
|
-
if (result) console.log(
|
|
1824
|
+
if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed, ...(result.reused ? { reused: true } : {}) } : withObservation(doc)); return; }
|
|
1825
|
+
if (result?.reused) console.log(`Team ${label} is already declared with that id: nothing to change`);
|
|
1826
|
+
else if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
|
|
1798
1827
|
console.log(`default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
|
|
1799
1828
|
console.log(`local ${doc.localTeams === null ? "allowed (standalone)" : doc.localTeams ? "allowed (localTeams: true)" : "not allowed"}`);
|
|
1800
1829
|
if (!doc.teams.length) console.log("teams (none: `oats aweb setup` creates them, or `oats teams add <label> --team <id>`)");
|
|
@@ -2612,35 +2641,41 @@ function retireCmd() {
|
|
|
2612
2641
|
const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
|
|
2613
2642
|
if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
|
|
2614
2643
|
if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
|
|
2615
|
-
|
|
2644
|
+
// What the plan says about recorded children holds on every apply path: the
|
|
2645
|
+
// retirement stops them first and keeps them (retireInstance, once it has
|
|
2646
|
+
// resolved the home). A guarded apply acts on the children of the plan it
|
|
2647
|
+
// revalidated; a plain or --self retire computes them as the plan does, and
|
|
2648
|
+
// passes none when there are none.
|
|
2649
|
+
let replayPath = null, plannedExtraWorktrees, fresh, children;
|
|
2616
2650
|
if (planRev !== undefined) {
|
|
2617
2651
|
if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
|
|
2618
2652
|
// Replay first: after a successful retire the home is gone, so the receipt
|
|
2619
2653
|
// (beside the instances dir, keyed by the idempotency key) is the answer.
|
|
2620
2654
|
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; } };
|
|
2621
2655
|
for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
|
|
2622
|
-
let fresh;
|
|
2623
2656
|
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
|
|
2624
2657
|
replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
|
|
2625
2658
|
// The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
|
|
2626
2659
|
// move or remove one that no longer reads that way when it gets to them.
|
|
2627
2660
|
plannedExtraWorktrees = fresh.facts.extraWorktrees;
|
|
2628
2661
|
if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
|
|
2629
|
-
|
|
2630
|
-
|
|
2631
|
-
|
|
2632
|
-
|
|
2633
|
-
for (const kid of fresh.facts.children) {
|
|
2634
|
-
try { const s = stopInstanceSession(kid.home, {}); childrenStopped.push({ instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }); }
|
|
2635
|
-
catch (e) { childrenStopped.push({ instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }); }
|
|
2636
|
-
}
|
|
2637
|
-
const running = childrenStopped.filter((k) => !k.ok);
|
|
2638
|
-
if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
|
|
2662
|
+
children = fresh.facts.children;
|
|
2663
|
+
} else {
|
|
2664
|
+
const recorded = descendantsOf(root, name);
|
|
2665
|
+
if (recorded.length) children = recorded;
|
|
2639
2666
|
}
|
|
2640
2667
|
let r;
|
|
2641
|
-
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}) }); }
|
|
2642
|
-
catch (e) {
|
|
2643
|
-
|
|
2668
|
+
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}), ...(children ? { children } : {}) }); }
|
|
2669
|
+
catch (e) {
|
|
2670
|
+
if (!e?.code) throw e;
|
|
2671
|
+
// A child still running (or whose stop could not be established) refused the retirement: the
|
|
2672
|
+
// guarded apply returns the plan it acted on, and the text names each child's reason.
|
|
2673
|
+
if (e.code === "E_CHILDREN_RUNNING") {
|
|
2674
|
+
const running = e.details.childrenStopped.filter((k) => !k.ok);
|
|
2675
|
+
return args.includes("--json") ? jsonFail(e.code, e.message, { ...e.details, ...(planRev !== undefined ? { plan: fresh } : {}) }) : die(`children still running: ${running.map((k) => `${k.instance} (${k.code})`).join(", ")}; nothing retired`);
|
|
2676
|
+
}
|
|
2677
|
+
return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message);
|
|
2678
|
+
}
|
|
2644
2679
|
if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
|
|
2645
2680
|
// A retired home's wake jobs are forgotten (definitions only; nothing is
|
|
2646
2681
|
// stopped by this); a deferred self-retire keeps them until the home is gone.
|
|
@@ -2677,6 +2712,7 @@ function retireCmd() {
|
|
|
2677
2712
|
process.exit(1);
|
|
2678
2713
|
}
|
|
2679
2714
|
console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
|
|
2715
|
+
for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}`);
|
|
2680
2716
|
// Preserving work and not saying so leaves the operator believing it is gone,
|
|
2681
2717
|
// which is most of the harm of deleting it. Name the classes and the path.
|
|
2682
2718
|
for (const line of workRecoveryLines(r)) console.log(line);
|
|
@@ -3414,7 +3450,7 @@ function versionCmd() {
|
|
|
3414
3450
|
// Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
|
|
3415
3451
|
// runs on resolve/materialize (contract §6); a feature the binary does not implement is
|
|
3416
3452
|
// never listed.
|
|
3417
|
-
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], 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"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
|
|
3453
|
+
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], 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"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
|
|
3418
3454
|
return;
|
|
3419
3455
|
}
|
|
3420
3456
|
console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
|
|
@@ -4217,10 +4253,14 @@ Usage:
|
|
|
4217
4253
|
[--max-age <s>] (souls have no private mode), with origin
|
|
4218
4254
|
(member <key> @ <commit> | package <id> v<ver>) and its
|
|
4219
4255
|
teams on this deployment
|
|
4220
|
-
oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label>
|
|
4221
|
-
| default <label>
|
|
4256
|
+
oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label>
|
|
4257
|
+
| default <label> [--if-absent | --expect <label>]
|
|
4258
|
+
[--dir <d>] this deployment's teams (shared + local), the
|
|
4222
4259
|
[--max-age <s>] (the read form only) default, the workspace's souls:; add/remove/default
|
|
4223
|
-
edit oats-local.yaml (only with localTeams: true)
|
|
4260
|
+
edit oats-local.yaml (only with localTeams: true);
|
|
4261
|
+
--no-default: the mapping only (an exact repeat is
|
|
4262
|
+
reuse); --if-absent / --expect: set the default only
|
|
4263
|
+
where there is none / it is <label>
|
|
4224
4264
|
oats soul teams <soul>|'*' [--dir <d>] which teams a soul may join here, its default, and
|
|
4225
4265
|
[--max-age <s>] [--json] why (the workspace's souls: and local teams)
|
|
4226
4266
|
oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
|
package/docs/capabilities.md
CHANGED
|
@@ -495,6 +495,14 @@ start (a renewed session grant, for example) leaves the CURRENT one on record. A
|
|
|
495
495
|
launch hook that answers without `meta` keeps its previous entry; a start whose
|
|
496
496
|
preparation fails changes nothing.
|
|
497
497
|
|
|
498
|
+
A launch hook's `brief` is not used. A home's `TASK.md` (which carries the
|
|
499
|
+
spawn hooks' briefs) and `AGENTS.md` are composed once, at spawn, and no start
|
|
500
|
+
rewrites them. A provider whose state changes at a start records it in `meta`.
|
|
501
|
+
`oats inspect --home <abs> --json` reads the served identity a provider
|
|
502
|
+
recorded there (the messaging provider's, when it has one) as `identity`. A
|
|
503
|
+
spawn brief that describes such state should say it is the state at spawn and
|
|
504
|
+
point to that command.
|
|
505
|
+
|
|
498
506
|
A launch hook may do idempotent provider registration on a real start (an
|
|
499
507
|
aweb home registering with the host wake broker, for example). How the
|
|
500
508
|
kernel runs it depends on whether its capability declares **preview
|
package/docs/configuration.md
CHANGED
|
@@ -63,7 +63,7 @@ refused (`E_WORKSPACE_SCHEMA`).
|
|
|
63
63
|
| `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
|
|
64
64
|
| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
|
|
65
65
|
| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
|
|
66
|
-
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
|
|
66
|
+
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
|
|
67
67
|
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
|
|
68
68
|
| `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
|
|
69
69
|
| `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -40,7 +40,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
|
40
40
|
"team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
|
|
41
41
|
"preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
|
|
42
42
|
"workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
|
|
43
|
-
"automation-descriptions","souls-capabilities","soul-composed-instructions"],
|
|
43
|
+
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default"],
|
|
44
44
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
45
45
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
46
46
|
"capabilityShowApi":1}
|
|
@@ -112,6 +112,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
|
112
112
|
| `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
|
|
113
113
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
114
114
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
115
|
+
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
115
116
|
|
|
116
117
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
117
118
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -367,7 +368,7 @@ An instance subject, abridged:
|
|
|
367
368
|
| `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
|
|
368
369
|
| `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
|
|
369
370
|
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
|
|
370
|
-
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null` |
|
|
371
|
+
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
|
|
371
372
|
| `problems` | below |
|
|
372
373
|
|
|
373
374
|
**Soul row** (`soulsApi: 2`). For a home it is read from the recorded
|
|
@@ -1250,9 +1251,9 @@ unknown.
|
|
|
1250
1251
|
|
|
1251
1252
|
```text
|
|
1252
1253
|
oats teams [--dir <d>] [--max-age <s>] --json
|
|
1253
|
-
oats teams add <label> --team <id> [--description <d>] --json
|
|
1254
|
+
oats teams add <label> --team <id> [--description <d>] [--no-default] --json
|
|
1254
1255
|
oats teams remove <label> --json
|
|
1255
|
-
oats teams default <label> --json
|
|
1256
|
+
oats teams default <label> [--if-absent | --expect <label>] --json
|
|
1256
1257
|
```
|
|
1257
1258
|
|
|
1258
1259
|
```json
|
|
@@ -1284,13 +1285,41 @@ oats teams default <label> --json
|
|
|
1284
1285
|
still runs there: taking local teams away is the last step of committing
|
|
1285
1286
|
them in the workspace.
|
|
1286
1287
|
- **`add`**: the first team added also becomes the local `defaultTeam`. A
|
|
1287
|
-
label already declared is `E_TEAM_EXISTS {label, from
|
|
1288
|
-
|
|
1288
|
+
label already declared is `E_TEAM_EXISTS {label, from, observed: {label,
|
|
1289
|
+
team, from}}` (`observed` is the declared mapping; `from` is `"local"` or
|
|
1290
|
+
`"shared"`); a bad label or no `--team` is `E_BAD_ARGS`.
|
|
1291
|
+
- **`add --no-default`** (feature `teams-conditional-default`) writes the
|
|
1292
|
+
mapping and never touches `defaultTeam`. A mapping already declared with
|
|
1293
|
+
the same label and the same team id (local or shared) is reuse: the answer
|
|
1294
|
+
is `changed: false, reused: true`, so a setup can retry it. The description
|
|
1295
|
+
is neither compared nor changed. The same label with another id is
|
|
1296
|
+
`E_TEAM_EXISTS` as above. `reused` appears only on that answer. Where local
|
|
1297
|
+
teams are not allowed, `add --no-default` is refused with local-teams-closed
|
|
1298
|
+
like every `add`, before reuse is considered.
|
|
1289
1299
|
- **`remove`**: a label the local `defaultTeam` names is `E_TEAM_IN_USE
|
|
1290
1300
|
{label, usedBy: ["defaultTeam"]}`; a shared label is `E_TEAM_SHARED {label,
|
|
1291
1301
|
at}` (a label in both files can be removed locally); unknown is
|
|
1292
1302
|
`E_TEAM_UNKNOWN {label}`.
|
|
1293
1303
|
- **`default`**: any declared label, else `E_TEAM_UNKNOWN`.
|
|
1304
|
+
- **`default --if-absent`** sets it only where the deployment has no effective
|
|
1305
|
+
default (this document's `defaultTeam` is `null`); **`default --expect
|
|
1306
|
+
<label0>`** only where the effective default's label is `<label0>`, local
|
|
1307
|
+
or inherited from the workspace (feature `teams-conditional-default`). The
|
|
1308
|
+
two together are `E_BAD_ARGS`. A failed condition is `E_TEAM_DEFAULT_MISMATCH
|
|
1309
|
+
{expected: {absent: true} | {label}, observed}`, `observed` being the
|
|
1310
|
+
`defaultTeam` exactly as this document reports it (or `null`); nothing was
|
|
1311
|
+
written. A soul's `souls:` default is not the deployment's and is not
|
|
1312
|
+
looked at. The refusals above run first, in order: `E_BAD_ARGS`,
|
|
1313
|
+
local-teams-closed, `E_TEAM_UNKNOWN`, then the condition. When the
|
|
1314
|
+
condition holds and `<label>` already is the local default, `changed` is
|
|
1315
|
+
`false`.
|
|
1316
|
+
- **Flags**: each form refuses a flag it does not take with `E_USAGE {flag}`,
|
|
1317
|
+
naming the flag and the usage, before anything is read. `add` takes
|
|
1318
|
+
`--team`, `--description`, `--no-default`; `remove` none; `default`
|
|
1319
|
+
`--if-absent`, `--expect`; every form `--dir` and `--json`, and the read
|
|
1320
|
+
form `--max-age` (on a write form, `--max-age` is the kernel's own
|
|
1321
|
+
`E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
|
|
1322
|
+
answer, as for every command.
|
|
1294
1323
|
- A write that would introduce an unknown reference is refused with that
|
|
1295
1324
|
code; an invalid result is `E_WORKSPACE_SCHEMA`.
|
|
1296
1325
|
- **Writes** edit `oats-local.yaml` in place and touch only the entries that
|
|
@@ -1298,7 +1327,22 @@ oats teams default <label> --json
|
|
|
1298
1327
|
entries, are kept. Each verb re-reads the file and judges its refusals on it
|
|
1299
1328
|
as it is now, and writes only if the file did not change meanwhile (else it
|
|
1300
1329
|
redoes the edit on the new content). A file that keeps changing is
|
|
1301
|
-
`E_LOCAL_CHANGED {path}`; nothing was written.
|
|
1330
|
+
`E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
|
|
1331
|
+
and `--expect` is judged the same way, on the file as it is now and again on
|
|
1332
|
+
every redo.
|
|
1333
|
+
- **Concurrency.** Every `add`, `remove` and `default` holds
|
|
1334
|
+
`<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
|
|
1335
|
+
Among concurrent `oats teams` writers on one deployment, a conditional write
|
|
1336
|
+
therefore never overwrites a default another of them set: when two race, the
|
|
1337
|
+
later one sees the earlier result and refuses with
|
|
1338
|
+
`E_TEAM_DEFAULT_MISMATCH`. A lock still held after 5 s is `E_LOCAL_BUSY
|
|
1339
|
+
{path, lock}`, naming the directory to remove when no oats process is
|
|
1340
|
+
editing; nothing was written. The limits: a person or tool editing
|
|
1341
|
+
`oats-local.yaml` directly does not take the lock (the content compare still
|
|
1342
|
+
catches most such edits, but not one landing between the compare and the
|
|
1343
|
+
rename), and changes to the committed `oats-workspace.yaml` (a pull, a
|
|
1344
|
+
merge) are not serialized with it: the condition reads the workspace file
|
|
1345
|
+
when it is judged, and that is the only promise.
|
|
1302
1346
|
|
|
1303
1347
|
<a id="oats-soul-teams"></a>
|
|
1304
1348
|
### `oats soul teams`
|
|
@@ -2848,14 +2892,32 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
2848
2892
|
pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
|
|
2849
2893
|
`{…, alreadyScheduled: true, requestedAt}`.
|
|
2850
2894
|
|
|
2895
|
+
**Recorded children**, on every apply (plain, guarded and `--self`), as the
|
|
2896
|
+
plan says: each child the plan lists is stopped first (bounded SIGTERM,
|
|
2897
|
+
never escalated) and kept, once the retire has resolved the home and before
|
|
2898
|
+
the instance's own session is stopped. `childrenStopped[]` lists them,
|
|
2899
|
+
deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
|
|
2900
|
+
`{instance, home, ok: false, code, message, stillRunning}`. A plain or
|
|
2901
|
+
`--self` receipt carries it only when there are children; a guarded receipt
|
|
2902
|
+
always does (`[]` when there are none). One child still running after the
|
|
2903
|
+
grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
|
|
2904
|
+
`E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
|
|
2905
|
+
`E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
|
|
2906
|
+
`code`). **`--force` does not bypass it**: `--force` covers incomplete
|
|
2907
|
+
cleanup, not a running child. A `--self` retirement stops the children
|
|
2908
|
+
recorded when it was scheduled that are still instances (a child retired in
|
|
2909
|
+
between is skipped), in its detached completion before it stops the caller;
|
|
2910
|
+
a refusal there leaves the caller's window and home in place and
|
|
2911
|
+
writes `{ok: false, error: {code: "E_CHILDREN_RUNNING"}, childrenStopped,
|
|
2912
|
+
retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
|
|
2913
|
+
|
|
2851
2914
|
**Guarded apply** (what the Desktop sends): `--plan-revision` and
|
|
2852
2915
|
`--idempotency-key` together.
|
|
2853
2916
|
- A used key replays its receipt as an **envelope** with `replayed: true`
|
|
2854
2917
|
(receipts live beside the instances directory and outlive the home).
|
|
2855
2918
|
- The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
|
|
2856
|
-
-
|
|
2857
|
-
|
|
2858
|
-
{childrenStopped, plan}`.
|
|
2919
|
+
- The children stopped are those of the revalidated plan, and a refusal
|
|
2920
|
+
carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
|
|
2859
2921
|
- A first guarded retire prints the raw receipt with `planRevision`,
|
|
2860
2922
|
`idempotencyKey` and `replayed: false`.
|
|
2861
2923
|
|
|
@@ -744,6 +744,9 @@ oats session attach --home /abs/home
|
|
|
744
744
|
harness, `shell` for a fallback shell,
|
|
745
745
|
`stopped` for an absent or dead terminal, or `not-launched`. An unavailable
|
|
746
746
|
backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
|
|
747
|
+
A home without its session receipt is refused with
|
|
748
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for; what
|
|
749
|
+
to do is in [souls and instances](souls-and-instances.md#retire).
|
|
747
750
|
Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
|
|
748
751
|
live claim that the instance needs input from a human, `{since, producer,
|
|
749
752
|
reason, message}`, or `null`; it is non-null only for a running harness
|
package/docs/implementation.md
CHANGED
|
@@ -368,3 +368,22 @@ and acts on every existing session through its recorded socket
|
|
|
368
368
|
`list-windows`, `new-window` (a window id) and `set-option`.
|
|
369
369
|
- A server a test starts is killed by its socket, never by name and never
|
|
370
370
|
with a bare `tmux kill-server`.
|
|
371
|
+
|
|
372
|
+
Nor does a test depend on where or how the suite runs:
|
|
373
|
+
|
|
374
|
+
- A worker whose working directory is inside an instance home (a developer
|
|
375
|
+
agent running the suite from its work tree) is that instance to the
|
|
376
|
+
kernel. `isolateSessionEnvironment` leaves it; a fixture that builds its
|
|
377
|
+
environment itself calls `leaveEnclosingInstance(base)` and moves back
|
|
378
|
+
when it is done.
|
|
379
|
+
- `isolateSessionEnvironment` drops `CLAUDECODE`, which a worker inherits
|
|
380
|
+
from a Claude Code session: a server the worker starts would hold it.
|
|
381
|
+
- An expected path is built on a canonical fixture base,
|
|
382
|
+
`realpathSync(mkdtempSync(…))`: the platform's temporary directory can be
|
|
383
|
+
a symlink (`/var` on macOS), and the kernel builds the paths it reports on
|
|
384
|
+
its working directory, which the OS gives as the physical path.
|
|
385
|
+
- A probe of the host that reads under `HOME` (the scheduler's installed
|
|
386
|
+
unit) runs with the fixture's own `HOME`.
|
|
387
|
+
- A fixture the filesystem may not represent (a file name that is not valid
|
|
388
|
+
UTF-8, which APFS refuses) is probed in the fixture directory and skipped
|
|
389
|
+
with its reason only when refused; Linux CI runs it.
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,14 +9,15 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.8.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
15
|
-
| `oats.engineering` | `v1.
|
|
14
|
+
| `oats.aweb` | `v1.23.2` | `oats.aweb` (messaging) | |
|
|
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` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
19
19
|
| `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
|
|
20
|
+
| `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
|
|
20
21
|
|
|
21
22
|
Each package lives in its own `awebai/oats-*` repository except
|
|
22
23
|
`oats.framework`, whose payload root is `oats-package/` here. A capability id
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v4.1.1`, `4.1.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 (`v4.1.1` or `oats-framework/v1.
|
|
54
|
+
convention (`v4.1.1` or `oats-framework/v1.8.0`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,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.
|
|
77
|
+
oats.framework: v1.8.0
|
|
78
78
|
oats.okf: v4.1.1
|
|
79
|
-
oats.aweb: v1.
|
|
79
|
+
oats.aweb: v1.23.2
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -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.
|
|
137
|
+
oats package add oats.aweb v1.23.2 # 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
|
```
|
|
@@ -339,11 +339,11 @@ A soul that names one of the package's capabilities with
|
|
|
339
339
|
"policy": "docs/official-catalog.md",
|
|
340
340
|
"packages": {
|
|
341
341
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
|
|
342
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
342
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.8.0", "path": "oats-package" }
|
|
343
343
|
}
|
|
344
344
|
}
|
|
345
345
|
```
|
|
346
346
|
|
|
347
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
348
|
-
resolves to tag `oats-framework/v1.
|
|
347
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.8.0`
|
|
348
|
+
resolves to tag `oats-framework/v1.8.0`. Resolving through the catalog never
|
|
349
349
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# OATS 0.48.0
|
|
2
|
+
|
|
3
|
+
2026-10-08
|
|
4
|
+
|
|
5
|
+
## Added
|
|
6
|
+
|
|
7
|
+
- **Conditional team default and mapping-only add (#771), feature
|
|
8
|
+
`teams-conditional-default`.** `oats teams default <label> --if-absent`
|
|
9
|
+
sets the local default only where the deployment has no effective default;
|
|
10
|
+
`--expect <label0>` only where the effective default (local, or inherited
|
|
11
|
+
from the workspace) is `<label0>`. A failed condition is
|
|
12
|
+
`E_TEAM_DEFAULT_MISMATCH {expected, observed}` and writes nothing.
|
|
13
|
+
`oats teams add <label> --team <id> --no-default` writes the mapping without
|
|
14
|
+
touching `defaultTeam`; the same label and id already declared is reuse
|
|
15
|
+
(`changed: false, reused: true`). `E_TEAM_EXISTS` also carries `observed:
|
|
16
|
+
{label, team, from}`. Every `oats teams` write holds
|
|
17
|
+
`<deployment>/.agents/locks/local.lock`, so the later of two racing
|
|
18
|
+
conditional writes sees the earlier one and refuses with
|
|
19
|
+
`E_TEAM_DEFAULT_MISMATCH`; a lock still held after 5 s is `E_LOCAL_BUSY`,
|
|
20
|
+
with nothing written. `teamsApi`
|
|
21
|
+
stays 2: the `oats teams --json` shape is unchanged. Callers check the
|
|
22
|
+
feature before passing the flags, because older kernels ignore them, and
|
|
23
|
+
there `--if-absent` is an unconditional set.
|
|
24
|
+
|
|
25
|
+
## Changed
|
|
26
|
+
|
|
27
|
+
- **The Desktop accepts OATS CLIs `>=0.25.8 <0.49.0`.** The compatibility band
|
|
28
|
+
admits 0.48; existing feature gates remain unchanged.
|
|
29
|
+
|
|
30
|
+
- **`oats teams` refuses flags it does not take.** Each form (`oats teams`,
|
|
31
|
+
`add`, `remove`, `default`) answers an unknown flag with `E_USAGE {flag}`,
|
|
32
|
+
naming it and the usage, before anything is read or written. Before, they
|
|
33
|
+
were ignored. `--server` on `oats teams` is now refused too: teams has never
|
|
34
|
+
been routed to a server. A script that passes stray flags must drop them.
|
|
35
|
+
|
|
36
|
+
- **The workspace pins oats.framework 1.8.0 and oats.engineering 1.9.0.**
|
|
37
|
+
The official catalog resolves bare `oats.framework` versions to
|
|
38
|
+
`oats-framework/v1.8.0` (oats.support 1.0.0, the support desk role), and
|
|
39
|
+
`oats.engineering` to `v1.9.0`. That adds oats.maintainer's
|
|
40
|
+
`/support-maintainer` skill: a maintainer that serves the support desk's
|
|
41
|
+
tickets. The capability mirrors under `mirrors/` are regenerated from the
|
|
42
|
+
v1.9.0 tag and their trees equal the tag's. Running instances keep what
|
|
43
|
+
they were spawned with; new spawns pick these up after `oats sync`.
|
|
44
|
+
|
|
45
|
+
- **The workspace and official catalog pin oats.aweb 1.23.2.** The generated
|
|
46
|
+
`mirrors/oats-aweb` payload equals the provider v1.23.2 tag tree. This adds
|
|
47
|
+
verified LOCAL join mapping/default readback and explicit LOCAL identity
|
|
48
|
+
selectors at launch and preview (1.23.1), and GLOBAL grant metadata that
|
|
49
|
+
records the app snapshot from each successful native mint receipt: Comms
|
|
50
|
+
labels it as the at-spawn snapshot, inspect shows the current recorded
|
|
51
|
+
metadata, and preview warnings say whether it is retained or unknown
|
|
52
|
+
pending renewal (1.23.2). That snapshot is not a live app acceptance. Existing captured homes
|
|
53
|
+
do not adopt the changes automatically; this pin does not perform sync,
|
|
54
|
+
restart or live acceptance.
|
|
55
|
+
|
|
56
|
+
- **oats.apps 1.0.0 is a new official package.** It exports `oats.folio` and
|
|
57
|
+
`oats.library`, additive guidance capabilities for the aweb Folio and Library
|
|
58
|
+
apps (`aw >=1.36.26`; OATS 0.47.0 or later), and the catalog aliases both
|
|
59
|
+
ids to the package. The generated `mirrors/oats-folio` and
|
|
60
|
+
`mirrors/oats-library` equal the v1.0.0 tag's payload trees. The workspace
|
|
61
|
+
adds `awebai/oats-apps` as a member (its expert soul `oats-apps-expert`) and
|
|
62
|
+
pins `oats.apps: git:github.com/awebai/oats-apps@v1.0.0`: an installed CLI
|
|
63
|
+
resolves bare versions through the catalog it shipped with, and 0.47.0's has
|
|
64
|
+
no `oats.apps`, so the pin goes bare once every deployment's CLI carries
|
|
65
|
+
this entry. No soul selects either capability yet, and no workspace default
|
|
66
|
+
is added.
|
|
67
|
+
|
|
68
|
+
## Fixed
|
|
69
|
+
|
|
70
|
+
- **Every `oats retire` stops recorded children first, as its plan says
|
|
71
|
+
(#778).** `oats retire <name> --plan` has always said that recorded child
|
|
72
|
+
instances "are stopped first (bounded SIGTERM, never escalated) and
|
|
73
|
+
retained" and that "a child still running after the grace refuses the
|
|
74
|
+
retirement", but before 0.48.0 only the guarded apply (`--plan-revision`
|
|
75
|
+
with `--idempotency-key`, what the Desktop sends) did it. A plain
|
|
76
|
+
`oats retire <name>` and a `--self` retirement left the children running,
|
|
77
|
+
attached ones on a work tree that had just been removed, with no stop
|
|
78
|
+
event.
|
|
79
|
+
- **Behavior change.** A plain `oats retire` and `--self` now stop recorded
|
|
80
|
+
children first and keep them. They refuse, retiring nothing, when one
|
|
81
|
+
won't stop or its session can't be established: `E_CHILDREN_RUNNING
|
|
82
|
+
{childrenStopped}`, exit 1, and the text names each child and its code
|
|
83
|
+
(`children still running: <name> (<code>); nothing retired`). `--force`
|
|
84
|
+
does not bypass it: end the child's session yourself (the receipt's
|
|
85
|
+
`stillRunning` names its processes), then retry.
|
|
86
|
+
- The receipt lists the children as `childrenStopped[]` (absent when there
|
|
87
|
+
are none), and the text prints `child <name>: stopped` or
|
|
88
|
+
`already idle` for each.
|
|
89
|
+
- `--self` stops the children recorded when the retirement was scheduled
|
|
90
|
+
(skipping any retired since), in its detached completion before it stops
|
|
91
|
+
the caller. A refusal leaves the caller's window and home in place and
|
|
92
|
+
writes `E_CHILDREN_RUNNING` with `childrenStopped` and the `retry` command
|
|
93
|
+
to the result file that `oats status` reports.
|
|
94
|
+
- The guarded apply is unchanged for the Desktop. It now stops children
|
|
95
|
+
only after the retire's own read-only refusals, so a retire refused
|
|
96
|
+
there leaves its children running.
|
|
97
|
+
|
|
98
|
+
- **A home without its session receipt says what was looked for and what to
|
|
99
|
+
do (#762).** `session inspect`, `start` and `restart` refused such a home
|
|
100
|
+
with a bare `ENOENT`. The `E_RUNTIME_ENDPOINT_UNKNOWN` refusal now names
|
|
101
|
+
the receipt path it looked for, says to address the home exactly as
|
|
102
|
+
`oats status` prints it (a different spelling of the path looks for the
|
|
103
|
+
receipt elsewhere), and otherwise names the causes and the remedy: stop its
|
|
104
|
+
session yourself if one runs, then `oats retire <name> --plan` and
|
|
105
|
+
`oats retire <name>`, and respawn. The code is unchanged. The receipt's key
|
|
106
|
+
for a differently spelled path is #780.
|
|
@@ -431,6 +431,13 @@ takes a final capture of notes and the session record into durable custody; an
|
|
|
431
431
|
incomplete capture keeps the home for a retry. Retirement never waits for a
|
|
432
432
|
model or GitHub: processing continues after the home is gone.
|
|
433
433
|
|
|
434
|
+
Recorded children (the instances whose recorded parent chain reaches this
|
|
435
|
+
one) are stopped first, never escalated, and kept: their homes stay. If one is
|
|
436
|
+
still running after the grace, or its stop cannot be established, retire
|
|
437
|
+
refuses with `E_CHILDREN_RUNNING` and retires nothing; `--force` does not
|
|
438
|
+
bypass it. This holds for plain, guarded and `--self` retires alike
|
|
439
|
+
([desktop-cli-api.md](desktop-cli-api.md)).
|
|
440
|
+
|
|
434
441
|
Before any retire hook runs, retire preserves the instance's uncommitted and
|
|
435
442
|
unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
|
|
436
443
|
the summary. One retire writes at most one recovery directory. A worktree
|
|
@@ -753,8 +760,16 @@ exist under "not copied", by name, with the declaring capability. The
|
|
|
753
760
|
declaration is recorded at spawn: a home spawned before its capability
|
|
754
761
|
declared them gains no exclusion from a package update, and is copied whole.
|
|
755
762
|
|
|
756
|
-
Retire stops the harness through the home's session receipt
|
|
757
|
-
|
|
763
|
+
Retire stops the harness through the home's session receipt, kept beside the
|
|
764
|
+
home in the instances directory's `.oats-retirement/baselines/` and keyed by
|
|
765
|
+
the home's path. First address the home exactly as `oats status` prints it: a
|
|
766
|
+
different spelling of its path (letter case, a deployment directory moved
|
|
767
|
+
since the spawn) looks for the receipt elsewhere. A home can also be without
|
|
768
|
+
its receipt because it was spawned before 0.25.9, it was copied, the
|
|
769
|
+
`.oats-retirement` beside it was removed, or its creation did not finish;
|
|
770
|
+
`session inspect`, `start` and `restart` then refuse with
|
|
771
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN` naming the receipt path they looked for. Such a
|
|
772
|
+
home retires only when its session is observably gone:
|
|
758
773
|
instance.json records no launch, or the recorded tmux server is not running,
|
|
759
774
|
or the recorded window is gone and no pane on that server works in the home;
|
|
760
775
|
and, always, no live process on this host works in the home (a harness
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.8.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v4.1.1
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -421,11 +421,26 @@ the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
|
|
|
421
421
|
```
|
|
422
422
|
oats teams [--json] # the teams, ids, the default, localTeams, the workspace's souls:, problems
|
|
423
423
|
oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
|
|
424
|
+
oats teams add <label> --team <id> --no-default # the mapping only; the same label and id again is reuse
|
|
424
425
|
oats teams remove <label> # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
|
|
425
426
|
oats teams default <label> # the local default
|
|
427
|
+
oats teams default <label> --if-absent # ... only where there is no effective default
|
|
428
|
+
oats teams default <label> --expect <label0> # ... only where the effective default is <label0>
|
|
426
429
|
oats soul teams <soul>|'*' [--json] # a soul's default and teams here, and which souls: key gave them
|
|
427
430
|
```
|
|
428
431
|
|
|
432
|
+
`--if-absent` and `--expect` make a setup safe to run against a deployment
|
|
433
|
+
whose default it has not chosen: the condition is the effective default that
|
|
434
|
+
`oats teams` reports (the local one, else the workspace's), judged when the
|
|
435
|
+
file is written, and a failed one (`E_TEAM_DEFAULT_MISMATCH`) reports what it
|
|
436
|
+
found and writes nothing. A soul's `souls:` default is not the deployment's
|
|
437
|
+
default and is not looked at. Concurrent `oats teams` writes on one deployment
|
|
438
|
+
are serialized, so of two racing conditional writes the later one refuses;
|
|
439
|
+
hand edits to `oats-local.yaml` and changes to `oats-workspace.yaml` are not
|
|
440
|
+
serialized with them. Each form refuses a flag it does not take (`E_USAGE`).
|
|
441
|
+
Callers check for the feature `teams-conditional-default` in `oats version
|
|
442
|
+
--json` first: an older kernel ignores these flags.
|
|
443
|
+
|
|
429
444
|
The messaging provider's own setup creates provider teams (see the provider's
|
|
430
445
|
documentation). The spawn preview, `inspect` and `oats souls` report a soul's
|
|
431
446
|
`teams` and `defaultTeam`; readiness reports the team problems in
|
package/lib/core.mjs
CHANGED
|
@@ -5456,16 +5456,26 @@ function launchStateAgrees(meta, authority) {
|
|
|
5456
5456
|
["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
|
|
5457
5457
|
}
|
|
5458
5458
|
|
|
5459
|
+
/** The refusal for a home whose session receipt file does not exist where its path says it is. The
|
|
5460
|
+
* receipt is keyed by the home's path, so a different spelling of that path looks elsewhere. */
|
|
5461
|
+
function missingSessionReceipt(home, receiptPath) {
|
|
5462
|
+
return oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `no session receipt for ${home} at ${receiptPath}. First address the home exactly as \`oats status\` prints it (a different spelling — letter case, a moved deployment directory — looks for the receipt elsewhere). Otherwise the home was copied, the .oats-retirement beside it was removed, or its creation did not finish: stop its session yourself if one runs, then \`oats retire ${basename(home)} --plan\` and \`oats retire ${basename(home)}\` (work is preserved), and respawn.`);
|
|
5463
|
+
}
|
|
5464
|
+
|
|
5459
5465
|
/** Session control uses the independent endpoint receipt. */
|
|
5460
5466
|
function instanceSessionTarget(home) {
|
|
5461
5467
|
if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
|
|
5462
5468
|
home = realPathOrNearest(home);
|
|
5463
5469
|
refuseHerdrHome(home);
|
|
5470
|
+
const receiptPath = retirementBaselinePath(home);
|
|
5464
5471
|
let baseline, meta;
|
|
5465
5472
|
try {
|
|
5466
|
-
baseline = JSON.parse(readFileSync(
|
|
5473
|
+
baseline = JSON.parse(readFileSync(receiptPath, "utf8"));
|
|
5467
5474
|
meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
|
|
5468
|
-
} catch (e) {
|
|
5475
|
+
} catch (e) {
|
|
5476
|
+
if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home, receiptPath);
|
|
5477
|
+
throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`);
|
|
5478
|
+
}
|
|
5469
5479
|
const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
|
|
5470
5480
|
if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
|
|
5471
5481
|
if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
|
|
@@ -5593,6 +5603,17 @@ export function stopInstanceSession(home, o = {}) {
|
|
|
5593
5603
|
return { home: s.home, backend: s.target.backend, stopped: true, alreadyIdle: false, state: receipt.state, receipt };
|
|
5594
5604
|
}
|
|
5595
5605
|
|
|
5606
|
+
/** What a retire plan promises about recorded children, applied: each is stopped
|
|
5607
|
+
* (default grace, never escalated) in the order given (the plan's: deepest first)
|
|
5608
|
+
* and kept. Every outcome is collected, so a refusal names each child that is
|
|
5609
|
+
* still running or whose stop could not be established. */
|
|
5610
|
+
function stopRecordedChildren(children) {
|
|
5611
|
+
return children.map((kid) => {
|
|
5612
|
+
try { const s = stopInstanceSession(kid.home, {}); return { instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }; }
|
|
5613
|
+
catch (e) { return { instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }; }
|
|
5614
|
+
});
|
|
5615
|
+
}
|
|
5616
|
+
|
|
5596
5617
|
export async function attachInstanceSession(home) {
|
|
5597
5618
|
const s = instanceSessionTarget(home);
|
|
5598
5619
|
if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
|
|
@@ -5995,7 +6016,10 @@ export function startInstanceSession(home, o = {}) {
|
|
|
5995
6016
|
checkRoots();
|
|
5996
6017
|
const baselinePath = retirementBaselinePath(realHome);
|
|
5997
6018
|
let baseline;
|
|
5998
|
-
try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) {
|
|
6019
|
+
try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) {
|
|
6020
|
+
if (e.code === "ENOENT") throw missingSessionReceipt(realHome, baselinePath);
|
|
6021
|
+
throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`);
|
|
6022
|
+
}
|
|
5999
6023
|
if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== realHome || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
|
|
6000
6024
|
baseline.runtime = { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
|
|
6001
6025
|
writeJsonAtomic(baselinePath, baseline, 0o600);
|
|
@@ -7295,7 +7319,9 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
|
|
|
7295
7319
|
instance: name, agent: found.agent.name, root: resolve(root),
|
|
7296
7320
|
requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
|
|
7297
7321
|
// A confirmed plan's extra trees go with the intent, so the completion is bound by them as well.
|
|
7298
|
-
options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {})
|
|
7322
|
+
options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}),
|
|
7323
|
+
// The recorded children as they were when the retirement was scheduled: the completion stops them first.
|
|
7324
|
+
...(Array.isArray(o.children) ? { children: o.children.map((c) => ({ instance: c.instance, home: c.home })) } : {}) }, resultPath,
|
|
7299
7325
|
};
|
|
7300
7326
|
const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
|
|
7301
7327
|
for (const k of CORE_LAUNCH_ENV) delete env[k];
|
|
@@ -7374,10 +7400,11 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
|
7374
7400
|
result = retireInstance(intent.root, intent.instance, {
|
|
7375
7401
|
home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
|
|
7376
7402
|
...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
|
|
7403
|
+
...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
|
|
7377
7404
|
...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
|
|
7378
7405
|
});
|
|
7379
7406
|
} catch (e) {
|
|
7380
|
-
record({ ok: false, error: { code: e.code, message: e.message }, ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
|
|
7407
|
+
record({ ok: false, error: { code: e.code, message: e.message }, ...(e.details?.childrenStopped ? { childrenStopped: e.details.childrenStopped } : {}), ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
|
|
7381
7408
|
console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
|
|
7382
7409
|
return false;
|
|
7383
7410
|
}
|
|
@@ -7555,6 +7582,19 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7555
7582
|
throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
|
|
7556
7583
|
}
|
|
7557
7584
|
}
|
|
7585
|
+
// The plan's promise about recorded children (`o.children`, computed the way
|
|
7586
|
+
// the plan computes them): stopped first and kept, after every refusal above
|
|
7587
|
+
// that changes nothing and before this instance is quiesced. One still running,
|
|
7588
|
+
// or whose stop could not be established, refuses the retirement: nothing is
|
|
7589
|
+
// retired, nothing is escalated, and --force does not bypass it. A child whose
|
|
7590
|
+
// instance.json is gone by now (a --self snapshot's child retired in between)
|
|
7591
|
+
// is no longer an instance, and the plan would not list it: it is not stopped.
|
|
7592
|
+
let childrenStopped;
|
|
7593
|
+
if (Array.isArray(o.children)) {
|
|
7594
|
+
childrenStopped = stopRecordedChildren(o.children.filter((kid) => existsSync(join(kid.home, "instance.json"))));
|
|
7595
|
+
const running = childrenStopped.filter((k) => !k.ok);
|
|
7596
|
+
if (running.length) throw Object.assign(oatsError("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`), { details: { childrenStopped } });
|
|
7597
|
+
}
|
|
7558
7598
|
// `=` forces exact matching: tmux targets otherwise PREFIX-match window names.
|
|
7559
7599
|
// A no-launch instance is already quiesced. A launched one must have exact
|
|
7560
7600
|
// window absence established before recovery copying begins.
|
|
@@ -7953,7 +7993,7 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7953
7993
|
rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
|
|
7954
7994
|
}
|
|
7955
7995
|
|
|
7956
|
-
const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
|
|
7996
|
+
const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
|
|
7957
7997
|
const w = [...(hookResults?.warnings || [])];
|
|
7958
7998
|
if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
|
|
7959
7999
|
if (isCapturedHome(meta) && !quarantine) {
|
package/lib/teams-verbs.mjs
CHANGED
|
@@ -8,12 +8,14 @@
|
|
|
8
8
|
* `souls:`, edited by a PR to that file: `oats soul teams` only reads them.
|
|
9
9
|
*/
|
|
10
10
|
import { readFileSync } from "node:fs";
|
|
11
|
+
import { join } from "node:path";
|
|
11
12
|
import YAML from "yaml";
|
|
12
13
|
import { parseConfigData } from "./config-data.mjs";
|
|
13
14
|
import { oatsError } from "./errors.mjs";
|
|
14
15
|
import { teamLabelProblem, validateLocal } from "./workspace.mjs";
|
|
15
16
|
import { TEAM_ID_RE, localTeamsClosed, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
|
|
16
17
|
import { writeFileAtomic } from "./packages.mjs";
|
|
18
|
+
import { withDirLock } from "./dir-lock.mjs";
|
|
17
19
|
|
|
18
20
|
export const TEAMS_API = 2, SOUL_TEAMS_API = 2;
|
|
19
21
|
const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
@@ -99,8 +101,19 @@ function applyState(doc, before, next) {
|
|
|
99
101
|
* `verb` names the command and `writes` the keys it adds, for the refusal where the workspace does not
|
|
100
102
|
* allow local teams (local-teams-closed); a verb that only takes local teams away (`writes: null`) runs
|
|
101
103
|
* there too, since it moves the file toward what the workspace allows. → { changed, local } (the value now).
|
|
104
|
+
* The whole read-compare-write runs under the deployment's local lock (localLock), so among `oats teams`
|
|
105
|
+
* writers the compare and the rename are one step: a conditional write sees every earlier one.
|
|
102
106
|
*/
|
|
103
107
|
function editLocal(ctx, { verb, writes }, mutate) {
|
|
108
|
+
const lock = localLock(ctx);
|
|
109
|
+
return withDirLock(lock, `${verb} on ${ctx.localPath}`, () => editLocalLocked(ctx, { verb, writes }, mutate), {
|
|
110
|
+
retryMs: 5000,
|
|
111
|
+
busy: (why) => fail("E_LOCAL_BUSY", `${ctx.localPath} is being edited by another oats process (the lock ${lock}: ${why}); if no oats teams command is running, remove ${lock} and retry; nothing was written`, { path: ctx.localPath, lock }),
|
|
112
|
+
});
|
|
113
|
+
}
|
|
114
|
+
/** The lock every `oats teams` mutation holds: in the deployment's kernel state tree, never beside the files. */
|
|
115
|
+
const localLock = (ctx) => join(ctx.deployment, ".agents", "locks", "local.lock");
|
|
116
|
+
function editLocalLocked(ctx, { verb, writes }, mutate) {
|
|
104
117
|
for (let attempt = 0; attempt < 5; attempt++) {
|
|
105
118
|
const { text, doc, local: current } = readLocal(ctx);
|
|
106
119
|
const model = modelOf(ctx, current);
|
|
@@ -128,20 +141,25 @@ const assertLabel = (label) => {
|
|
|
128
141
|
if (problem) throw fail("E_BAD_ARGS", `not a team label (lowercase letters, digits, and . _ - after the first; at most 64 characters): ${problem}`, { label });
|
|
129
142
|
};
|
|
130
143
|
|
|
131
|
-
/** `oats teams add <label> --team <id> [--description <d>]` → { changed, local }.
|
|
132
|
-
|
|
144
|
+
/** `oats teams add <label> --team <id> [--description <d>] [--no-default]` → { changed, local, reused? }.
|
|
145
|
+
* `noDefault`: the mapping only, `defaultTeam` never touched; a mapping already there with the same label
|
|
146
|
+
* and team id (local or shared; the description is not compared) is reuse → { changed: false, reused: true }. */
|
|
147
|
+
export function teamsAdd(ctx, label, { team, description, noDefault = false } = {}) {
|
|
133
148
|
assertLabel(label);
|
|
134
149
|
if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
|
|
135
150
|
if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
|
|
136
|
-
|
|
151
|
+
let reused = false;
|
|
152
|
+
const result = editLocal(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
|
|
137
153
|
if (model.labels.has(label)) {
|
|
138
|
-
const from = model.labels.get(label)
|
|
139
|
-
|
|
154
|
+
const { from, team: existing } = model.labels.get(label);
|
|
155
|
+
if (noDefault && existing === team.trim()) { reused = true; return; }
|
|
156
|
+
throw fail("E_TEAM_EXISTS", `team ${label} is already declared (${from === "shared" ? "shared, in oats-workspace.yaml" : "local, in oats-local.yaml"})${from === "local" ? ": remove it first (`oats teams remove`) to redefine it" : ""}`, { label, from, observed: { label, team: existing, from } });
|
|
140
157
|
}
|
|
141
158
|
s.teams[label] = { team: team.trim(), ...(typeof description === "string" && description ? { description } : {}) };
|
|
142
|
-
// The first team added becomes the deployment's default.
|
|
143
|
-
if (s.defaultTeam === null) s.defaultTeam = label;
|
|
159
|
+
// The first team added becomes the deployment's default (unless --no-default).
|
|
160
|
+
if (s.defaultTeam === null && !noDefault) s.defaultTeam = label;
|
|
144
161
|
});
|
|
162
|
+
return reused ? { ...result, reused } : result;
|
|
145
163
|
}
|
|
146
164
|
|
|
147
165
|
/** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). Allowed where the workspace
|
|
@@ -160,10 +178,23 @@ export function teamsRemove(ctx, label) {
|
|
|
160
178
|
});
|
|
161
179
|
}
|
|
162
180
|
|
|
163
|
-
/**
|
|
164
|
-
|
|
181
|
+
/** Refuse unless the effective default (the `defaultTeam` of `oats teams --json`) is what the caller
|
|
182
|
+
* expects: none (`ifAbsent`), or the label `expect`. Soul defaults are not the deployment's and not looked at. */
|
|
183
|
+
function assertDefaultPrecondition(model, { ifAbsent, expect }) {
|
|
184
|
+
const observed = deploymentDefault(model);
|
|
185
|
+
if (ifAbsent ? observed === null : observed?.label === expect) return;
|
|
186
|
+
const now = observed === null ? "there is no default team" : `the default team is ${observed.label} (${observed.from === "deployment" ? "the deployment's, in oats-local.yaml" : "the workspace's, from oats-workspace.yaml"})`;
|
|
187
|
+
const wanted = ifAbsent ? "--if-absent sets it only where there is none" : `--expect ${expect} sets it only where the default is ${expect}`;
|
|
188
|
+
throw fail("E_TEAM_DEFAULT_MISMATCH", `${now}: ${wanted}; nothing was written`, { expected: ifAbsent ? { absent: true } : { label: expect }, observed });
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** `oats teams default <label> [--if-absent | --expect <label0>]`: a label of either file. The condition is
|
|
192
|
+
* judged inside the edit, on the file as it is now (and again on every retry), after today's refusals. */
|
|
193
|
+
export function teamsDefault(ctx, label, { ifAbsent = false, expect } = {}) {
|
|
194
|
+
if (ifAbsent && expect !== undefined) throw fail("E_BAD_ARGS", "oats teams default takes --if-absent or --expect <label>, not both", { label });
|
|
165
195
|
return editLocal(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
|
|
166
196
|
if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
|
|
197
|
+
if (ifAbsent || expect !== undefined) assertDefaultPrecondition(model, { ifAbsent, expect });
|
|
167
198
|
s.defaultTeam = label;
|
|
168
199
|
});
|
|
169
200
|
}
|
package/package-catalog.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.23.2",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
"oats.engineering": {
|
|
30
30
|
"url": "https://github.com/awebai/oats-engineering.git",
|
|
31
|
-
"ref": "v1.
|
|
31
|
+
"ref": "v1.9.0",
|
|
32
32
|
"path": "oats-package"
|
|
33
33
|
},
|
|
34
34
|
"oats.cloning": {
|
|
@@ -36,9 +36,14 @@
|
|
|
36
36
|
"ref": "v1.0.1",
|
|
37
37
|
"path": "oats-package"
|
|
38
38
|
},
|
|
39
|
+
"oats.apps": {
|
|
40
|
+
"url": "https://github.com/awebai/oats-apps.git",
|
|
41
|
+
"ref": "v1.0.0",
|
|
42
|
+
"path": "oats-package"
|
|
43
|
+
},
|
|
39
44
|
"oats.framework": {
|
|
40
45
|
"url": "https://github.com/awebai/oats.git",
|
|
41
|
-
"ref": "oats-framework/v1.
|
|
46
|
+
"ref": "oats-framework/v1.8.0",
|
|
42
47
|
"path": "oats-package"
|
|
43
48
|
}
|
|
44
49
|
},
|
|
@@ -71,6 +76,8 @@
|
|
|
71
76
|
"oats.engineering-expert": "oats.engineering",
|
|
72
77
|
"oats.developer": "oats.engineering",
|
|
73
78
|
"oats.code-review": "oats.engineering",
|
|
74
|
-
"oats.maintainer": "oats.engineering"
|
|
79
|
+
"oats.maintainer": "oats.engineering",
|
|
80
|
+
"oats.folio": "oats.apps",
|
|
81
|
+
"oats.library": "oats.apps"
|
|
75
82
|
}
|
|
76
83
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.48.0",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -60,7 +60,7 @@ members:
|
|
|
60
60
|
- git:github.com/acme/agents # the host is a member too
|
|
61
61
|
- git:github.com/acme/platform
|
|
62
62
|
packages:
|
|
63
|
-
oats.framework: v1.
|
|
63
|
+
oats.framework: v1.8.0 # bare versions resolve through the official catalog
|
|
64
64
|
oats.okf: v4.1.1
|
|
65
65
|
defaults:
|
|
66
66
|
capabilities: { oats.core: { from: package } }
|