@awebai/oats 0.66.0 → 0.68.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 +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/** Read-only package-upgrade state shared by the upgrade act and session starts.
|
|
2
|
+
* Kept independent of core.mjs so checking a receipt never loads the lifecycle act. */
|
|
3
|
+
import { lstatSync, readdirSync } from "node:fs";
|
|
4
|
+
import { basename, join } from "node:path";
|
|
5
|
+
import { oatsError } from "./errors.mjs";
|
|
6
|
+
import { shellWord } from "./shell-word.mjs";
|
|
7
|
+
import { driftOf } from "./materialize.mjs";
|
|
8
|
+
import { parseStrictJson } from "./canonical-json.mjs";
|
|
9
|
+
import { readPortableBytes } from "./bounded-read.mjs";
|
|
10
|
+
import { canonicalHomePath } from "./real-path.mjs";
|
|
11
|
+
|
|
12
|
+
export const UPGRADE_RECEIPT_NAME_RE = /^upgrade-receipt\.[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\.json$/;
|
|
13
|
+
const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
14
|
+
const uncertainReceipt = (home, path) => Object.assign(oatsError("E_UPGRADE_PARTIAL", `cannot safely read package-upgrade receipt state at ${path}; cannot prove a session launch is safe. Inspect the receipt and retry its recorded upgrade command, or respawn the instance; nothing was stopped or started`), { details: { home, receipt: path } });
|
|
15
|
+
|
|
16
|
+
/** Read receipt state without following directory or receipt symlinks. A corrupt record cannot
|
|
17
|
+
* prove that provider adoption finished, so every reader refuses before lifecycle effects. */
|
|
18
|
+
export function readUpgradeReceipts(home) {
|
|
19
|
+
const directory = join(home, ".oats");
|
|
20
|
+
let before;
|
|
21
|
+
try { before = lstatSync(directory); }
|
|
22
|
+
catch (error) { if (error.code === "ENOENT") return []; throw uncertainReceipt(home, directory); }
|
|
23
|
+
if (!before.isDirectory()) throw uncertainReceipt(home, directory);
|
|
24
|
+
let names;
|
|
25
|
+
try { names = readdirSync(directory); }
|
|
26
|
+
catch { throw uncertainReceipt(home, directory); }
|
|
27
|
+
const rows = [];
|
|
28
|
+
for (const name of names.sort()) {
|
|
29
|
+
if (!UPGRADE_RECEIPT_NAME_RE.test(name)) continue;
|
|
30
|
+
const path = join(directory, name);
|
|
31
|
+
try {
|
|
32
|
+
const receipt = parseStrictJson(readPortableBytes(path));
|
|
33
|
+
const key = name.slice("upgrade-receipt.".length, -".json".length);
|
|
34
|
+
if (!object(receipt) || receipt.action !== "upgrade" || !["partial", "complete"].includes(receipt.status) || receipt.idempotencyKey !== key
|
|
35
|
+
|| (receipt.steps !== undefined && !object(receipt.steps))
|
|
36
|
+
|| ((receipt.status === "partial" || receipt.steps?.cleaned === false) && (typeof receipt.planRevision !== "string" || !receipt.planRevision.trim()))) throw new Error("invalid upgrade receipt");
|
|
37
|
+
rows.push({ path, receipt });
|
|
38
|
+
} catch { throw uncertainReceipt(home, path); }
|
|
39
|
+
}
|
|
40
|
+
try {
|
|
41
|
+
const after = lstatSync(directory);
|
|
42
|
+
if (!after.isDirectory() || after.dev !== before.dev || after.ino !== before.ino) throw new Error("receipt directory changed");
|
|
43
|
+
} catch { throw uncertainReceipt(home, directory); }
|
|
44
|
+
return rows;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function retryFor(home, receipt) {
|
|
48
|
+
const instance = typeof receipt.instance === "string" && receipt.instance ? receipt.instance : basename(home);
|
|
49
|
+
return { instance, command: `oats instance upgrade ${shellWord(instance)}${receipt.undo === true ? " --undo" : ""} --plan-revision ${shellWord(receipt.planRevision)} --idempotency-key ${shellWord(receipt.idempotencyKey)}` };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The shared start mutex is a directory for starts and a regular file for upgrades.
|
|
53
|
+
* A start never reclaims an upgrade file, even if its owner died during the initial write. */
|
|
54
|
+
export function upgradeMutexRetry(home) {
|
|
55
|
+
const path = join(home, ".oats-start.lock");
|
|
56
|
+
try { if (!lstatSync(path).isFile()) return null; }
|
|
57
|
+
catch { return null; }
|
|
58
|
+
try {
|
|
59
|
+
const owner = parseStrictJson(readPortableBytes(path));
|
|
60
|
+
if (object(owner) && owner.action === "upgrade" && owner.instance === basename(home)
|
|
61
|
+
&& typeof owner.home === "string" && canonicalHomePath(owner.home) === canonicalHomePath(home)
|
|
62
|
+
&& typeof owner.planRevision === "string" && owner.planRevision.trim()
|
|
63
|
+
&& typeof owner.idempotencyKey === "string" && UPGRADE_RECEIPT_NAME_RE.test(`upgrade-receipt.${owner.idempotencyKey}.json`)
|
|
64
|
+
&& (owner.undo === undefined || typeof owner.undo === "boolean")) return retryFor(home, owner).command;
|
|
65
|
+
} catch { /* An empty or incomplete write still belongs to the upgrade act. */ }
|
|
66
|
+
return `${retryFor(home, { planRevision: "<original-plan-revision>", idempotencyKey: "<original-idempotency-key>" }).command} (use the original revision and key, and include --undo if originally used)`;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** A provider may already have adopted host state. A partial upgrade must finish forward
|
|
70
|
+
* before any launch hook or harness runs against the home's module copies. */
|
|
71
|
+
export function assertNoPartialUpgrade(home) {
|
|
72
|
+
for (const { path, receipt } of readUpgradeReceipts(home)) {
|
|
73
|
+
if (receipt.status !== "partial") continue;
|
|
74
|
+
const { instance, command } = retryFor(home, receipt);
|
|
75
|
+
throw Object.assign(oatsError("E_UPGRADE_PARTIAL", `the package upgrade of ${instance} is partial (${path}); nothing was stopped or started. Retry ${command} to finish it; if it cannot finish, respawn the instance`), {
|
|
76
|
+
details: { home, receipt: path, instance, idempotencyKey: receipt.idempotencyKey },
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Swap and baseline already committed: launch is safe while event/cleanup finalization is retried. */
|
|
82
|
+
export function upgradeCleanupWarnings(home) {
|
|
83
|
+
return readUpgradeReceipts(home)
|
|
84
|
+
.filter(({ receipt }) => receipt.status === "complete" && receipt.steps?.cleaned === false)
|
|
85
|
+
.map(({ path, receipt }) => {
|
|
86
|
+
const { instance, command } = retryFor(home, receipt);
|
|
87
|
+
return `the package upgrade of ${instance} is complete, but staging cleanup remains (${path}); retry ${command} to finish cleanup`;
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Only package modules that can move to a different locked commit. Removed packages
|
|
92
|
+
* and member drift remain information for status; neither is offered as an upgrade. */
|
|
93
|
+
export function packageUpgradeDrift(meta, { lock } = {}) {
|
|
94
|
+
return driftOf(meta, null, { lock })
|
|
95
|
+
.filter((row) => row.from.kind === "package" && row.status === "moved")
|
|
96
|
+
.map((row) => ({
|
|
97
|
+
capability: row.module,
|
|
98
|
+
recorded: { version: row.recorded.version ?? null, commit: row.recorded.commit ?? null },
|
|
99
|
+
locked: { version: row.current.version ?? null, commit: row.current.commit ?? null },
|
|
100
|
+
}));
|
|
101
|
+
}
|
package/lib/workspace.mjs
CHANGED
|
@@ -552,6 +552,9 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
|
|
|
552
552
|
|
|
553
553
|
/* ───────────────────────────── enumeration ────────────────────────────── */
|
|
554
554
|
|
|
555
|
+
/** The conventional directory shared by discovery and reads at a recorded soul commit. */
|
|
556
|
+
export const memberSoulPath = (name) => `souls/${name}`;
|
|
557
|
+
|
|
555
558
|
const SOUL_FILE = /^([^/]+)\/soul\.yaml$/;
|
|
556
559
|
const CAP_FILE = /^([^/]+)\/oats\.json$/;
|
|
557
560
|
|
|
@@ -580,7 +583,7 @@ async function enumerateRepo(remote, ref, key, commit) {
|
|
|
580
583
|
for (const entry of await list("souls")) {
|
|
581
584
|
const m = entry.type === "blob" && SOUL_FILE.exec(entry.path);
|
|
582
585
|
if (!m) continue;
|
|
583
|
-
const path =
|
|
586
|
+
const path = memberSoulPath(m[1]);
|
|
584
587
|
const file = `${path}/soul.yaml`;
|
|
585
588
|
let bytes;
|
|
586
589
|
try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }
|
package/lib/worktree.mjs
CHANGED
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
* is passed after `--end-of-options` where the git subcommand honours it. The
|
|
20
20
|
* remote URL is recorded, printed and handed to hooks without userinfo (A2). */
|
|
21
21
|
import { execFileSync, spawn as spawnChild, spawnSync } from "node:child_process";
|
|
22
|
-
import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
|
|
22
|
+
import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
|
|
23
|
+
import { tmpdir } from "node:os";
|
|
23
24
|
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
24
25
|
import { checkHolderByHand, ifItDoesNotEnd, lifecycleBusy, nothingAfter, oatsError, OWN_START_REMEDY } from "./errors.mjs";
|
|
25
26
|
import { appendEvent } from "./instance-events.mjs";
|
|
@@ -53,8 +54,8 @@ export function worktreeFetchTimeoutMs(env = process.env) {
|
|
|
53
54
|
/** The git environment of every step: the invoker's, never prompting for credentials. */
|
|
54
55
|
const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: "0" });
|
|
55
56
|
/** Run git → { ok, out, err, status }. Never a shell. */
|
|
56
|
-
function git(argv, { timeout = 120_000 } = {}) {
|
|
57
|
-
const r = spawnSync("git", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: gitEnv(), timeout, maxBuffer: 64 * 1024 * 1024 });
|
|
57
|
+
function git(argv, { timeout = 120_000, env = {}, input } = {}) {
|
|
58
|
+
const r = spawnSync("git", argv, { encoding: "utf8", stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, env: { ...gitEnv(), ...env }, timeout, maxBuffer: 64 * 1024 * 1024 });
|
|
58
59
|
return { ok: r.status === 0 && !r.error, out: String(r.stdout ?? ""), err: String(r.stderr ?? "").trim() || r.error?.message || "", status: r.status };
|
|
59
60
|
}
|
|
60
61
|
/** Run a git step that changes something (a tree, a ref, the worktree list) as a recorded child:
|
|
@@ -607,6 +608,73 @@ export async function worktreeAdd(homeArg, o = {}) {
|
|
|
607
608
|
|
|
608
609
|
// ---------- remove ----------
|
|
609
610
|
|
|
611
|
+
const manualResidueRemedy = (tree, purpose) => `save any work and remove ${tree} by hand, then run \`oats worktree remove --purpose ${purpose}\` to drop its record`;
|
|
612
|
+
|
|
613
|
+
/** Git removes its admin entry even when deleting ignored output fails. A later remove
|
|
614
|
+
* has no index to ask: compare the surviving files with the recorded branch in a private
|
|
615
|
+
* index, never the clone's index. Missing files are expected after partial deletion. */
|
|
616
|
+
function checkRemovalResidue(clone, tree, rec, refuse) {
|
|
617
|
+
const dotgit = join(tree, ".git");
|
|
618
|
+
let missingGitdir = false;
|
|
619
|
+
try {
|
|
620
|
+
if (lstatSync(dotgit).isFile()) {
|
|
621
|
+
const match = /^gitdir: (.+)\r?\n?$/.exec(readFileSync(dotgit, "utf8"));
|
|
622
|
+
if (match) {
|
|
623
|
+
try { lstatSync(resolve(tree, match[1])); }
|
|
624
|
+
catch (e) { if (e.code === "ENOENT") missingGitdir = true; else throw e; }
|
|
625
|
+
}
|
|
626
|
+
}
|
|
627
|
+
} catch (e) { throw refuse(`the unregistered tree's .git file could not be checked (${e.message}); ${manualResidueRemedy(tree, rec.purpose)}`); }
|
|
628
|
+
if (!missingGitdir) throw refuse(`the unregistered tree has no .git file pointing at a missing gitdir; ${manualResidueRemedy(tree, rec.purpose)}`);
|
|
629
|
+
|
|
630
|
+
const scratch = mkdtempSync(join(tmpdir(), "oats-worktree-remove-"));
|
|
631
|
+
try {
|
|
632
|
+
const env = { GIT_INDEX_FILE: join(scratch, "index") };
|
|
633
|
+
const args = ["-C", clone, "--work-tree", tree];
|
|
634
|
+
const read = git([...args, "read-tree", `refs/heads/${rec.branch}`], { env });
|
|
635
|
+
if (!read.ok) throw refuse(`the recorded branch ${rec.branch} could not be read (${firstLine(read.err)})`);
|
|
636
|
+
// read-tree has no stat cache. Refresh it before diff-files so identical survivors
|
|
637
|
+
// are compared by content; a refresh reporting differences is expected, not a failure.
|
|
638
|
+
const refresh = git([...args, "update-index", "--really-refresh", "--ignore-missing"], { env });
|
|
639
|
+
if (!refresh.ok && refresh.status !== 1) throw refuse(`the surviving files could not be checked (${firstLine(refresh.err)})`);
|
|
640
|
+
const diff = git([...args, "diff-files", "--name-only", "--diff-filter=d", "--ignore-submodules=none", "-z"], { env });
|
|
641
|
+
const deleted = git([...args, "diff-files", "--name-only", "--diff-filter=D", "--ignore-submodules=none", "-z"], { env });
|
|
642
|
+
if (!diff.ok || !deleted.ok) throw refuse(`the surviving files could not be checked (${firstLine(diff.err || deleted.err)})`);
|
|
643
|
+
// Partial deletion can remove .gitignore before its ignored output. Git reads
|
|
644
|
+
// absent per-directory ignore files from the index only with skip-worktree set.
|
|
645
|
+
// Mark deletions after checking modifications, in this private index alone.
|
|
646
|
+
if (deleted.out) {
|
|
647
|
+
const skip = git([...args, "update-index", "--skip-worktree", "-z", "--stdin"], { env, input: deleted.out });
|
|
648
|
+
if (!skip.ok) throw refuse(`the deleted ignore rules could not be read from the temporary index (${firstLine(skip.err)})`);
|
|
649
|
+
}
|
|
650
|
+
const others = git([...args, "ls-files", "--others", "--exclude-standard", "-z"], { env });
|
|
651
|
+
if (!others.ok) throw refuse(`the surviving files could not be checked (${firstLine(others.err)})`);
|
|
652
|
+
const paths = [...new Set([...diff.out.split("\0"), ...others.out.split("\0")].filter(Boolean))];
|
|
653
|
+
if (paths.length) {
|
|
654
|
+
const changed = paths.map((p) => JSON.stringify(p)).join(", ");
|
|
655
|
+
throw Object.assign(oatsError("E_WORKTREE_DIRTY", `the unregistered tree ${tree} has modified or untracked work: ${changed}; save its changes, or discard them, then retry (the record is kept)`), { details: { purpose: rec.purpose, path: tree, git: changed } });
|
|
656
|
+
}
|
|
657
|
+
} finally { rmSync(scratch, { recursive: true, force: true }); }
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
/** Only after Git's clean check, or the retry's branch comparison. lstat and skipping
|
|
661
|
+
* symlinks keep permission changes inside the tree; rm never follows their targets. */
|
|
662
|
+
function removeWritableResidue(tree) {
|
|
663
|
+
const makeWritable = (path) => {
|
|
664
|
+
const st = lstatSync(path);
|
|
665
|
+
if (st.isSymbolicLink()) return;
|
|
666
|
+
chmodSync(path, st.mode | (st.isDirectory() ? 0o700 : 0o200));
|
|
667
|
+
if (st.isDirectory()) for (const name of readdirSync(path)) makeWritable(join(path, name));
|
|
668
|
+
};
|
|
669
|
+
if (!lstatSync(tree).isDirectory()) throw new Error("the recorded tree path is not a directory");
|
|
670
|
+
makeWritable(tree);
|
|
671
|
+
// Recursive rm can delete .git even when another entry fails. Keep the retry
|
|
672
|
+
// marker until every other entry is gone; the record stays until verification.
|
|
673
|
+
for (const name of readdirSync(tree)) if (name !== ".git") rmSync(join(tree, name), { recursive: true, force: true });
|
|
674
|
+
rmSync(join(tree, ".git"), { recursive: true, force: true });
|
|
675
|
+
rmdirSync(tree);
|
|
676
|
+
}
|
|
677
|
+
|
|
610
678
|
/** `oats worktree remove --purpose <p>`: `git worktree remove` (which refuses a dirty tree),
|
|
611
679
|
* the branch kept, no hook, the record dropped. A `creating` record whose adder is gone is
|
|
612
680
|
* rolled back instead. Only recorded trees: a hand-made one is git's to remove.
|
|
@@ -638,27 +706,50 @@ export async function worktreeRemove(homeArg, o = {}) {
|
|
|
638
706
|
return { purpose, path: tree, removed: true, rolledBack: true, branch: rec.branch, branchKept: rb.branchKept, ...(rb.branchKeptReason ? { branchKeptReason: rb.branchKeptReason } : {}), ...(warned.length ? { warnings: warned } : {}) };
|
|
639
707
|
}
|
|
640
708
|
const clone = rec.clone;
|
|
709
|
+
// existsSync follows links: a dangling link is still an entry we must not orphan.
|
|
710
|
+
const treePresent = () => lstatSync(tree, { throwIfNoEntry: false }) !== undefined;
|
|
641
711
|
// Who is attached, asked while the tree is there (a link through an alias resolves only then).
|
|
642
712
|
// The owner's lineage is read under the home's real path: the command may have been given a
|
|
643
713
|
// link to the home, whose name and parents are not the instance's.
|
|
644
714
|
const realHome = realpathOr(home);
|
|
645
|
-
const attached =
|
|
715
|
+
const attached = treePresent() ? attachedToTree(dirname(dirname(dirname(realHome))), basename(realHome), tree) : [];
|
|
646
716
|
const inUse = attached.filter((c) => c.session !== "stopped");
|
|
647
717
|
if (inUse.length) {
|
|
648
718
|
const seen = inUse.map((c) => `${c.instance} (${c.session === "running" ? "its session is running" : "whether its session is running could not be read"})`).join(", ");
|
|
649
719
|
const step = inUse.length === 1 ? `stop it (\`oats instance stop ${inUse[0].instance}\`) or retire it` : "stop each one (`oats instance stop <instance>`) or retire it";
|
|
650
720
|
throw Object.assign(oatsError("E_CHILDREN_RUNNING", `${tree} is the work of ${inUse.length === 1 ? "an attached instance" : "attached instances"}: ${seen}; nothing was removed (the record is kept). To remove the tree, ${step}, then remove again`), { details: { purpose, path: tree, children: inUse } });
|
|
651
721
|
}
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
722
|
+
let started = false;
|
|
723
|
+
const refuse = (reason, gitError) => Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `${tree}: ${reason}; ${started ? "Git may already have removed files or its registration; resolve the named problem, then retry to finish the removal" : "no files were removed by this command"} (the record is kept)`), { details: { purpose, path: tree, ...(gitError ? { git: gitError } : {}) } });
|
|
724
|
+
const registered = () => {
|
|
725
|
+
const list = git(["-C", clone, "worktree", "list", "--porcelain", "-z"]);
|
|
726
|
+
if (!list.ok) throw refuse(`the worktree registration could not be read (${firstLine(list.err)})`);
|
|
727
|
+
return worktreeFields(list.out, "worktree").map(realpathOr).includes(realpathOr(tree));
|
|
728
|
+
};
|
|
729
|
+
if (treePresent()) {
|
|
730
|
+
if (!lstatSync(tree).isDirectory()) throw refuse("the recorded tree path is not a directory");
|
|
731
|
+
if (!registered()) {
|
|
732
|
+
checkRemovalResidue(clone, tree, rec, refuse);
|
|
733
|
+
} else {
|
|
734
|
+
const status = git(["-C", tree, "status", "--porcelain", "--ignore-submodules=none"]);
|
|
735
|
+
started = true;
|
|
736
|
+
const r = await trackedGit(["-C", clone, "worktree", "remove", "--end-of-options", tree], { track });
|
|
737
|
+
if (!r.ok && registered()) {
|
|
738
|
+
if (status.ok && status.out.trim()) throw Object.assign(oatsError("E_WORKTREE_DIRTY", `git refused to remove ${tree}: ${firstLine(r.err)}; commit and push its changes, or discard them, then retry (the record is kept)`), { details: { purpose, path: tree, git: r.err } });
|
|
739
|
+
throw refuse(`git could not finish removing the tree (${firstLine(r.err)})`, r.err);
|
|
740
|
+
}
|
|
741
|
+
}
|
|
742
|
+
// An unregistered residue is safe only after the check above: Git passed its own
|
|
743
|
+
// clean check in this call, or the retry proved the surviving files against the branch.
|
|
744
|
+
if (treePresent()) {
|
|
745
|
+
started = true;
|
|
746
|
+
try { removeWritableResidue(tree); }
|
|
747
|
+
catch (e) { throw refuse(`its registration is gone but deleting the remaining files failed (${e.message})${lstatSync(join(tree, ".git"), { throwIfNoEntry: false }) ? "" : `; its .git marker is gone too; ${manualResidueRemedy(tree, purpose)}`}`); }
|
|
658
748
|
}
|
|
659
749
|
}
|
|
660
|
-
await trackedGit(["-C", clone, "worktree", "prune"], { track });
|
|
661
|
-
if (
|
|
750
|
+
const pruned = await trackedGit(["-C", clone, "worktree", "prune"], { track });
|
|
751
|
+
if (!pruned.ok) throw refuse(`git worktree prune failed (${firstLine(pruned.err)})`);
|
|
752
|
+
if (treePresent() || registered()) throw refuse("the tree is still present or registered after git worktree remove");
|
|
662
753
|
rmSync(recPath, { force: true });
|
|
663
754
|
// What the removal left each attached instance with (their sessions were stopped).
|
|
664
755
|
const warned = [...claimWarnings, ...attached.map((c) => `${c.instance}: its work was ${tree}, which was removed; its work link ${join(c.home, "work")} now points at a path that is gone`)];
|
package/package-catalog.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v5.
|
|
6
|
+
"ref": "v5.3.0",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.31.0",
|
|
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.11.0",
|
|
32
32
|
"path": "oats-package"
|
|
33
33
|
},
|
|
34
34
|
"oats.cloning": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"oats.framework": {
|
|
45
45
|
"url": "https://github.com/awebai/oats.git",
|
|
46
|
-
"ref": "oats-framework/v1.
|
|
46
|
+
"ref": "oats-framework/v1.14.1",
|
|
47
47
|
"path": "oats-package"
|
|
48
48
|
}
|
|
49
49
|
},
|
|
@@ -73,6 +73,7 @@
|
|
|
73
73
|
"oats.setup": "oats.framework",
|
|
74
74
|
"oats.okf-harvest": "oats.okf",
|
|
75
75
|
"oats.okf-maintenance": "oats.okf",
|
|
76
|
+
"oats.aweb-tasks": "oats.aweb",
|
|
76
77
|
"oats.engineering-expert": "oats.engineering",
|
|
77
78
|
"oats.developer": "oats.engineering",
|
|
78
79
|
"oats.code-review": "oats.engineering",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.68.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",
|
|
@@ -31,6 +31,8 @@ import { gitFileId, gitRevision, gitIndexRevision, gitObservation } from './inst
|
|
|
31
31
|
import { validMaxAge, maxAgeArgv } from './deployment-contract.mjs';
|
|
32
32
|
import { MACHINE_ID, machineFieldProblem } from './machine-contract.mjs';
|
|
33
33
|
import { kernelMade } from './kernel-made.mjs';
|
|
34
|
+
import { SOUL_COLORS } from './soul-colors.mjs';
|
|
35
|
+
import { NAMING_TIMEOUT_MS } from './spawn-preview-contract.mjs';
|
|
34
36
|
|
|
35
37
|
const ENVELOPE_TIMEOUT_MS = 60_000;
|
|
36
38
|
|
|
@@ -57,6 +59,9 @@ export function parseEnvelope(stdout) {
|
|
|
57
59
|
* silently degrade into different spawn behavior. */
|
|
58
60
|
const SPAWN_ARG_RULES = {
|
|
59
61
|
purpose: { flag: "--purpose", re: /^[a-z0-9][a-z0-9-]*$/i }, // instance-name slug
|
|
62
|
+
// The exact instance name (feature spawn-name): the kernel's instance-name grammar, lowercase,
|
|
63
|
+
// used as given; the kernel refuses the rest of its rule itself (E_INSTANCE_NAME_INVALID). Never with a purpose.
|
|
64
|
+
name: { flag: "--name", re: /^[a-z0-9][a-z0-9-]*$/ },
|
|
60
65
|
repo: { flag: "--repo", re: /^[^-][^\0]*$/ }, // path — anything not option-shaped
|
|
61
66
|
work: { flag: "--work", re: /^(worktree|checkout|attached|workspace|directory)$/ },
|
|
62
67
|
backend: { flag: "--backend", re: /^tmux$/ },
|
|
@@ -91,6 +96,13 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
|
|
|
91
96
|
: "--relative-to requires a relation (child|sibling|parent)");
|
|
92
97
|
e.code = "E_BAD_ARGS"; throw e;
|
|
93
98
|
}
|
|
99
|
+
// A name is the instance's whole name; a purpose is the part after `<soul>-`: one or the other.
|
|
100
|
+
const given = v => v !== undefined && v !== null && v !== "";
|
|
101
|
+
if (given(opts.name) && given(opts.purpose)) { const e = new Error("a spawn takes --name or --purpose, not both"); e.code = "E_BAD_ARGS"; throw e; }
|
|
102
|
+
// --suggest-name on an apply (feature spawn-apply-suggest-name): the machine that spawns names it from its task, so
|
|
103
|
+
// never beside a name or a purpose.
|
|
104
|
+
if (opts.suggestName !== undefined && typeof opts.suggestName !== "boolean") throw Object.assign(new Error("suggestName must be a boolean"), { code: "E_BAD_ARGS" });
|
|
105
|
+
if (opts.suggestName && (given(opts.name) || given(opts.purpose))) throw Object.assign(new Error("--suggest-name chooses the name: it takes no --name or --purpose"), { code: "E_BAD_ARGS" });
|
|
94
106
|
// relativeRoot rides along with the pair only — alone it is meaningless
|
|
95
107
|
if (!hasRef && opts.relativeRoot !== undefined && opts.relativeRoot !== null && opts.relativeRoot !== "") {
|
|
96
108
|
const e = new Error("--relative-root requires --relation and --relative-to");
|
|
@@ -112,6 +124,7 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
|
|
|
112
124
|
if (typeof opts.yolo !== "boolean") throw Object.assign(new Error("yolo must be a boolean"), { code: "E_BAD_ARGS" });
|
|
113
125
|
argv.push(opts.yolo ? "--yolo" : "--no-yolo");
|
|
114
126
|
}
|
|
127
|
+
if (opts.suggestName) argv.push("--suggest-name");
|
|
115
128
|
argv.push("--json");
|
|
116
129
|
return argv;
|
|
117
130
|
}
|
|
@@ -151,11 +164,19 @@ export function writeTaskFile(taskText, io = {}) {
|
|
|
151
164
|
* fixed list of options), so this home's own default for it is `execFileInSession`. Such a child is given no
|
|
152
165
|
* deadline (`timeout: 0`, the default of an apply): execFileInSession arms its kill only for a positive one,
|
|
153
166
|
* and the caller's own wait ends instead (cliStart's START_WAIT_MS; instance-lifecycle.mjs APPLY_WAIT_MS). */
|
|
154
|
-
|
|
167
|
+
/** What a kernel answer may print, bytes of stdout: every read but a soul inspection that carries its skills' text. */
|
|
168
|
+
export const ENVELOPE_MAX_BUFFER = 4 * 1024 * 1024;
|
|
169
|
+
/** A soul inspection with `--skills` and/or `--composed-skills`: their texts' budgets (1 MiB and 2 MiB of UTF-8,
|
|
170
|
+
* docs/desktop-cli-api.md) as JSON may print them, six bytes a byte (the kernel reads a control character as text,
|
|
171
|
+
* and JSON escapes it as `\u0001`): 18 MiB, beside the two AGENTS.md (200,000 characters each, sixfold too) and the
|
|
172
|
+
* rest of the answer, with room to spare. */
|
|
173
|
+
export const SKILLS_INSPECT_MAX_BUFFER = 32 * 1024 * 1024;
|
|
174
|
+
|
|
175
|
+
function runJson(bin, argv, { cwd, exec, timeout = ENVELOPE_TIMEOUT_MS, parse = parseEnvelope, strictExit = false, detached = false, maxBuffer = ENVELOPE_MAX_BUFFER } = {}) {
|
|
155
176
|
const run = exec ?? (detached ? execFileInSession : execFile);
|
|
156
177
|
return new Promise((resolveP, rejectP) => {
|
|
157
178
|
try {
|
|
158
|
-
run(bin, argv, { cwd, encoding: "utf8", timeout, maxBuffer
|
|
179
|
+
run(bin, argv, { cwd, encoding: "utf8", timeout, maxBuffer, shell: false, ...(detached ? { detached: true } : {}) },
|
|
159
180
|
(err, stdout) => {
|
|
160
181
|
// New reads require a clean exit for success. Keep the historical
|
|
161
182
|
// envelope-wins policy for existing mutations unless opted in.
|
|
@@ -283,7 +304,9 @@ export async function cliSpawn(bin, { agent, workspaceDir, task, ...opts }, io =
|
|
|
283
304
|
let wakeFile;
|
|
284
305
|
try {
|
|
285
306
|
if (wake) { wakeFile = writeTaskFile(JSON.stringify(wake), io); argv.push("--wake-file", wakeFile.file); }
|
|
286
|
-
|
|
307
|
+
// An apply that names its instance makes the kernel's naming call first: its deadline allows for it.
|
|
308
|
+
const timeout = io.timeout ?? (opts.suggestName ? ENVELOPE_TIMEOUT_MS + NAMING_TIMEOUT_MS : undefined);
|
|
309
|
+
return await runJson(bin, argv, { cwd: workspaceDir, exec: io.exec, timeout });
|
|
287
310
|
} finally { wakeFile?.cleanup(); cleanup(); }
|
|
288
311
|
}
|
|
289
312
|
|
|
@@ -616,9 +639,26 @@ export function operationArgs(args) {
|
|
|
616
639
|
if (entries.length > 8 || entries.some(([k, v]) => !/^[a-z][a-z0-9-]{0,63}$/.test(k) || typeof v !== 'string' || !v || v.length > 1024 || /[\x00-\x1f\x7f]/.test(v))) return null;
|
|
617
640
|
return entries.flatMap(([k, v]) => ['--arg', `${k}=${v}`]);
|
|
618
641
|
}
|
|
642
|
+
/** An instance's colour (feature instance-color, awebai/oats#1421 §2): `oats instance color <instance>
|
|
643
|
+
* (<color> | --clear) --home <home> (--dir <context> | --server <server>) --json`, addressed as `oats
|
|
644
|
+
* instance stop` is (lifecycle-cli.mjs: a routed command never carries --dir). `color` is a palette name
|
|
645
|
+
* (soul-colors.mjs SOUL_COLORS) or null to clear; anything else is refused here and nothing runs. A read's
|
|
646
|
+
* deadline: 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
|
|
647
|
+
export async function cliInstanceColor(bin, { instance, home, context, server, color }, io = {}) {
|
|
648
|
+
const fail = code => ({ schemaVersion: 1, ok: false, error: { code } });
|
|
649
|
+
if (typeof bin !== "string" || !isAbsolute(bin) || typeof instance !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(instance)
|
|
650
|
+
|| typeof home !== "string" || !isAbsolute(home) || home.includes("\0") || !(color === null || SOUL_COLORS.includes(color))
|
|
651
|
+
|| (server !== undefined ? !/^[a-z0-9][a-z0-9-]{0,63}$/.test(server ?? "") : typeof context !== "string" || !isAbsolute(context))) return fail("E_BAD_ARGS");
|
|
652
|
+
const argv = ["instance", "color", instance, ...(color === null ? ["--clear"] : [color]), "--home", home,
|
|
653
|
+
...(server !== undefined ? ["--server", server] : ["--dir", context]), "--json"];
|
|
654
|
+
const limit = server !== undefined ? 45_000 : 30_000;
|
|
655
|
+
return runJson(bin, argv, { cwd: server !== undefined ? io.cwd : context, exec: io.exec, strictExit: true,
|
|
656
|
+
timeout: Number.isFinite(io.timeout) && io.timeout > 0 ? Math.min(io.timeout, limit) : limit });
|
|
657
|
+
}
|
|
658
|
+
|
|
619
659
|
/** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
|
|
620
|
-
* gates the flags (also `instructions` and `
|
|
621
|
-
export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, features }, io = {}) {
|
|
660
|
+
* gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
|
|
661
|
+
export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, composedSkills = false, features }, io = {}) {
|
|
622
662
|
const bad = message => { throw Object.assign(new Error(message), { code: 'E_BAD_ARGS' }); };
|
|
623
663
|
const value = (v, label) => {
|
|
624
664
|
if (typeof v !== 'string' || !v || v.startsWith('-') || v.includes('\0')) bad(`Invalid ${label}`);
|
|
@@ -652,7 +692,13 @@ export async function cliCapability(bin, { action, context, server, soul, agents
|
|
|
652
692
|
// way; routed, the caller asks only for a host whose roster row names soul-skills (composed-gate.mjs hostReportsSkills).
|
|
653
693
|
if (skills && (action !== 'inspect' || !soul || home)) bad('Skills belong to a soul inspection');
|
|
654
694
|
const skillsArgv = skills && Array.isArray(features) && features.includes('soul-skills') ? ['--skills'] : [];
|
|
655
|
-
|
|
695
|
+
// --composed-skills (feature soul-composed-skills) adds every skill a spawn gives the instance (souls[0].composedSkills):
|
|
696
|
+
// inspect --soul only, gated the same way; routed, only for a host whose roster row names it (hostComposesSkills).
|
|
697
|
+
if (composedSkills && (action !== 'inspect' || !soul || home)) bad('Composed skills belong to a soul inspection');
|
|
698
|
+
const composedSkillsArgv = composedSkills && Array.isArray(features) && features.includes('soul-composed-skills') ? ['--composed-skills'] : [];
|
|
699
|
+
return await runJson(bin, [...argv, ...target, ...composed, ...skillsArgv, ...composedSkillsArgv, ...maxAgeArgv(features, maxAge), '--json'], {
|
|
656
700
|
cwd: localCwd, exec: io.exec, timeout: io.timeout ?? (action === 'run' ? 300_000 : ENVELOPE_TIMEOUT_MS),
|
|
701
|
+
// The skills' text makes the answer larger than any other read: an allowance of its own, still bounded.
|
|
702
|
+
maxBuffer: skillsArgv.length || composedSkillsArgv.length ? SKILLS_INSPECT_MAX_BUFFER : ENVELOPE_MAX_BUFFER,
|
|
657
703
|
});
|
|
658
704
|
}
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.69.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
|
|
|
52
52
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
53
53
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
54
54
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 69, 0] };
|
|
56
56
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
57
|
* rejection reason, the backend's /api status and the degradation card can
|
|
58
58
|
* never disagree with the numbers actually enforced above. */
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/** When a soul field the host composes or reports is asked for: the composed AGENTS.md (feature
|
|
2
|
-
* soul-composed-instructions, `inspect --soul --instructions`)
|
|
3
|
-
* `inspect --soul --skills`, `souls[0].skills`)
|
|
2
|
+
* soul-composed-instructions, `inspect --soul --instructions`), the soul's own skills (feature soul-skills,
|
|
3
|
+
* `inspect --soul --skills`, `souls[0].skills`) and every skill a spawn gives its instance (feature
|
|
4
|
+
* soul-composed-skills, `inspect --soul --composed-skills`, `souls[0].composedSkills`). The one gate module for all three, shared by the renderer (whether the
|
|
4
5
|
* soul page asks) and the server (whether the ask reaches the CLI); DOM-free so the server can import it.
|
|
5
6
|
*
|
|
6
7
|
* A local soul: this computer's CLI advertises the feature. A routed soul (`--server`): the host answers, so this
|
|
@@ -11,6 +12,7 @@
|
|
|
11
12
|
* (`E_REMOTE_INCOMPATIBLE`) and never by probing: the roster row is the answer. */
|
|
12
13
|
export const COMPOSED_FEATURE = 'soul-composed-instructions';
|
|
13
14
|
export const SKILLS_FEATURE = 'soul-skills';
|
|
15
|
+
export const COMPOSED_SKILLS_FEATURE = 'soul-composed-skills';
|
|
14
16
|
export const PROBE_FEATURES_FEATURE = 'server-probe-features';
|
|
15
17
|
|
|
16
18
|
const advertises = (cli, feature) => !!cli?.ok && Array.isArray(cli.features) && cli.features.includes(feature);
|
|
@@ -32,3 +34,9 @@ export const skillsSupported = cli => advertises(cli, SKILLS_FEATURE);
|
|
|
32
34
|
export const routedSkillsSupported = cli => skillsSupported(cli) && advertises(cli, PROBE_FEATURES_FEATURE);
|
|
33
35
|
/** A roster group's host reports a soul's skills: its last roster read succeeded and its own list names the feature. */
|
|
34
36
|
export const hostReportsSkills = (cli, group) => routedSkillsSupported(cli) && hostAdvertises(group, SKILLS_FEATURE);
|
|
37
|
+
/** This computer's CLI lists every skill a spawn of a soul gives its instance, capabilities' included. */
|
|
38
|
+
export const composedSkillsSupported = cli => advertises(cli, COMPOSED_SKILLS_FEATURE);
|
|
39
|
+
/** This computer's CLI can route the composed-skills request and relays the hosts' own feature lists in the roster. */
|
|
40
|
+
export const routedComposedSkillsSupported = cli => composedSkillsSupported(cli) && advertises(cli, PROBE_FEATURES_FEATURE);
|
|
41
|
+
/** A roster group's host lists composed skills: its last roster read succeeded and its own list names the feature. */
|
|
42
|
+
export const hostComposesSkills = (cli, group) => routedComposedSkillsSupported(cli) && hostAdvertises(group, COMPOSED_SKILLS_FEATURE);
|
|
@@ -9,6 +9,7 @@ import { launchOf, REPORT_FROM } from './launch-contract.mjs';
|
|
|
9
9
|
import { readIdentity } from './workspace-views.mjs';
|
|
10
10
|
import { waitingOnYouData } from './waiting-on-you.mjs';
|
|
11
11
|
import { retireData } from './retire-state.mjs';
|
|
12
|
+
import { instanceColor } from './instance-presentation.mjs';
|
|
12
13
|
const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
|
|
13
14
|
const absolute = value => text(value) && isAbsolute(value) && resolve(value) === value;
|
|
14
15
|
const own = (value, key) => Object.hasOwn(value, key);
|
|
@@ -214,6 +215,10 @@ export function deploymentStatusData(document, deployment) {
|
|
|
214
215
|
// check()ed: a value out of the contract is dropped and the row reads as if it had none.
|
|
215
216
|
if (own(instance, 'retire')) { const retire = retireData(instance.retire); if (retire) row.retire = retire; }
|
|
216
217
|
if (own(instance, 'rollbackIncomplete')) row.rollbackIncomplete = true;
|
|
218
|
+
// Feature instance-color: the instance's colour, a palette name exactly (instance-presentation.mjs
|
|
219
|
+
// instanceColor, the one rule of which colour a row shows). Validated, never check()ed: anything
|
|
220
|
+
// else is dropped and the row reads as one with no colour.
|
|
221
|
+
if (own(instance, 'color') && instanceColor(instance) !== null) row.color = instanceColor(instance);
|
|
217
222
|
// #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
|
|
218
223
|
// any other value is dropped, never checked: the row stays an ordinary one.
|
|
219
224
|
if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/** A deployment's workspace identity, read before a client serves it (#482): the `workspace` object of
|
|
2
|
+
* `oats status --dir <path> --json`, the read an observed deployment gets, so a deployment of this
|
|
3
|
+
* computer's list can be matched to its workspace (panel-views.mjs `listedViews`) before it is opened.
|
|
4
|
+
* One read, bounded as every deployment read is (deployment-read-cli.mjs: its time and size limits), and
|
|
5
|
+
* projected by the observer's own projection (deployment-data.mjs `deploymentStatusData`): nothing of the
|
|
6
|
+
* answer but its `workspace` object is kept. No retry and no cache: what the answers become is the
|
|
7
|
+
* caller's (`held.learned`, panel-views.mjs). */
|
|
8
|
+
import { cliDeploymentRead } from './deployment-read-cli.mjs';
|
|
9
|
+
import { deploymentStatusData } from './deployment-data.mjs';
|
|
10
|
+
import { deploymentFailure } from './deployment-contract.mjs';
|
|
11
|
+
|
|
12
|
+
/** Whether a kernel record (cli-locator.mjs) reports workspace identities at all: without the feature
|
|
13
|
+
* no read can match anything, and a client makes none. */
|
|
14
|
+
export const identityReadable = (cli) => cli?.ok === true && Array.isArray(cli.features) && cli.features.includes('workspace-identity');
|
|
15
|
+
|
|
16
|
+
/** The answer for a read its caller's total budget ended, or one that never began before it ended: timed
|
|
17
|
+
* out, as a read past its own time limit answers. */
|
|
18
|
+
export const identityTimedOut = () => deploymentFailure('E_CLI_TIMEOUT');
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Read the identity of deployment `path` (absolute, canonical: a row of this computer's list).
|
|
22
|
+
* `options.maxAge` rides on the read as it does on an observation's; `io` is cliDeploymentRead's
|
|
23
|
+
* (`exec`, `env`).
|
|
24
|
+
* @returns {Promise<{ ok: true, workspace: object | null } | { ok: false, reason: { code, message, origin? } }>}
|
|
25
|
+
* `workspace` is the projected `workspace` object (deployment-data.mjs: its reachability and, with
|
|
26
|
+
* feature workspace-identity, the identity fields, or `identityInvalid`), null when the kernel reported
|
|
27
|
+
* none; a failure is the reader's reason as it came, or the projection's code. Never rejected.
|
|
28
|
+
*/
|
|
29
|
+
export async function cliDeploymentIdentity(cli, path, options = {}, io = {}) {
|
|
30
|
+
let answer;
|
|
31
|
+
try {
|
|
32
|
+
answer = await cliDeploymentRead(cli, { action: 'status', context: path, ...(options.maxAge !== undefined ? { maxAge: options.maxAge } : {}) }, io);
|
|
33
|
+
} catch { return deploymentFailure('E_CLI_FAILED'); }
|
|
34
|
+
if (!answer?.ok) return answer?.reason ? { ok: false, reason: answer.reason } : deploymentFailure('E_CLI_PROTOCOL');
|
|
35
|
+
try {
|
|
36
|
+
return { ok: true, workspace: deploymentStatusData(answer.document, path).workspace ?? null };
|
|
37
|
+
} catch (error) {
|
|
38
|
+
return deploymentFailure(error?.code === 'E_DEPLOYMENT_SCOPE' ? 'E_DEPLOYMENT_SCOPE' : 'E_CLI_PROTOCOL');
|
|
39
|
+
}
|
|
40
|
+
}
|
|
@@ -12,13 +12,15 @@
|
|
|
12
12
|
* test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
|
|
13
13
|
import { dirname } from 'node:path';
|
|
14
14
|
import { livenessOrigin } from './liveness.mjs';
|
|
15
|
-
import { knownOrigin, hasRuntimeError, byRuntimeState } from './instance-presentation.mjs';
|
|
15
|
+
import { knownOrigin, hasRuntimeError, byRuntimeState, instanceColor } from './instance-presentation.mjs';
|
|
16
16
|
import { retireData } from './retire-state.mjs';
|
|
17
17
|
|
|
18
18
|
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
19
19
|
|
|
20
20
|
/** One row per instance of a roster (deployment-data.mjs `deploymentStatusData`): the kernel's row,
|
|
21
|
-
* with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster
|
|
21
|
+
* with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster, and `soulKey`, the
|
|
22
|
+
* agent row's soul key (`key`, feature launch-preference: a string, or null when no instance records a
|
|
23
|
+
* workspace soul), present only when the agent row has `key`.
|
|
22
24
|
* Needs input: a row keeps the kernel's `waitingOnYou` only when this CLI advertises waiting-on-you.
|
|
23
25
|
* Gate on the feature, never the version: a pre-feature kernel emitting the field is dropped. A row
|
|
24
26
|
* without the key stays without it. */
|
|
@@ -27,7 +29,7 @@ export function rosterRows(roster, cli) {
|
|
|
27
29
|
return roster.agents.flatMap((agent) => agent.instances.map(({ waitingOnYou, ...instance }) => ({
|
|
28
30
|
...instance, ...(waitingFeature && waitingOnYou !== undefined ? { waitingOnYou } : {}),
|
|
29
31
|
agent: instance.agent || agent.name, description: agent.description || "",
|
|
30
|
-
team: agent.team || null, agentsRoot: roster.root,
|
|
32
|
+
team: agent.team || null, agentsRoot: roster.root, ...(Object.hasOwn(agent, "key") ? { soulKey: agent.key } : {}),
|
|
31
33
|
})));
|
|
32
34
|
}
|
|
33
35
|
|
|
@@ -93,6 +95,8 @@ export function panelInstance(i) {
|
|
|
93
95
|
// present only when a provider reported one — never synthesized.
|
|
94
96
|
...(i.modules !== undefined ? { modules: i.modules } : {}),
|
|
95
97
|
...(i.soul !== undefined ? { soul: i.soul } : {}),
|
|
98
|
+
// The soul key the instance was spawned from (rosterRows), as the roster reported it: string or null; absent stays absent.
|
|
99
|
+
...(i.soulKey !== undefined ? { soulKey: i.soulKey } : {}),
|
|
96
100
|
...(i.identity !== undefined ? { identity: i.identity } : {}),
|
|
97
101
|
// desktop-facts: the last session start, where the model came from, the messaging identity's address.
|
|
98
102
|
...(i.startedAt !== undefined ? { startedAt: i.startedAt } : {}),
|
|
@@ -108,6 +112,8 @@ export function panelInstance(i) {
|
|
|
108
112
|
// Needs input (PR K): the validated claim (or null, unknown) as status reported it; absent stays absent.
|
|
109
113
|
// The client's liveness is merged before projection, so running/runtimeState beside it are the probe's.
|
|
110
114
|
...(i.waitingOnYou !== undefined ? { waitingOnYou: i.waitingOnYou } : {}),
|
|
115
|
+
// Feature instance-color: the row's colour as instanceColor reads it, present only when it is one.
|
|
116
|
+
...(instanceColor(i) !== null ? { color: instanceColor(i) } : {}),
|
|
111
117
|
team: i.team || null,
|
|
112
118
|
};
|
|
113
119
|
}
|