@awebai/oats 0.69.22 → 0.69.23
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 +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +878 -0
- package/docs/design/README.md +3 -0
- package/docs/desktop-cli-api.md +416 -72
- package/docs/desktop.md +60 -17
- package/docs/implementation.md +1 -1
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +117 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +51 -22
- package/docs/tui.md +4 -3
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +39 -2
- package/lib/core.mjs +25 -14
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-lifecycle.mjs +19 -15
- package/lib/instance-listing.mjs +18 -10
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +4 -1
- package/lib/servers.mjs +123 -13
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/deployment-data.mjs +4 -2
- package/packages/client/deployment-panel.mjs +2 -1
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +4 -3
- package/packages/client/workspace-cli.mjs +13 -2
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
package/bin/oats.mjs
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
* `init` / `use` / `install` / `restore` / `list` / `catalog` / `remove` /
|
|
20
20
|
* `migrate` / `trust` / `inject` are gone with the installed-capability tier.
|
|
21
21
|
*/
|
|
22
|
-
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
|
|
22
|
+
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
23
23
|
import { execFileSync, spawnSync } from "node:child_process";
|
|
24
24
|
import { constants as osConstants, homedir, tmpdir } from "node:os";
|
|
25
25
|
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
@@ -83,7 +83,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
|
|
|
83
83
|
const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
|
|
84
84
|
const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
|
|
85
85
|
const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
86
|
-
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin,
|
|
86
|
+
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceRelatedWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
87
87
|
const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
|
|
88
88
|
const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
89
89
|
const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
|
|
@@ -91,16 +91,17 @@ const { retireIncompleteProblems } = await kernelImport("retire-incomplete", ()
|
|
|
91
91
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
92
92
|
const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
|
|
93
93
|
const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
|
|
94
|
+
const { readBoardDetail, askBoardQuestion, clearBoardQuestion, setBoardFact, unsetBoardFact } = await kernelImport("instance-board", () => import("../lib/instance-board.mjs"));
|
|
94
95
|
const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
|
|
95
96
|
const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
|
|
96
97
|
const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
|
|
97
|
-
const { KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
|
|
98
|
+
const { BOARD_API, KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
|
|
98
99
|
const { inheritedContextRefusal } = await kernelImport("captured-context", () => import("../lib/captured-context.mjs"));
|
|
99
100
|
const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call", () => import("../lib/read-call.mjs"));
|
|
100
101
|
const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
|
|
101
102
|
const { memberLabel, memberRows, packageRows, standaloneCatalogVersion, standalonePackages, workspaceName, workspaceStatusAnswer, workspaceStatusView } = await kernelImport("workspace-read", () => import("../lib/workspace-read.mjs"));
|
|
102
103
|
const { expandInlineValues, flagValue } = await kernelImport("argv", () => import("../lib/argv.mjs"));
|
|
103
|
-
const { APPROVAL_REMOVED, NATIVE_RECORD_REFUSED, HOST_RUN_USAGE, RESUME_LOCAL_ONLY, RETIRE_USAGE, SOUL_LAUNCH_USAGE, SPAWN_USAGE, SYNC_USAGE, TEAMS_USAGE, WORKTREE_USAGE, commandArgvProblem, commandFlags } = await kernelImport("command-flags", () => import("../lib/command-flags.mjs"));
|
|
104
|
+
const { APPROVAL_REMOVED, NATIVE_RECORD_REFUSED, HOST_RUN_USAGE, RESUME_LOCAL_ONLY, RETIRE_USAGE, SOUL_LAUNCH_USAGE, SPAWN_USAGE, SYNC_USAGE, TEAMS_USAGE, WORKTREE_USAGE, BOARD_USAGE, commandArgvProblem, commandFlags, sameWorkDeprecation } = await kernelImport("command-flags", () => import("../lib/command-flags.mjs"));
|
|
104
105
|
|
|
105
106
|
const rawArgs = process.argv.slice(2);
|
|
106
107
|
const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
|
|
@@ -618,12 +619,17 @@ async function inspectCmd() {
|
|
|
618
619
|
// Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
|
|
619
620
|
const composedSkills = args.includes("--composed-skills");
|
|
620
621
|
if (composedSkills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--composed-skills lists the skills a spawn of a soul would give its instance: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
|
|
622
|
+
// Feature instance-board: opt-in, instance subject only; the board's facts with their history and its
|
|
623
|
+
// questions with their context (the rows carry neither).
|
|
624
|
+
const board = args.includes("--board");
|
|
625
|
+
if (board && flag("home") === undefined) return bail("E_BAD_ARGS", "--board reads an instance's board: it takes --home <abs>, not --soul (a soul has no board)");
|
|
621
626
|
let t = await workspaceTarget(bail, { command: "inspect" });
|
|
622
627
|
if (t) {
|
|
623
628
|
if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
|
|
624
629
|
if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
|
|
625
630
|
if (skills) t = await withSkills(t);
|
|
626
631
|
const doc = inspectDocument(t, { kernel: OATS_VERSION });
|
|
632
|
+
if (board && doc.instance) doc.instance = { ...doc.instance, board: readBoardDetail(t.home) };
|
|
627
633
|
if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
|
|
628
634
|
printWorkspaceInspect(doc); return;
|
|
629
635
|
}
|
|
@@ -672,6 +678,16 @@ function printWorkspaceInspect(doc) {
|
|
|
672
678
|
for (const c of doc.capabilities) console.log(` ${c.id}@${c.version || "?"} ${c.from?.kind === "package" ? `package ${c.from.package}` : c.from?.kind === "member" ? `member ${c.from.repoKey}` : ""}${c.operations.length ? ` ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
|
|
673
679
|
for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
|
|
674
680
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
681
|
+
const board = doc.instance?.board;
|
|
682
|
+
if (board !== undefined) {
|
|
683
|
+
// The agent's own text: every refused character spelled out, never interpreted (terminalText).
|
|
684
|
+
if (board === null) console.log("\nBoard: none");
|
|
685
|
+
else {
|
|
686
|
+
console.log(`\nBoard: ${board.facts.length} fact${board.facts.length === 1 ? "" : "s"}, ${board.questions.length} open question${board.questions.length === 1 ? "" : "s"}`);
|
|
687
|
+
for (const f of board.facts) console.log(terminalText(` ${f.key} ${f.label}: ${f.value}${f.unit ? ` ${f.unit}` : ""}${f.link ? ` ${f.link}` : ""} (${f.history.length} value${f.history.length === 1 ? "" : "s"}, updated ${f.at})`));
|
|
688
|
+
for (const q of board.questions) console.log(terminalText(` ${q.id} ${q.question} [${q.options.map((o, i) => `${i + 1}. ${o}`).join(" ")}] (asked ${q.since})`));
|
|
689
|
+
}
|
|
690
|
+
}
|
|
675
691
|
const composed = doc.souls[0].composedInstructions;
|
|
676
692
|
if (composed !== undefined) console.log(composed ? `\nComposed AGENTS.md (a spawn here, resolution ${composed.resolution ?? "?"}${composed.truncated ? ", truncated" : ""}):\n\n${composed.text}` : "\nComposed AGENTS.md: unavailable (see the problems above)");
|
|
677
693
|
const composedSkills = doc.souls[0].composedSkills;
|
|
@@ -1312,6 +1328,76 @@ function instanceWaitingCmd(sub, bail) {
|
|
|
1312
1328
|
} catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
|
|
1313
1329
|
}
|
|
1314
1330
|
|
|
1331
|
+
/** `oats instance board set|unset|ask` (feature instance-board, lib/instance-board.mjs): the agent's own
|
|
1332
|
+
* board, the facts it keeps in view for its person and the questions it asks them. Like `attention`, it
|
|
1333
|
+
* acts only on $OATS_INSTANCE_HOME (no --home, --dir or --server: lib/command-flags.mjs refuses them).
|
|
1334
|
+
* Display only: the kernel routes no answer. */
|
|
1335
|
+
function instanceBoardCmd(bail) {
|
|
1336
|
+
dropAmbientRoot();
|
|
1337
|
+
const verb = args[2];
|
|
1338
|
+
const usage = BOARD_USAGE;
|
|
1339
|
+
const forms = { set: ["label", "value", "unit", "link"], unset: [], ask: ["option", "id", "context-file", "clear"] };
|
|
1340
|
+
if (!Object.hasOwn(forms, verb)) return bail("E_BAD_ARGS", usage);
|
|
1341
|
+
// The form's words after the verb: its value flags (each once, but --option), and its operands. The
|
|
1342
|
+
// dispatch (commandArgvProblem) has refused an unknown flag and an argument too many.
|
|
1343
|
+
const values = new Map(), operands = [];
|
|
1344
|
+
for (let i = 3; i < args.length; i++) {
|
|
1345
|
+
const a = args[i];
|
|
1346
|
+
if (!a.startsWith("--")) { operands.push(a); continue; }
|
|
1347
|
+
const name = a.slice(2);
|
|
1348
|
+
if (name === "json") continue;
|
|
1349
|
+
if (!forms[verb].includes(name)) return bail("E_BAD_ARGS", `oats instance board ${verb}: unknown flag ${a}\n${usage}`);
|
|
1350
|
+
const v = args[i + 1];
|
|
1351
|
+
if (v === undefined || v.startsWith("--")) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
|
|
1352
|
+
if (values.has(name) && name !== "option") return bail("E_BAD_ARGS", `--${name} is given more than once; ${usage}`);
|
|
1353
|
+
values.set(name, [...(values.get(name) ?? []), v]);
|
|
1354
|
+
i++;
|
|
1355
|
+
}
|
|
1356
|
+
const one = (name) => values.get(name)?.[0];
|
|
1357
|
+
const home = process.env.OATS_INSTANCE_HOME;
|
|
1358
|
+
if (!home || !isAbsolute(home) || incarnationOf(home) === null) return bail("E_USAGE", `oats instance board runs inside an instance session: $OATS_INSTANCE_HOME is ${home ? `${home}, which is not an instance home (no readable instance.json)` : "unset"}`);
|
|
1359
|
+
const root = agentsRootOfHome(home);
|
|
1360
|
+
const { resolveInstance } = await_import_lifecycle();
|
|
1361
|
+
try { resolveInstance(dirFlag(), root, basename(home), { home }); }
|
|
1362
|
+
catch (e) { return bail("E_USAGE", `$OATS_INSTANCE_HOME (${home}) is not an instance home under ${root}: ${e.message}`); }
|
|
1363
|
+
const instance = basename(home);
|
|
1364
|
+
let r, line;
|
|
1365
|
+
try {
|
|
1366
|
+
if (verb === "set") {
|
|
1367
|
+
if (operands.length !== 1) return bail("E_BAD_ARGS", `oats instance board set takes one key; ${usage}`);
|
|
1368
|
+
r = setBoardFact(home, { key: operands[0], label: one("label"), value: one("value"), unit: one("unit"), link: one("link") });
|
|
1369
|
+
line = `fact ${r.key} ${r.changed ? "set" : "unchanged"}`;
|
|
1370
|
+
} else if (verb === "unset") {
|
|
1371
|
+
if (operands.length !== 1) return bail("E_BAD_ARGS", `oats instance board unset takes one key; ${usage}`);
|
|
1372
|
+
r = unsetBoardFact(home, operands[0]);
|
|
1373
|
+
line = `fact ${r.key} ${r.changed ? "removed" : "was not set"}`;
|
|
1374
|
+
} else if (values.has("clear")) {
|
|
1375
|
+
if (operands.length || [...values.keys()].some((k) => k !== "clear")) return bail("E_BAD_ARGS", `--clear <id> takes nothing else; ${usage}`);
|
|
1376
|
+
r = clearBoardQuestion(home, one("clear"));
|
|
1377
|
+
line = `question ${r.id} ${r.changed ? "cleared" : "was not open"}`;
|
|
1378
|
+
} else {
|
|
1379
|
+
if (operands.length > 1) return bail("E_BAD_ARGS", `oats instance board ask takes one question (quote it); ${usage}`);
|
|
1380
|
+
// A file's trailing newlines are not content (a heredoc's final LF): they are trimmed before the
|
|
1381
|
+
// context is counted and stored (desktop-rework-lead, a detail filled within contract v4).
|
|
1382
|
+
let context;
|
|
1383
|
+
const file = one("context-file");
|
|
1384
|
+
if (file !== undefined) {
|
|
1385
|
+
try {
|
|
1386
|
+
const st = statSync(file);
|
|
1387
|
+
if (!st.isFile()) return bail("E_BAD_ARGS", `--context-file ${file} is not a regular file`);
|
|
1388
|
+
if (st.size > 64 * 1024) return bail("E_BAD_ARGS", `--context-file ${file} is over 64 KiB; a context is at most 2000 characters`);
|
|
1389
|
+
context = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(file)).replace(/\n+$/, "");
|
|
1390
|
+
} catch (e) { return bail("E_BAD_ARGS", `--context-file ${file} cannot be read as UTF-8 text (${e.code || e.message})`); }
|
|
1391
|
+
}
|
|
1392
|
+
r = askBoardQuestion(home, { question: operands[0], options: values.get("option") ?? [], id: one("id"), context });
|
|
1393
|
+
line = `question ${r.id} ${r.changed ? "asked: answers arrive typed as" : "is already open: answers arrive typed as"} "${r.id}: <text>"`;
|
|
1394
|
+
}
|
|
1395
|
+
} catch (e) { return bail(e.code || "E_BOARD_FAILED", e.message, e.details); }
|
|
1396
|
+
const { board, changed, ...named } = r;
|
|
1397
|
+
if (JSON_MODE) { jsonOk({ boardApi: BOARD_API, instance, home, ...named, changed, board }); return; }
|
|
1398
|
+
console.log(`${instance}: ${line}`);
|
|
1399
|
+
}
|
|
1400
|
+
|
|
1315
1401
|
/** A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone, an ssh
|
|
1316
1402
|
* session that ended) has only stopped reading: the command goes on to its consistent end, what it
|
|
1317
1403
|
* can no longer print is dropped, and its exit status is the one it would have had. Unhandled,
|
|
@@ -1452,9 +1538,10 @@ async function instanceCmd() {
|
|
|
1452
1538
|
const sub = args[1], name = args[2];
|
|
1453
1539
|
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1454
1540
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1541
|
+
if (sub === "board") return instanceBoardCmd(bail);
|
|
1455
1542
|
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1456
|
-
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance
|
|
1457
|
-
if (!["git", "diff", "stop", "events", "color", "background", "pin", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1543
|
+
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance board set|unset|ask … [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off (deprecated alias of related-work)";
|
|
1544
|
+
if (!["git", "diff", "stop", "events", "color", "background", "pin", "related-work", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1458
1545
|
dropAmbientRoot();
|
|
1459
1546
|
if (sub === "events") {
|
|
1460
1547
|
// K7: typed producer events, bounded window; nothing inferred.
|
|
@@ -1547,20 +1634,21 @@ async function instanceCmd() {
|
|
|
1547
1634
|
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1548
1635
|
}
|
|
1549
1636
|
}
|
|
1550
|
-
|
|
1551
|
-
|
|
1637
|
+
// `oats instance same-work` is the verb's deprecated alias (the dispatch said so on stderr): the same command.
|
|
1638
|
+
if (sub === "related-work" || sub === "same-work") {
|
|
1639
|
+
// Feature instance-related-work: presentation only, so no plan; addressed as color addresses an instance.
|
|
1552
1640
|
const homeOpt = flag("home");
|
|
1553
1641
|
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1554
|
-
const
|
|
1642
|
+
const relatedWorkUsage = "usage: oats instance related-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1555
1643
|
// The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
|
|
1556
1644
|
const words = [];
|
|
1557
1645
|
for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
|
|
1558
|
-
if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${
|
|
1646
|
+
if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${relatedWorkUsage}`);
|
|
1559
1647
|
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
1560
1648
|
try {
|
|
1561
|
-
const r =
|
|
1649
|
+
const r = setInstanceRelatedWork(dirFlag(), root, name, { home: homeOpt, on: words[0] === "on" });
|
|
1562
1650
|
if (JSON_MODE) { jsonOk(r); return; }
|
|
1563
|
-
console.log(`${r.instance}:
|
|
1651
|
+
console.log(`${r.instance}: related work ${r.relatedWork ? "on" : "off"}`);
|
|
1564
1652
|
return;
|
|
1565
1653
|
} catch (e) {
|
|
1566
1654
|
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
@@ -2916,8 +3004,10 @@ async function spawnCmd() {
|
|
|
2916
3004
|
prepared,
|
|
2917
3005
|
purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText ?? stdinTask, taskFile: stdinTask === undefined ? taskFileFlag : undefined, relation, relativeTo, relativeRoot,
|
|
2918
3006
|
...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
|
|
2919
|
-
// Feature instance-
|
|
2920
|
-
|
|
3007
|
+
// Feature instance-related-work: the kernel binds it to the parent the new home records, else to its
|
|
3008
|
+
// sibling, or refuses.
|
|
3009
|
+
// `--same-work` is its deprecated alias (the dispatch said so on stderr).
|
|
3010
|
+
...(args.includes("--related-work") || args.includes("--same-work") ? { relatedWork: true } : {}),
|
|
2921
3011
|
// Directory execution uses deployment configuration, not an ambient Git
|
|
2922
3012
|
// checkout (especially when invoked via --dir from a source instance).
|
|
2923
3013
|
// An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
|
|
@@ -4217,7 +4307,7 @@ function versionCmd() {
|
|
|
4217
4307
|
// Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
|
|
4218
4308
|
// runs on resolve/materialize (contract §6); a feature the binary does not implement is
|
|
4219
4309
|
// never listed.
|
|
4220
|
-
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: KERNEL_FEATURES, 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, readerApi: READER_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
|
|
4310
|
+
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: KERNEL_FEATURES, 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, readerApi: READER_API, boardApi: BOARD_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
|
|
4221
4311
|
return;
|
|
4222
4312
|
}
|
|
4223
4313
|
console.log(`${OATS_PACKAGE_NAME} ${OATS_VERSION} (desktop API v1)`);
|
|
@@ -4816,6 +4906,9 @@ if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ co
|
|
|
4816
4906
|
// A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
|
|
4817
4907
|
// and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
|
|
4818
4908
|
{ const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
|
|
4909
|
+
// A deprecated alias of the related-work flag or verb (lib/command-flags.mjs SAME_WORK_ALIASES) works as the
|
|
4910
|
+
// new spelling, and says so once on stderr, never in a --json answer: before it runs or is sent to a host.
|
|
4911
|
+
{ const deprecated = sameWorkDeprecation(rawArgs); if (deprecated) process.stderr.write(`oats: ${deprecated}\n`); }
|
|
4819
4912
|
// Session resume is local only (#1559, D1): a server resumes its own instances.
|
|
4820
4913
|
if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
|
|
4821
4914
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
@@ -5074,9 +5167,11 @@ Usage:
|
|
|
5074
5167
|
[--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
|
|
5075
5168
|
[--relative-to <instance>] default: unrelated, top-level
|
|
5076
5169
|
[--relative-root <agents-root>] disambiguates same-named anchors
|
|
5077
|
-
[--
|
|
5078
|
-
its parent; clients draw the
|
|
5079
|
-
(needs a relation that records a
|
|
5170
|
+
[--related-work] record that the new instance does related work with
|
|
5171
|
+
its parent, else its sibling; clients draw the
|
|
5172
|
+
line for it (needs a relation that records a
|
|
5173
|
+
parent or a sibling)
|
|
5174
|
+
[--same-work] deprecated alias of --related-work
|
|
5080
5175
|
[--work worktree|checkout|attached|workspace|directory] override the soul's work mode
|
|
5081
5176
|
[--work-dir <owner-work>] attached: the owner's work tree (always a child)
|
|
5082
5177
|
[--branch <b>] [--base <ref>] worktree branch and starting ref;
|
|
@@ -5140,7 +5235,7 @@ Usage:
|
|
|
5140
5235
|
a detached external retirement runs
|
|
5141
5236
|
oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
|
|
5142
5237
|
[--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
|
|
5143
|
-
[--instructions] [--skills]
|
|
5238
|
+
[--board] [--instructions] [--skills] installed capabilities with health, effective
|
|
5144
5239
|
[--composed-skills] [--max-age <s>] layer bindings and activation, declared
|
|
5145
5240
|
[--json] operations with availability; --home answers the
|
|
5146
5241
|
running home's recorded modules and their drift
|
|
@@ -5148,6 +5243,8 @@ Usage:
|
|
|
5148
5243
|
adds the AGENTS.md a spawn of the soul here would write;
|
|
5149
5244
|
--skills (--soul only) adds the soul's own skills, the
|
|
5150
5245
|
ones a spawn copies, with each file's text;
|
|
5246
|
+
--board (--home only) adds the agent's board, each
|
|
5247
|
+
fact's history and each question's context;
|
|
5151
5248
|
--composed-skills (--soul only) adds every skill a spawn
|
|
5152
5249
|
would give the instance, its capabilities' included
|
|
5153
5250
|
oats operation run <layer>:<name> run an operation the soul's core capability for that
|
|
@@ -5248,6 +5345,15 @@ Usage:
|
|
|
5248
5345
|
oats instance attention [--message=<text>] [--clear] [--json]
|
|
5249
5346
|
run by the agent from its home: "I need a human's
|
|
5250
5347
|
answer" (waiting --producer agent --reason attention)
|
|
5348
|
+
oats instance board set <key> --label <text> --value <text> [--unit <text>] [--link <https-url>] [--json]
|
|
5349
|
+
oats instance board unset <key> [--json]
|
|
5350
|
+
run by the agent from its home: a fact its person
|
|
5351
|
+
keeps in view on the agent's board (at most 12)
|
|
5352
|
+
oats instance board ask <question> --option <text> --option <text> [--option <text>]… [--id <id>] [--context-file <f>] [--json]
|
|
5353
|
+
oats instance board ask --clear <id> [--json]
|
|
5354
|
+
run by the agent from its home: a question with 2
|
|
5355
|
+
to 4 options (at most 9 open); answers arrive typed
|
|
5356
|
+
as "<id>: <text>"; clear it once read
|
|
5251
5357
|
oats instance upgrade <instance> --plan [--undo] [--json]
|
|
5252
5358
|
Preview package module moves and provider adoption; session must be stopped.
|
|
5253
5359
|
oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--undo] [--json]
|
|
@@ -5268,10 +5374,12 @@ Usage:
|
|
|
5268
5374
|
pin the instance at the top of its machine's
|
|
5269
5375
|
list; shared, as every viewer of the machine
|
|
5270
5376
|
reads it from the home
|
|
5271
|
-
oats instance
|
|
5272
|
-
record that this instance does
|
|
5273
|
-
its parent (on needs
|
|
5274
|
-
draw the
|
|
5377
|
+
oats instance related-work <instance> on|off [--home <abs>] [--json]
|
|
5378
|
+
record that this instance does related work with
|
|
5379
|
+
its parent, else its sibling (on needs one
|
|
5380
|
+
recorded); clients draw the line for it; off
|
|
5381
|
+
removes it; oats instance same-work is its
|
|
5382
|
+
deprecated alias
|
|
5275
5383
|
oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi]
|
|
5276
5384
|
[--model <m>] [--launch-config <n>] [--dir <d>] [--json]
|
|
5277
5385
|
a name for a spawn by this machine's harness, as a
|
package/docs/capabilities.md
CHANGED
|
@@ -333,8 +333,9 @@ A self-contained package has an `oats.json`:
|
|
|
333
333
|
- an exact name that is `.oats`, `.agents` or `.claude`, or that starts
|
|
334
334
|
with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
|
|
335
335
|
`.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
|
|
336
|
-
`.oats-background`, `.oats-pinned
|
|
337
|
-
|
|
336
|
+
`.oats-background`, `.oats-pinned`, `.oats-related-work`, `.oats-same-work` (the
|
|
337
|
+
file of the flag `.oats-related-work` replaced, still read while the new one is absent) or
|
|
338
|
+
`.oats-board`: the top-level entries the kernel itself writes in an instance home;
|
|
338
339
|
- a prefix that starts with `.oats-`.
|
|
339
340
|
|
|
340
341
|
An exact name such as `.oats-aweb` is allowed: it is a provider's
|
|
@@ -1244,6 +1245,15 @@ bidi controls (U+202A–202E, U+2066–2069), U+200B, U+2060, U+FEFF and tag
|
|
|
1244
1245
|
characters (U+E0000–E007F) are refused, and everything else (emoji ZWJ
|
|
1245
1246
|
sequences, ZWNJ, LRM, RLM, ALM) is allowed.
|
|
1246
1247
|
|
|
1248
|
+
**The board's claim** (feature `instance-board`). An agent that needs a
|
|
1249
|
+
decision between 2 and 4 options asks it on its board, `oats instance board
|
|
1250
|
+
ask <question> --option <text> --option <text>`. While any board question is
|
|
1251
|
+
open, the kernel holds a claim of producer `oats.board`, reason `attention`,
|
|
1252
|
+
whose message is the oldest open question, and the last `oats instance board
|
|
1253
|
+
ask --clear <id>` removes it. It sits beside the agent's own `attention`
|
|
1254
|
+
claim and holds no scheduled wake. The board is in
|
|
1255
|
+
[desktop-cli-api.md](desktop-cli-api.md#the-agents-board-oats-instance-board).
|
|
1256
|
+
|
|
1247
1257
|
**The Claude Code emitter.** For a Claude instance, oats.core's spawn and
|
|
1248
1258
|
launch hooks (`bin/oats-core.mjs`, preview-aware) write Claude Code hooks
|
|
1249
1259
|
into the home's project settings, `<home>/.claude/settings.json`. Each one
|
|
@@ -374,7 +374,7 @@
|
|
|
374
374
|
"description": "Home entries the kernel owns cannot be declared.",
|
|
375
375
|
"anyOf": [
|
|
376
376
|
{"pattern": "^\\.(?:oats|agents|claude)$"},
|
|
377
|
-
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work)"},
|
|
377
|
+
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work|related-work|board)"},
|
|
378
378
|
{"pattern": "^\\.oats-.*\\*$"}
|
|
379
379
|
]
|
|
380
380
|
}
|