@awebai/oats 0.69.21 → 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 +290 -5
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- 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 +377 -148
- package/docs/implementation.md +15 -2
- 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 +47 -4
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.22.md +221 -0
- 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 +48 -7
- package/docs/upgrading.md +17 -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/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +7 -2
- package/packages/client/deployment-panel.mjs +4 -1
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +96 -24
- package/packages/client/keymap.mjs +16 -3
- 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 +11 -3
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +97 -24
- 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/lib/instance-events.mjs
CHANGED
|
@@ -25,7 +25,9 @@
|
|
|
25
25
|
*
|
|
26
26
|
* Producers write claims as `waiting` rows through `setWaiting` (the CLI's
|
|
27
27
|
* `oats instance waiting` and `oats instance attention`): data
|
|
28
|
-
* `{waitingOnYou, reason?, message?}`, appended only on a change
|
|
28
|
+
* `{waitingOnYou, reason?, message?, session?}`, appended only on a change; `session`
|
|
29
|
+
* (the board's claim, lib/instance-board.mjs) binds a positive claim to the session it was
|
|
30
|
+
* derived in, so it never counts in another (claimsOf). A claim
|
|
29
31
|
* authorizes nothing; it may only withhold an automated keystroke: a scheduled
|
|
30
32
|
* wake holds on a live `permission`, `question` or unknown-reason claim
|
|
31
33
|
* (waitingHold). Every other reader takes it as evidence for display.
|
|
@@ -41,6 +43,7 @@
|
|
|
41
43
|
* one home's, so its `home` is the address that was asked about, and a consumer
|
|
42
44
|
* that checks "the rows' home is the home I asked for" keeps holding. */
|
|
43
45
|
import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
|
|
46
|
+
import { createHash } from "node:crypto";
|
|
44
47
|
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
45
48
|
import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
|
|
46
49
|
|
|
@@ -85,6 +88,12 @@ function cutToUnits(text, max) {
|
|
|
85
88
|
* incarnation's latest one is not live. */
|
|
86
89
|
export const WAITING_BOUNDARY_KINDS = ["launched", "restarted", "stopped"];
|
|
87
90
|
const sessionBoundary = (r) => (r.producer ?? "kernel") === "kernel" && WAITING_BOUNDARY_KINDS.includes(r.kind);
|
|
91
|
+
/** The id of the session a boundary row begins, or null for no boundary: what a session-bound claim
|
|
92
|
+
* (setWaiting `session`) and a board question (lib/instance-board.mjs) record. `<kind>@<at>#<digest of
|
|
93
|
+
* its data>`: two boundaries of one millisecond are told apart by what they record (a launch's
|
|
94
|
+
* `startId`, a stop's receipt), never by their place in a bounded read, and the same row written
|
|
95
|
+
* again (a start boundary repaired into the other log, recordStartBoundary) is the same session. */
|
|
96
|
+
const sessionIdOf = (r) => (r ? `${r.kind}@${r.at}#${createHash("sha256").update(JSON.stringify(r.data ?? null)).digest("hex").slice(0, 16)}` : null);
|
|
88
97
|
/** The closed set of reasons a positive claim carries. A claim authorizes nothing; it may only
|
|
89
98
|
* withhold an automated keystroke. `attention` never marks a screen an Enter answers: a producer
|
|
90
99
|
* that wants one uses `question`, and review catches that. */
|
|
@@ -232,6 +241,10 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
|
|
|
232
241
|
return { ok: results.some((r) => r.ok), row, results };
|
|
233
242
|
}
|
|
234
243
|
|
|
244
|
+
/** Whether a read of one log holds the whole log: it was absent, or read in full (not a tail, not
|
|
245
|
+
* refused). */
|
|
246
|
+
const wholeRead = (log) => log.source.status === "ok" || log.source.status === "absent";
|
|
247
|
+
|
|
235
248
|
/** Bounded, descriptor-safe read of one log: lstat → regular file only → read
|
|
236
249
|
* at most the last MAX_BYTES. Returns rows plus the source's integrity facts, and
|
|
237
250
|
* `lastTorn`: where the last torn row sat, as the index in `rows` of the row after it
|
|
@@ -300,8 +313,10 @@ function admit(home, reads) {
|
|
|
300
313
|
* unknown stays unknown, it never resurrects an earlier incarnation's
|
|
301
314
|
* positive. A row older than the incarnation's latest kernel session
|
|
302
315
|
* boundary belongs to an ended session and is not a claim at all, nor is a
|
|
303
|
-
* row whose producer is neither `kernel` nor a valid producer id.
|
|
304
|
-
|
|
316
|
+
* row whose producer is neither `kernel` nor a valid producer id. `complete`:
|
|
317
|
+
* whether every log read was whole (wholeRead); a session-bound row needs it,
|
|
318
|
+
* or a boundary of the incarnation in the rows, to count (below). */
|
|
319
|
+
function claimsOf(rows, incarnation, { complete }) {
|
|
305
320
|
const claims = new Map();
|
|
306
321
|
if (incarnation === null) return claims;
|
|
307
322
|
const current = rows.filter((r) => r.incarnation === incarnation);
|
|
@@ -309,8 +324,14 @@ function claimsOf(rows, incarnation) {
|
|
|
309
324
|
// millisecond keep their append order, and a claim appended before the
|
|
310
325
|
// boundary in that millisecond is still before it.
|
|
311
326
|
const boundary = current.findLastIndex(sessionBoundary);
|
|
327
|
+
const session = sessionIdOf(current[boundary]);
|
|
312
328
|
for (const r of current.slice(boundary + 1)) {
|
|
313
329
|
if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
|
|
330
|
+
// A session-bound row (setWaiting `session`) counts only in the session it names, and only where
|
|
331
|
+
// the read proves the current session: a boundary of the incarnation in the rows, or a whole read
|
|
332
|
+
// (with none, the first session). One appended after a boundary its writer had not seen, or read
|
|
333
|
+
// where the current boundary may have fallen out of a tail, says nothing. Unbound rows are as before.
|
|
334
|
+
if (Object.hasOwn(r.data, "session") && (r.data.session !== session || (boundary < 0 && !complete))) continue;
|
|
314
335
|
const p = r.producer ?? "kernel";
|
|
315
336
|
// A row the read rule refuses (a hand-edited log: its producer, its time) says nothing.
|
|
316
337
|
const claim = readWaitingClaim({ since: r.at, producer: p, reason: r.data.reason, message: r.data.message });
|
|
@@ -344,7 +365,7 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
|
|
|
344
365
|
const { home, instance, incarnation, homeLog, workspaceLog } = address;
|
|
345
366
|
const a = readLog(homeLog, "home"), b = readLog(workspaceLog, "workspace");
|
|
346
367
|
const { rows, foreign } = admit(home, [a, b]);
|
|
347
|
-
const claims = claimsOf(rows, incarnation);
|
|
368
|
+
const claims = claimsOf(rows, incarnation, { complete: wholeRead(a) && wholeRead(b) });
|
|
348
369
|
const waitingClaims = [...claims.values()];
|
|
349
370
|
const positive = positiveOf(claims);
|
|
350
371
|
const filtered = since ? rows.filter((r) => r.at > since) : rows;
|
|
@@ -374,11 +395,26 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
|
|
|
374
395
|
* or a session boundary writes goes to both. `meta`: the home's record, when the caller has just
|
|
375
396
|
* read it (lib/instance-listing.mjs listInstances), so that one read parses it once. */
|
|
376
397
|
export function liveWaiting(home, { meta } = {}) {
|
|
398
|
+
return liveSession(home, { meta }).waitingOnYou;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/** The instance's current session as one read of its log shows it (liveWaiting's read):
|
|
402
|
+
* `{ incarnation, session, sessionKnown, waitingOnYou }`. `session` is the id of the incarnation's
|
|
403
|
+
* latest kernel session boundary (`launched`, `restarted`, `stopped`; `<kind>@<at>`), null when the
|
|
404
|
+
* read holds none. `sessionKnown` says whether the read proves it: false when the log was read as a
|
|
405
|
+
* tail (its last MAX_BYTES) that holds no boundary of this incarnation, where an earlier one may
|
|
406
|
+
* have been cut off. A board question counts only in the session it was asked in
|
|
407
|
+
* (lib/instance-board.mjs). An unknown incarnation is `{ incarnation: null, session: null,
|
|
408
|
+
* sessionKnown: false, waitingOnYou: null }`. */
|
|
409
|
+
export function liveSession(home, { meta } = {}) {
|
|
377
410
|
const a = addressOf(home, meta);
|
|
378
|
-
if (a.incarnation === null) return null;
|
|
411
|
+
if (a.incarnation === null) return { incarnation: null, session: null, sessionKnown: false, waitingOnYou: null };
|
|
379
412
|
let log = readLog(a.homeLog, "home");
|
|
380
413
|
if (log.source.status === "absent") log = readLog(a.workspaceLog, "workspace");
|
|
381
|
-
|
|
414
|
+
const rows = admit(a.home, [log]).rows;
|
|
415
|
+
const boundary = rows.filter((r) => r.incarnation === a.incarnation).findLast(sessionBoundary);
|
|
416
|
+
const sessionKnown = !!boundary || wholeRead(log);
|
|
417
|
+
return { incarnation: a.incarnation, session: sessionIdOf(boundary), sessionKnown, waitingOnYou: waitingShape(positiveOf(claimsOf(rows, a.incarnation, { complete: wholeRead(log) }))) };
|
|
382
418
|
}
|
|
383
419
|
|
|
384
420
|
/** What holds a scheduled wake at this home: null (no hold), `{claimReason, producer}` (a claim), or
|
|
@@ -403,7 +439,7 @@ export function waitingHold(given) {
|
|
|
403
439
|
if (status === "tail" && boundary < 0) return unreadable(`the ${path} events log's tail holds no session boundary`);
|
|
404
440
|
if (log.lastTorn > boundary) return unreadable(`the ${path} events log has a torn row in this session`);
|
|
405
441
|
}
|
|
406
|
-
const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation).values()].filter((c) => c.waiting && c.reason !== "attention");
|
|
442
|
+
const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation, { complete: logs.every(wholeRead) }).values()].filter((c) => c.waiting && c.reason !== "attention");
|
|
407
443
|
const newest = claims.sort((x, y) => x.since.localeCompare(y.since)).at(-1);
|
|
408
444
|
return newest ? { claimReason: newest.reason, producer: newest.producer } : null;
|
|
409
445
|
}
|
|
@@ -420,13 +456,15 @@ const waitingError = (code, message) => Object.assign(new Error(message), { code
|
|
|
420
456
|
* E_SESSION_UNKNOWN; a write either log refused is E_EVENTS_FAILED (a retry
|
|
421
457
|
* repairs it). The answer's `home` is the home as the caller spelled it; the row
|
|
422
458
|
* records the real path. Evidence, not authority: nothing else is touched. */
|
|
423
|
-
export function setWaiting(given, { producer, waiting, reason, message } = {}) {
|
|
459
|
+
export function setWaiting(given, { producer, waiting, reason, message, session } = {}) {
|
|
424
460
|
if (typeof producer !== "string" || !WAITING_PRODUCER_RE.test(producer)) throw waitingError("E_BAD_ARGS", `--producer must match ${WAITING_PRODUCER_RE.source}`);
|
|
425
461
|
if (producer === "kernel") throw waitingError("E_BAD_ARGS", "--producer kernel is reserved for the kernel's own events");
|
|
426
462
|
if (typeof waiting !== "boolean") throw waitingError("E_BAD_ARGS", "waiting must be set or clear");
|
|
427
463
|
if (waiting) {
|
|
428
464
|
if (!WAITING_REASONS.includes(reason)) throw waitingError("E_BAD_ARGS", `--reason must be one of ${WAITING_REASONS.join(", ")}`);
|
|
429
465
|
if (message !== undefined && !validWaitingMessage(message)) throw waitingError("E_BAD_ARGS", `--message must be one line of 1 to ${WAITING_MESSAGE_MAX} characters with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
|
|
466
|
+
// A session-bound claim (in-process only: the board's) names the session it was derived in.
|
|
467
|
+
if (session !== undefined && session !== null && typeof session !== "string") throw waitingError("E_BAD_ARGS", "session must be a session id or null");
|
|
430
468
|
} else {
|
|
431
469
|
if (reason !== undefined) throw waitingError("E_BAD_ARGS", "--reason is for set, not clear");
|
|
432
470
|
if (message !== undefined) throw waitingError("E_BAD_ARGS", "--message is for set, not clear");
|
|
@@ -435,11 +473,11 @@ export function setWaiting(given, { producer, waiting, reason, message } = {}) {
|
|
|
435
473
|
const { home, incarnation } = a;
|
|
436
474
|
if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${given} is not an instance home (no readable instance.json)`);
|
|
437
475
|
const live = [readLog(a.homeLog, "home"), readLog(a.workspaceLog, "workspace")]
|
|
438
|
-
.map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation).get(producer); return c?.waiting ? c : null; });
|
|
476
|
+
.map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation, { complete: wholeRead(log) }).get(producer); return c?.waiting ? c : null; });
|
|
439
477
|
const agrees = (c) => (waiting ? !!c && c.reason === reason && c.message === (message ?? null) : !c);
|
|
440
478
|
const answer = (changed, claim) => answered(a, { eventsApi: EVENTS_API, instance: a.instance, home, producer, changed, waitingOnYou: waitingShape(claim) });
|
|
441
479
|
if (live.every(agrees)) return answer(false, waiting ? live[0] : null);
|
|
442
|
-
const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}) } : { waitingOnYou: false };
|
|
480
|
+
const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}), ...(session !== undefined ? { session } : {}) } : { waitingOnYou: false };
|
|
443
481
|
const res = append(a, { producer, kind: "waiting", data }, { incarnation });
|
|
444
482
|
const failed = (res.results || []).filter((r) => !r.ok);
|
|
445
483
|
if (!res.ok || failed.length) throw waitingError("E_EVENTS_FAILED", `could not record the waiting claim in ${failed.map((r) => `${r.path} (${r.reason})`).join(", ") || res.reason}; retry to complete it`);
|
|
@@ -21,7 +21,7 @@ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
|
21
21
|
import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
|
|
22
22
|
import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
|
|
23
23
|
import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
|
|
24
|
-
import {
|
|
24
|
+
import { relatedWorkBinding, relatedWorkHeld, writeRelatedWork } from "./instance-related-work.mjs";
|
|
25
25
|
import { resolveInstance } from "./instance-address.mjs";
|
|
26
26
|
export { resolveInstance } from "./instance-address.mjs";
|
|
27
27
|
|
|
@@ -110,23 +110,27 @@ export function setInstancePin(ctx, root, name, { home, pinned }) {
|
|
|
110
110
|
return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
|
|
111
111
|
}
|
|
112
112
|
|
|
113
|
-
/** `oats instance
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
* `
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
|
|
120
|
-
|
|
113
|
+
/** `oats instance related-work <instance> on|off` (feature instance-related-work), and its deprecated alias
|
|
114
|
+
* `oats instance same-work` (feature instance-same-work): bind the flag of the home
|
|
115
|
+
* `name` resolves to to its recorded parent, else to its recorded sibling (`on`, relatedWorkBinding), or
|
|
116
|
+
* remove it (`off`). Addressed, and refused beside a retire or in a quarantined home, exactly as
|
|
117
|
+
* setInstanceColor is. `on` needs a recorded `parentInstance` or `siblingInstance` (E_BAD_ARGS with
|
|
118
|
+
* neither) and rebinds a record bound to an old relation; the same binding again writes nothing. `off`
|
|
119
|
+
* succeeds whatever stands there, binding or none. → `{ instance, relatedWork, sameWork }`, the rule
|
|
120
|
+
* (relatedWorkHeld) read after the write: `relatedWork` whether it holds, `sameWork` whether it holds as a
|
|
121
|
+
* parent binding (the old verb's answer, for an older client). */
|
|
122
|
+
export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
|
|
123
|
+
if (typeof on !== "boolean") throw oatsError("E_BAD_ARGS", "instance related-work takes on or off");
|
|
121
124
|
const me = resolveTarget(ctx, root, name, { home });
|
|
122
125
|
if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the flag was not changed`);
|
|
123
126
|
if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the flag was not changed`);
|
|
124
|
-
refuseBesideRetire("instance
|
|
125
|
-
const
|
|
126
|
-
const
|
|
127
|
-
if (on &&
|
|
128
|
-
|
|
129
|
-
|
|
127
|
+
refuseBesideRetire("instance related-work", me.home);
|
|
128
|
+
const lineage = targetRecord(me.home) ?? {};
|
|
129
|
+
const binding = relatedWorkBinding(lineage);
|
|
130
|
+
if (on && binding === null) throw oatsError("E_BAD_ARGS", `${name} would record no parent or sibling instance: related work is declared against a recorded parent or sibling; the flag was not changed`);
|
|
131
|
+
writeRelatedWork(me.home, on ? binding : null);
|
|
132
|
+
const held = relatedWorkHeld(me.home, lineage);
|
|
133
|
+
return { instance: name, relatedWork: held !== null, sameWork: !!held?.parent };
|
|
130
134
|
}
|
|
131
135
|
|
|
132
136
|
/** Every instance under the roots whose recorded parent chain reaches `name`,
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -8,7 +8,8 @@ import { readFileSync, readdirSync, lstatSync, existsSync, statSync, openSync, c
|
|
|
8
8
|
import { join, dirname, resolve, basename } from "node:path";
|
|
9
9
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
10
10
|
import { createSessionPaneInspector, AGENT_PANE_OPTION } from "./session-input.mjs";
|
|
11
|
-
import {
|
|
11
|
+
import { liveSession, validWaitingMessage } from "./instance-events.mjs";
|
|
12
|
+
import { readBoardRow } from "./instance-board.mjs";
|
|
12
13
|
import { processLiveness } from "./worktree-hooks.mjs";
|
|
13
14
|
import { shownHolder } from "./claim.mjs";
|
|
14
15
|
import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
|
|
@@ -16,7 +17,7 @@ import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
|
|
|
16
17
|
import { readInstanceColor } from "./instance-color.mjs";
|
|
17
18
|
import { readInstanceBackground } from "./instance-background.mjs";
|
|
18
19
|
import { readInstancePin } from "./instance-pin.mjs";
|
|
19
|
-
import {
|
|
20
|
+
import { relatedWorkHeld } from "./instance-related-work.mjs";
|
|
20
21
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
21
22
|
import { sessionEndOf } from "./session-end.mjs";
|
|
22
23
|
import { identityHolderState, recordSeen } from "./session-seen.mjs";
|
|
@@ -345,15 +346,17 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
345
346
|
// its home log); null otherwise, and null means unknown. Pane liveness is
|
|
346
347
|
// already observed in the batch; still require the independent receipt
|
|
347
348
|
// to agree before showing a claim, just as session inspect does.
|
|
348
|
-
|
|
349
|
+
const recordMeta = record.state === "record" ? { meta: record.meta } : {};
|
|
350
|
+
const session = liveness.running === true ? liveSession(home, recordMeta) : undefined;
|
|
351
|
+
let waitingOnYou = session ? session.waitingOnYou : null;
|
|
349
352
|
if (waitingOnYou) {
|
|
350
353
|
try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
|
|
351
354
|
catch { waitingOnYou = null; }
|
|
352
355
|
}
|
|
353
|
-
// `retire` is only ever the value read above, and `background`, `pinned` and `
|
|
356
|
+
// `retire` is only ever the value read above, and `background`, `pinned`, `relatedWork` and `board` the home's own
|
|
354
357
|
// records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
|
|
355
|
-
// for it.
|
|
356
|
-
const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
|
|
358
|
+
// for it. Nor does a `sameWork` key, the flag's old name (below).
|
|
359
|
+
const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, relatedWork: _recordedRelatedWork, sameWork: _recordedSameWork, board: _recordedBoard, ...recorded } = meta;
|
|
357
360
|
// `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
|
|
358
361
|
// a malformed one is null, and a home spawned before the feature has no key.
|
|
359
362
|
if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
|
|
@@ -365,10 +368,15 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
365
368
|
// null, after the record so that nothing in instance.json stands in for it.
|
|
366
369
|
// Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
|
|
367
370
|
// otherwise, never false.
|
|
368
|
-
// Feature instance-
|
|
369
|
-
// its
|
|
370
|
-
|
|
371
|
-
|
|
371
|
+
// Feature instance-related-work: `relatedWork: true` only while the home's flag is bound to the relation
|
|
372
|
+
// its record still has (lib/instance-related-work.mjs relatedWorkHeld); absent otherwise, never false.
|
|
373
|
+
// Feature instance-same-work, the compatibility layer: `sameWork: true` beside it for a parent binding
|
|
374
|
+
// only, as an older client reads it; absent otherwise.
|
|
375
|
+
const related = record.state === "record" ? relatedWorkHeld(home, meta) : null;
|
|
376
|
+
// Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
|
|
377
|
+
// file: its facts, and the questions of its current session, by the same read of the log as the claim.
|
|
378
|
+
const board = readBoardRow(home, { session, ...recordMeta });
|
|
379
|
+
return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
372
380
|
|
|
373
381
|
});
|
|
374
382
|
};
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/** The "related work" flag (feature instance-related-work; the same-work flag of awebai/oats#1577, renamed):
|
|
2
|
+
* an instance's declared "related work" with the instance it is bound to, its parent or its sibling, which
|
|
3
|
+
* clients draw as a line between the two. A home file of its own, `<home>/.oats-related-work.json`, so that a
|
|
4
|
+
* start, restart, stop or resume, which rewrite instance.json, never lose it; only `oats instance
|
|
5
|
+
* related-work … off` or retirement removes it. The kernel never sets it on its own: only `oats spawn
|
|
6
|
+
* --related-work` and the verb do (and their deprecated aliases, `--same-work` and `oats instance same-work`).
|
|
7
|
+
*
|
|
8
|
+
* The flag is BOUND to the relation it was set against: the home's recorded `parentInstance` when it has
|
|
9
|
+
* one, else its recorded `siblingInstance` (relatedWorkBinding, the one choice). The record names that
|
|
10
|
+
* instance and the kind of edge, and the flag is on only while that edge is still the home's
|
|
11
|
+
* (relatedWorkHeld, the one rule). A relink that changes the relation (a retire's splice, a `--relation
|
|
12
|
+
* parent` spawn re-pointing its anchor) leaves the record bound to the old name, so the flag reads off and
|
|
13
|
+
* nothing errors. A sibling binding names the sibling the home records: for a sibling of a root, that root;
|
|
14
|
+
* for a sibling of a sibling, the anchor it was spawned beside (lib/core.mjs records the anchor itself).
|
|
15
|
+
*
|
|
16
|
+
* The record is `{ relatedWorkApi: 1, parent | sibling, at }`, exactly one of `parent` and `sibling`,
|
|
17
|
+
* written atomically (writeThroughPrivateFile) at mode 0600; present means on. A reader takes a regular file
|
|
18
|
+
* only, without following a link, up to RECORD_MAX bytes: anything that is not a valid record reads as no
|
|
19
|
+
* binding (null), never an error.
|
|
20
|
+
*
|
|
21
|
+
* The compatibility layer with the same-work flag it replaced (item 4 of the related-work contract), all of
|
|
22
|
+
* it in this module and its callers named here: the old home file `.oats-same-work.json`,
|
|
23
|
+
* `{ sameWorkApi: 1, parent, at }`, reads as a parent binding while nothing stands at the new name
|
|
24
|
+
* (readRelatedWork); the write that creates the new file removes the old one, and a removal takes both
|
|
25
|
+
* (writeRelatedWork). Both names are kernel-owned (lib/capability-contract.mjs KERNEL_HOME_NAME_PREFIXES,
|
|
26
|
+
* lib/core.mjs KERNEL_HOME_RECEIPTS, the manifest schema). The old row field `sameWork: true` stands beside
|
|
27
|
+
* `relatedWork: true` for a parent binding (lib/instance-listing.mjs), and the old spellings are aliases
|
|
28
|
+
* (lib/command-flags.mjs SAME_WORK_ALIASES). Dependency-free: the status rows, spawn and the command all go
|
|
29
|
+
* through here. */
|
|
30
|
+
import { lstatSync, rmSync } from "node:fs";
|
|
31
|
+
import { join } from "node:path";
|
|
32
|
+
import { readFileHead } from "./bounded-read.mjs";
|
|
33
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
34
|
+
|
|
35
|
+
/** The record's own version. */
|
|
36
|
+
export const RELATED_WORK_API = 1;
|
|
37
|
+
/** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
|
|
38
|
+
* fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
|
|
39
|
+
export const RELATED_WORK_FILE = ".oats-related-work.json";
|
|
40
|
+
/** The file of the same-work flag the new one replaced: read while the new one is absent, never written,
|
|
41
|
+
* removed by the write that creates the new one and by a removal; kernel-owned. */
|
|
42
|
+
export const SAME_WORK_FILE = ".oats-same-work.json";
|
|
43
|
+
/** The old record's own version. */
|
|
44
|
+
const SAME_WORK_API = 1;
|
|
45
|
+
/** A record larger than this is not one. */
|
|
46
|
+
export const RECORD_MAX = 4096;
|
|
47
|
+
|
|
48
|
+
const isName = (v) => typeof v === "string" && v !== "";
|
|
49
|
+
|
|
50
|
+
/** The binding a home with lineage `{ parentInstance, siblingInstance }` (its instance.json, or a spawn's
|
|
51
|
+
* lineage before it is written) takes: `{ parent }` when it records a parent, else `{ sibling }` when it
|
|
52
|
+
* records a sibling, else null (no flag can be set). The one choice: spawn, the verb and the route ask it. */
|
|
53
|
+
export function relatedWorkBinding(lineage) {
|
|
54
|
+
if (isName(lineage?.parentInstance)) return { parent: lineage.parentInstance };
|
|
55
|
+
if (isName(lineage?.siblingInstance)) return { sibling: lineage.siblingInstance };
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** The JSON object in the file at `path`, or null: no file, not a regular file (a link is never followed),
|
|
60
|
+
* over RECORD_MAX bytes, unreadable, not a JSON object. Never throws. */
|
|
61
|
+
function readRecord(path) {
|
|
62
|
+
try {
|
|
63
|
+
const { bytes, size } = readFileHead(path, RECORD_MAX + 1);
|
|
64
|
+
if (size > RECORD_MAX) return null;
|
|
65
|
+
const record = JSON.parse(bytes.toString("utf8"));
|
|
66
|
+
return record && typeof record === "object" && !Array.isArray(record) ? record : null;
|
|
67
|
+
} catch { return null; }
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Whether anything at all stands at `path` (a file, a link, a directory, one that can't be read). */
|
|
71
|
+
function standsAt(path) {
|
|
72
|
+
try { lstatSync(path); return true; } catch (e) { return e?.code !== "ENOENT"; }
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** The binding `home`'s record holds, `{ parent }` or `{ sibling }`, or null. The new record, while anything
|
|
76
|
+
* stands at its name: null when it is not a record (readRecord), another relatedWorkApi, or not exactly one
|
|
77
|
+
* of a non-empty string `parent` and `sibling`. With nothing at the new name, the old same-work record, as
|
|
78
|
+
* a parent binding: null when it is not a record, another sameWorkApi, or no non-empty string `parent`.
|
|
79
|
+
* The one read of both files. Never throws. */
|
|
80
|
+
export function readRelatedWork(home) {
|
|
81
|
+
const path = join(home, RELATED_WORK_FILE);
|
|
82
|
+
if (!standsAt(path)) {
|
|
83
|
+
const old = readRecord(join(home, SAME_WORK_FILE));
|
|
84
|
+
return old?.sameWorkApi === SAME_WORK_API && isName(old.parent) ? { parent: old.parent } : null;
|
|
85
|
+
}
|
|
86
|
+
const record = readRecord(path);
|
|
87
|
+
if (!record || record.relatedWorkApi !== RELATED_WORK_API) return null;
|
|
88
|
+
const hasParent = Object.hasOwn(record, "parent"), hasSibling = Object.hasOwn(record, "sibling");
|
|
89
|
+
if (hasParent === hasSibling) return null;
|
|
90
|
+
if (hasParent) return isName(record.parent) ? { parent: record.parent } : null;
|
|
91
|
+
return isName(record.sibling) ? { sibling: record.sibling } : null;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
const sameBinding = (a, b) => !!a && !!b && a.parent === b.parent && a.sibling === b.sibling;
|
|
95
|
+
|
|
96
|
+
/** Remove whatever stands at `path` (a file, a link, a directory), and nothing when nothing does. */
|
|
97
|
+
const removeAt = (path) => { if (standsAt(path)) rmSync(path, { recursive: true, force: true }); };
|
|
98
|
+
|
|
99
|
+
/** Bind `home`'s flag to `binding` (`{ parent: <name> }` or `{ sibling: <name> }`), or remove it when
|
|
100
|
+
* `binding` is null. → `{ changed }`. A home already holding `binding` (readRelatedWork: from either file)
|
|
101
|
+
* is no change: nothing is written. Otherwise the new record is written, and the old same-work file, if
|
|
102
|
+
* anything stands at its name, is removed after it. A removal takes whatever stands at either name (an
|
|
103
|
+
* unreadable file, a link, a directory), and is a change only when a valid binding was read. The caller
|
|
104
|
+
* decided `binding` (relatedWorkBinding of the home's record) and holds the right to change the home. */
|
|
105
|
+
export function writeRelatedWork(home, binding, { now = () => new Date() } = {}) {
|
|
106
|
+
if (binding !== null) {
|
|
107
|
+
const keys = binding && typeof binding === "object" && !Array.isArray(binding) ? Object.keys(binding) : [];
|
|
108
|
+
if (keys.length !== 1 || !["parent", "sibling"].includes(keys[0]) || !isName(binding[keys[0]])) {
|
|
109
|
+
throw new TypeError("writeRelatedWork: binding is { parent: <name> }, { sibling: <name> } or null");
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
const path = join(home, RELATED_WORK_FILE), oldPath = join(home, SAME_WORK_FILE);
|
|
113
|
+
const before = readRelatedWork(home);
|
|
114
|
+
if (binding !== null && sameBinding(before, binding)) return { changed: false };
|
|
115
|
+
if (binding === null) {
|
|
116
|
+
removeAt(path);
|
|
117
|
+
removeAt(oldPath);
|
|
118
|
+
return { changed: before !== null };
|
|
119
|
+
}
|
|
120
|
+
// A directory at the name is no record, and a rename cannot replace it: it goes first. A link or a file
|
|
121
|
+
// is replaced by the rename itself.
|
|
122
|
+
let present;
|
|
123
|
+
try { present = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
|
|
124
|
+
if (present?.isDirectory()) rmSync(path, { recursive: true, force: true });
|
|
125
|
+
const bytes = JSON.stringify({ relatedWorkApi: RELATED_WORK_API, ...binding, at: now().toISOString() }) + "\n";
|
|
126
|
+
writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
|
|
127
|
+
// The new record stands: the old one would never be read again.
|
|
128
|
+
removeAt(oldPath);
|
|
129
|
+
return { changed: true };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** THE rule: the binding of `home` that holds against the row's current lineage `{ parentInstance,
|
|
133
|
+
* siblingInstance }`, or null. A parent binding holds only while its name is the current `parentInstance`;
|
|
134
|
+
* a sibling binding only while the row records no parent and its name is the current `siblingInstance`. */
|
|
135
|
+
export function relatedWorkHeld(home, lineage) {
|
|
136
|
+
const bound = readRelatedWork(home);
|
|
137
|
+
return bound !== null && sameBinding(bound, relatedWorkBinding(lineage)) ? bound : null;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Whether `home` does related work, by the rule (relatedWorkHeld). */
|
|
141
|
+
export function relatedWorkOf(home, lineage) {
|
|
142
|
+
return relatedWorkHeld(home, lineage) !== null;
|
|
143
|
+
}
|
package/lib/kernel-features.mjs
CHANGED
|
@@ -8,6 +8,9 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
|
|
|
8
8
|
/** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
|
|
9
9
|
* its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
|
|
10
10
|
export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
|
|
11
|
-
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
|
|
11
|
+
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "instance-related-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE, "instance-board"]);
|
|
12
|
+
/** The agent's board (feature instance-board, lib/instance-board.mjs): `boardApi` in the probe, the board
|
|
13
|
+
* file and the board commands' answers. */
|
|
14
|
+
export const BOARD_API = 1;
|
|
12
15
|
/** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
|
|
13
16
|
export const READER_API = 1;
|