@awebai/oats 0.69.1 → 0.69.3
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 +79 -15
- package/docs/capabilities.md +24 -5
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
- package/docs/design/2026-10-22-module-upgrade.md +1 -1
- package/docs/desktop-cli-api.md +273 -66
- package/docs/desktop-instance-start.md +8 -37
- package/docs/desktop.md +76 -9
- package/docs/execution-targets.md +27 -5
- package/docs/implementation.md +6 -5
- package/docs/integrations.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.69.2.md +259 -0
- package/docs/release-notes/v0.69.3.md +43 -0
- package/docs/servers.md +7 -2
- package/docs/soul.schema.json +1 -0
- package/docs/souls-and-instances.md +35 -2
- package/docs/tui.md +112 -15
- package/docs/upgrading.md +9 -5
- package/docs/workspaces.md +2 -2
- package/injects/instance-boundary.md +19 -33
- package/injects/work-attached.md +8 -13
- package/injects/work-checkout.md +16 -30
- package/injects/work-directory.md +9 -15
- package/injects/work-workspace.md +8 -19
- package/injects/work-worktree.md +18 -33
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +162 -49
- package/lib/instance-background.mjs +54 -0
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +35 -0
- package/lib/instance-resolution.mjs +3 -2
- package/lib/instance-same-work.mjs +67 -0
- package/lib/instance-upgrade.mjs +18 -0
- package/lib/materialize.mjs +23 -2
- package/lib/resolve.mjs +32 -5
- package/lib/servers.mjs +19 -4
- package/lib/session-resume-contract.mjs +1 -0
- package/lib/session-resume.mjs +36 -9
- package/lib/soul-composition.mjs +13 -10
- package/lib/workspace.mjs +3 -2
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +30 -8
- package/packages/client/deployment-data.mjs +9 -0
- package/packages/client/deployment-panel.mjs +4 -0
- package/packages/client/instance-tree.mjs +64 -14
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/panel-views.mjs +11 -3
- package/packages/client/remote-roster.mjs +5 -1
- package/packages/client/roster-sections.mjs +50 -6
- package/packages/client/same-work.mjs +49 -0
- package/packages/client/session-resume-trigger.mjs +15 -37
- package/packages/client/session-resume.mjs +22 -259
- package/packages/client/soul-rows.mjs +2 -0
- package/packages/client/spawn-apply-contract.mjs +2 -1
- package/packages/client/spawn-decision.mjs +4 -1
- package/packages/client/spawn-preview-contract.mjs +12 -1
- package/packages/client/spawn-preview.mjs +2 -0
- package/packages/tui/README.md +2 -2
- package/packages/tui/lib/client.mjs +6 -2
- package/packages/tui/lib/main.mjs +44 -11
- package/packages/tui/lib/model.mjs +101 -43
- package/packages/tui/lib/panel.mjs +23 -13
- package/packages/tui/lib/store.mjs +76 -20
- package/packages/tui/lib/views/frame.mjs +2 -0
- package/packages/tui/lib/views/help.mjs +2 -0
- package/packages/tui/lib/views/instances.mjs +38 -1
- package/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** The "same work" flag (feature instance-same-work, awebai/oats#1577): a child instance's declared
|
|
2
|
+
* "same work as my parent", which clients draw as the parent→child line. A home file of its own,
|
|
3
|
+
* `<home>/.oats-same-work.json`, so that a start, restart, stop or resume, which rewrite instance.json,
|
|
4
|
+
* never lose it; only `oats instance same-work … off` or retirement removes it.
|
|
5
|
+
*
|
|
6
|
+
* The flag is BOUND to the parent it was set against: the record names that parent, and the flag is on
|
|
7
|
+
* only while it is still the home's recorded `parentInstance` (sameWorkOf, the one rule). A reparent (a
|
|
8
|
+
* retire's relink, a `--relation parent` spawn re-pointing its anchor) leaves the record bound to the
|
|
9
|
+
* old name, so the flag reads off and nothing errors.
|
|
10
|
+
*
|
|
11
|
+
* The record is `{ sameWorkApi: 1, parent, at }`, written atomically (writeThroughPrivateFile) at mode
|
|
12
|
+
* 0600; present means on. A reader takes a regular file only, without following a link, up to
|
|
13
|
+
* RECORD_MAX bytes: anything that is not a valid record reads as no binding (null), never an error.
|
|
14
|
+
* Dependency-free: the status rows, spawn and the command all go through here. */
|
|
15
|
+
import { lstatSync, rmSync } from "node:fs";
|
|
16
|
+
import { join } from "node:path";
|
|
17
|
+
import { readFileHead } from "./bounded-read.mjs";
|
|
18
|
+
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
19
|
+
|
|
20
|
+
/** The record's own version. */
|
|
21
|
+
export const SAME_WORK_API = 1;
|
|
22
|
+
/** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
|
|
23
|
+
* fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
|
|
24
|
+
export const SAME_WORK_FILE = ".oats-same-work.json";
|
|
25
|
+
/** A record larger than this is not one. */
|
|
26
|
+
export const RECORD_MAX = 4096;
|
|
27
|
+
|
|
28
|
+
/** The parent `home`'s record is bound to, or null: no file, not a regular file (a link is never
|
|
29
|
+
* followed), over RECORD_MAX bytes, unreadable, not JSON, another sameWorkApi or no non-empty string
|
|
30
|
+
* `parent`. Never throws. */
|
|
31
|
+
export function readSameWork(home) {
|
|
32
|
+
try {
|
|
33
|
+
const { bytes, size } = readFileHead(join(home, SAME_WORK_FILE), RECORD_MAX + 1);
|
|
34
|
+
if (size > RECORD_MAX) return null;
|
|
35
|
+
const record = JSON.parse(bytes.toString("utf8"));
|
|
36
|
+
if (!record || typeof record !== "object" || Array.isArray(record) || record.sameWorkApi !== SAME_WORK_API) return null;
|
|
37
|
+
return typeof record.parent === "string" && record.parent !== "" ? record.parent : null;
|
|
38
|
+
} catch { return null; }
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Bind `home`'s flag to `parent` (an instance name), or remove the record when `parent` is null.
|
|
42
|
+
* → `{ changed }`. A record already bound to `parent` is no change: nothing is written. One bound to
|
|
43
|
+
* another (old) parent is rewritten to this one. A removal takes whatever stands at the name (an
|
|
44
|
+
* unreadable file, a link, a directory) and is a change only when a valid record was there. The caller
|
|
45
|
+
* decided `parent` (the home's recorded parentInstance) and holds the right to change the home. */
|
|
46
|
+
export function writeSameWork(home, parent, { now = () => new Date() } = {}) {
|
|
47
|
+
if (parent !== null && (typeof parent !== "string" || parent === "")) throw new TypeError("writeSameWork: parent is an instance name or null");
|
|
48
|
+
const path = join(home, SAME_WORK_FILE);
|
|
49
|
+
const before = readSameWork(home);
|
|
50
|
+
if (parent !== null && before === parent) return { changed: false };
|
|
51
|
+
let present;
|
|
52
|
+
try { present = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
|
|
53
|
+
// A directory at the name is no record, and a rename cannot replace it: it goes first. A link or a
|
|
54
|
+
// file is replaced by the rename itself, or removed here when the flag is cleared.
|
|
55
|
+
if (present && (parent === null || present.isDirectory())) rmSync(path, { recursive: true, force: true });
|
|
56
|
+
if (parent === null) return { changed: before !== null };
|
|
57
|
+
const bytes = JSON.stringify({ sameWorkApi: SAME_WORK_API, parent, at: now().toISOString() }) + "\n";
|
|
58
|
+
writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
|
|
59
|
+
return { changed: true };
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** THE rule: whether `home` does the same work as its parent, read against the row's current
|
|
63
|
+
* `parentInstance` (a non-empty string, else false): true only when the record is bound to exactly it. */
|
|
64
|
+
export function sameWorkOf(home, parentInstance) {
|
|
65
|
+
if (typeof parentInstance !== "string" || parentInstance === "") return false;
|
|
66
|
+
return readSameWork(home) === parentInstance;
|
|
67
|
+
}
|
package/lib/instance-upgrade.mjs
CHANGED
|
@@ -38,6 +38,7 @@ import {
|
|
|
38
38
|
retirementHomeChanged,
|
|
39
39
|
rebaseUpgradeRetirementBaseline,
|
|
40
40
|
planInstanceResources,
|
|
41
|
+
orderInstructionBlocks,
|
|
41
42
|
findRetirementBaseline,
|
|
42
43
|
officialPackageCatalog,
|
|
43
44
|
} from "./core.mjs";
|
|
@@ -639,6 +640,7 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
|
|
|
639
640
|
const resolution = {
|
|
640
641
|
resolutionApi: 1,
|
|
641
642
|
modules,
|
|
643
|
+
instructionOrder: recordedInstructionOrder(meta, modules),
|
|
642
644
|
payloads: meta.providers || {},
|
|
643
645
|
payloadOrigins: Object.fromEntries(
|
|
644
646
|
(meta.capabilityRuntime || []).map((c) => [
|
|
@@ -855,6 +857,7 @@ function derivedMetadata(p, tx, receipt) {
|
|
|
855
857
|
path: block.file,
|
|
856
858
|
materialized: true,
|
|
857
859
|
});
|
|
860
|
+
orderInstructionBlocks(expected, outcome.blocks);
|
|
858
861
|
const composition = {
|
|
859
862
|
...meta.composition,
|
|
860
863
|
expected: expected.map((r) => ({
|
|
@@ -945,6 +948,21 @@ function derivedMetadata(p, tx, receipt) {
|
|
|
945
948
|
resolutionRevision: resolution.revision,
|
|
946
949
|
};
|
|
947
950
|
}
|
|
951
|
+
/** The home's capability-block order, from the `instructions` it recorded (its AGENTS.md as
|
|
952
|
+
* spawned or last upgraded); a module with no recorded block follows, by name. An upgrade
|
|
953
|
+
* keeps that order, and the kernel's blocks close the recomposed AGENTS.md. */
|
|
954
|
+
function recordedInstructionOrder(meta, modules) {
|
|
955
|
+
const names = modules.map((m) => m.name),
|
|
956
|
+
order = [];
|
|
957
|
+
for (const row of Array.isArray(meta.instructions) ? meta.instructions : []) {
|
|
958
|
+
const name =
|
|
959
|
+
typeof row?.source === "string" && row.source.startsWith("capability:")
|
|
960
|
+
? row.source.slice("capability:".length)
|
|
961
|
+
: null;
|
|
962
|
+
if (name && names.includes(name) && !order.includes(name)) order.push(name);
|
|
963
|
+
}
|
|
964
|
+
return [...order, ...names.filter((n) => !order.includes(n)).sort()];
|
|
965
|
+
}
|
|
948
966
|
function keepPrevious(home, receipt, meta) {
|
|
949
967
|
const root = join(home, ".oats/previous");
|
|
950
968
|
if (existsSync(root)) realDir(root);
|
package/lib/materialize.mjs
CHANGED
|
@@ -107,6 +107,15 @@ function assertResolution(resolution) {
|
|
|
107
107
|
if (resolution.skills !== undefined && !Array.isArray(resolution.skills)) throw bad("/skills", "must be an array when present");
|
|
108
108
|
if (resolution.injects !== undefined && !Array.isArray(resolution.injects)) throw bad("/injects", "must be an array when present");
|
|
109
109
|
if (resolution.payloads !== undefined && !plainObject(resolution.payloads)) throw bad("/payloads", "must be an object when present");
|
|
110
|
+
if (resolution.instructionOrder !== undefined) {
|
|
111
|
+
if (!Array.isArray(resolution.instructionOrder)) throw bad("/instructionOrder", "must be an array of module names when present");
|
|
112
|
+
const listed = new Set();
|
|
113
|
+
resolution.instructionOrder.forEach((name, i) => {
|
|
114
|
+
if (!seen.has(name)) throw bad(`/instructionOrder/${i}`, `names no module (found ${JSON.stringify(name)})`);
|
|
115
|
+
if (listed.has(name)) throw bad(`/instructionOrder/${i}`, `lists module ${JSON.stringify(name)} twice`);
|
|
116
|
+
listed.add(name);
|
|
117
|
+
});
|
|
118
|
+
}
|
|
110
119
|
return resolution;
|
|
111
120
|
}
|
|
112
121
|
|
|
@@ -317,6 +326,14 @@ function moduleInjects(resolution, module, moduleDir) {
|
|
|
317
326
|
return rels;
|
|
318
327
|
}
|
|
319
328
|
|
|
329
|
+
/** Capability blocks (`capability:<module>`, built in module order) in `resolution.instructionOrder`;
|
|
330
|
+
* a module the order does not list keeps its place after the listed ones. Stable within a module. */
|
|
331
|
+
function instructionOrdered(resolution, blocks) {
|
|
332
|
+
const order = Array.isArray(resolution.instructionOrder) ? resolution.instructionOrder : [];
|
|
333
|
+
const rank = (b) => { const i = order.indexOf(b.source.slice("capability:".length)); return i < 0 ? order.length : i; };
|
|
334
|
+
return blocks.map((b, i) => ({ b, i, r: rank(b) })).sort((x, y) => x.r - y.r || x.i - y.i).map(({ b }) => b);
|
|
335
|
+
}
|
|
336
|
+
|
|
320
337
|
/* ───────────────────────────── home ─────────────────────────────── */
|
|
321
338
|
|
|
322
339
|
function assertHome(home) {
|
|
@@ -371,10 +388,14 @@ function ensureOatsDir(home) {
|
|
|
371
388
|
* lock oats-lock.json v3 object: package repo/path/commit for from.kind === "package"
|
|
372
389
|
* catalog { <id>: { url, ref, path } } for lock entries whose source is "catalog:<id>"
|
|
373
390
|
* soulAgentsMd the soul's canonical AGENTS.md text (else read from options.soulDir)
|
|
374
|
-
* blocks pre-rendered blocks [{ source, file, content }] placed
|
|
391
|
+
* blocks pre-rendered blocks [{ source, file, content }] placed AFTER the capability injects
|
|
375
392
|
* (the kernel's own kernel:… and work-mode:… blocks, composed by core.mjs)
|
|
376
393
|
* now() ISO timestamp source (tests)
|
|
377
394
|
*
|
|
395
|
+
* The AGENTS.md is the soul's body, then each module's inject in `resolution.instructionOrder`
|
|
396
|
+
* (the soul's listing, then the workspace defaults' order; a module the order omits follows, in
|
|
397
|
+
* module order), then `blocks`. `outcome.blocks` lists every block in that written order.
|
|
398
|
+
*
|
|
378
399
|
* stageMaterialize adds `replace` (complete roots), `staging` (explicit scratch
|
|
379
400
|
* directory), `existingModules` (name → frozen source path), and `instanceJson`
|
|
380
401
|
* (derived metadata transform). Its commit({preserveOnFailure:true}) retains
|
|
@@ -544,7 +565,7 @@ export async function stageMaterialize(resolution, home, options = {}) {
|
|
|
544
565
|
moduleRows.push({ name: module.name, from, commit: source.commit, digest, files: fetched.files ?? null, bytes: fetched.bytes ?? null, path: finalModule, materializedAt: at });
|
|
545
566
|
}
|
|
546
567
|
|
|
547
|
-
const blocks = [...(Array.isArray(options.blocks) ? options.blocks : [])
|
|
568
|
+
const blocks = [...instructionOrdered(resolution, capabilityBlocks), ...(Array.isArray(options.blocks) ? options.blocks : [])];
|
|
548
569
|
for (const b of blocks) {
|
|
549
570
|
if (!plainObject(b) || typeof b.source !== "string" || typeof b.file !== "string" || typeof b.content !== "string") {
|
|
550
571
|
throw fail("E_MATERIALIZE_RESOLUTION", "options.blocks entries must be { source, file, content } strings", { block: b });
|
package/lib/resolve.mjs
CHANGED
|
@@ -367,6 +367,30 @@ export function composeCapabilities(workspace, soulDefinition, { offs = null } =
|
|
|
367
367
|
return [...map.values()].sort((a, b) => byCodepoint(a.name, b.name));
|
|
368
368
|
}
|
|
369
369
|
|
|
370
|
+
/**
|
|
371
|
+
* The order a soul's capability instructions take in its composed AGENTS.md: the capabilities the soul
|
|
372
|
+
* lists, in its `capabilities:` order, then the workspace defaults it does not list, in the order the
|
|
373
|
+
* workspace's `defaults:` lists them (slot defaults and `defaults.capabilities` entries as they appear in
|
|
374
|
+
* the file). Each capability sits where the entry that composed it (its `via`) lists it, so a soul entry
|
|
375
|
+
* that re-lists a default sits at the soul's position. A name made only of digits comes first in its map
|
|
376
|
+
* (JavaScript orders integer-like keys first): a documented quirk. `declared` is composeCapabilities' output,
|
|
377
|
+
* over the same workspace and soul definition. → [name], every declared name once.
|
|
378
|
+
*/
|
|
379
|
+
export function instructionOrder(workspace, soulDefinition, declared) {
|
|
380
|
+
const viaOf = new Map(declared.map((d) => [d.name, d.via]));
|
|
381
|
+
const order = [];
|
|
382
|
+
const take = (entries, via) => {
|
|
383
|
+
for (const name of Object.keys(isObject(entries) ? entries : {})) if (viaOf.get(name) === via && !order.includes(name)) order.push(name);
|
|
384
|
+
};
|
|
385
|
+
take(soulDefinition?.capabilities, "soul");
|
|
386
|
+
const defaults = isObject(workspace?.defaults) ? workspace.defaults : {};
|
|
387
|
+
for (const key of Object.keys(defaults)) {
|
|
388
|
+
if (key === "capabilities") take(defaults.capabilities, "defaults.capabilities");
|
|
389
|
+
else if (SLOTS.includes(key)) take(defaults[key], `defaults.${key}`);
|
|
390
|
+
}
|
|
391
|
+
return order;
|
|
392
|
+
}
|
|
393
|
+
|
|
370
394
|
/* ───────────────────────────── lookups ────────────────────────────────── */
|
|
371
395
|
|
|
372
396
|
/** A discovery's member row by key (the first with that key; lib/workspace.mjs memberRowByKey). */
|
|
@@ -603,7 +627,7 @@ export function lockedCapability(name, id, entry, capabilities, details = { capa
|
|
|
603
627
|
* options: { local, lock, spawn = { providers? }, catalog, remote, remoteOptions }
|
|
604
628
|
* `catalog` (package-catalog.json shape) tells which repo a `catalog:<id>` lock entry is read from.
|
|
605
629
|
*
|
|
606
|
-
* → Resolution { resolutionApi: 1, soul, modules[], slots, payloads, payloadOrigins, skills[], injects[], revision } — deep-frozen.
|
|
630
|
+
* → Resolution { resolutionApi: 1, soul, modules[], slots, payloads, payloadOrigins, skills[], injects[], instructionOrder[], revision } — deep-frozen.
|
|
607
631
|
* Extra fields beyond the contract (recorded for materialize): module.dir (capability dir, repo-relative)
|
|
608
632
|
* and from.repoKey on package modules.
|
|
609
633
|
*/
|
|
@@ -627,9 +651,9 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
|
|
|
627
651
|
// What the soul turned off (feature desktop-facts): its own `off` over a lower layer, and a `<slot>: none`
|
|
628
652
|
// that dropped a workspace default below. Provenance, like slotsFrom.
|
|
629
653
|
const offs = [];
|
|
630
|
-
const
|
|
631
|
-
|
|
632
|
-
|
|
654
|
+
const composedWorkspace = discovery?.standalone === true ? null : workspace;
|
|
655
|
+
const composedSoul = discovery?.standalone === true ? { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities } : definition;
|
|
656
|
+
const declared = composeCapabilities(composedWorkspace, composedSoul, { offs });
|
|
633
657
|
const turnedOff = offs;
|
|
634
658
|
|
|
635
659
|
const modules = [];
|
|
@@ -816,8 +840,11 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
|
|
|
816
840
|
// `capabilitiesFrom` (the same per composed capability) and `turnedOff` (feature desktop-facts).
|
|
817
841
|
const teams = reportRows(soulTeamsHere.teams), defaultTeam = soulTeamsHere.defaultTeam;
|
|
818
842
|
const capabilitiesFrom = Object.fromEntries(modules.map((m) => [m.name, fromOfVia(viaOf.get(m.name))]));
|
|
843
|
+
// `instructionOrder` (the order the modules' injects take in the composed AGENTS.md: the soul's listing,
|
|
844
|
+
// then the workspace defaults' file order) is provenance too: reordering a soul's list is no composition change.
|
|
845
|
+
const order = instructionOrder(composedWorkspace, composedSoul, declared).filter((name) => moduleNames.has(name));
|
|
819
846
|
turnedOff.sort((a, b) => byCodepoint(a.name, b.name));
|
|
820
|
-
return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, defaultTeam, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision });
|
|
847
|
+
return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, defaultTeam, slotsFrom, capabilitiesFrom, instructionOrder: order, turnedOff, declRevision, payloadRevision, revision });
|
|
821
848
|
}
|
|
822
849
|
|
|
823
850
|
/** Where a composed capability came from, as the Desktop names it (`layers.<layer>.from`): the soul's own
|
package/lib/servers.mjs
CHANGED
|
@@ -675,6 +675,11 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
675
675
|
if (oatsArgs.includes("--suggest-name")) requireRemoteFeature(remote, target, preview ? "spawn-suggest-name" : "spawn-apply-suggest-name");
|
|
676
676
|
// An exact name is the host's to take: a host without spawn-name would refuse the flag, or worse.
|
|
677
677
|
if (oatsArgs.includes("--name")) requireRemoteFeature(remote, target, "spawn-name");
|
|
678
|
+
// Feature instance-background: an older host would refuse the flag as unknown, or place the instance
|
|
679
|
+
// in the main list; either is said here, before anything is sent.
|
|
680
|
+
if (oatsArgs.includes("--background") || oatsArgs.includes("--no-background")) requireRemoteFeature(remote, target, "instance-background");
|
|
681
|
+
// A host without instance-same-work would refuse the flag as unknown: it is never sent there.
|
|
682
|
+
if (oatsArgs.includes("--same-work")) requireRemoteFeature(remote, target, "instance-same-work");
|
|
678
683
|
const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
|
|
679
684
|
if (preview && envelope.ok && envelope.result?.preview === true && envelope.result.spawnPreviewApi === 2) {
|
|
680
685
|
// The host's preview with the two fields a routed spawn adds; never a
|
|
@@ -819,6 +824,10 @@ const HOST_SURFACES = {
|
|
|
819
824
|
"retire plan": { feature: "lifecycle-plans", api: "lifecycleApi", version: 1 },
|
|
820
825
|
// Feature instance-color: the feature alone (its answer's instanceColorApi is not a probe key).
|
|
821
826
|
"instance color": { feature: "instance-color" },
|
|
827
|
+
// Feature instance-background: the same (its answer's instanceBackgroundApi is not a probe key).
|
|
828
|
+
"instance background": { feature: "instance-background" },
|
|
829
|
+
// Feature instance-same-work: the feature alone, as instance color.
|
|
830
|
+
"instance same-work": { feature: "instance-same-work" },
|
|
822
831
|
};
|
|
823
832
|
|
|
824
833
|
function requireSurface(remote, target, surface) {
|
|
@@ -827,7 +836,7 @@ function requireSurface(remote, target, surface) {
|
|
|
827
836
|
}
|
|
828
837
|
}
|
|
829
838
|
|
|
830
|
-
/** `readiness`, `instance events|git|diff|stop|color` and `retire --plan` on the
|
|
839
|
+
/** `readiness`, `instance events|git|diff|stop|color|background|same-work` and `retire --plan` on the
|
|
831
840
|
* host: the instance is addressed as every routed session command addresses
|
|
832
841
|
* it (its name through a saved route or the host's roster, or an exact
|
|
833
842
|
* --home), the scope is an explicit --dir on the host or the registered
|
|
@@ -836,7 +845,7 @@ function requireSurface(remote, target, surface) {
|
|
|
836
845
|
function routeHostSurface(serverId, cmd, oatsArgs, io) {
|
|
837
846
|
const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
|
|
838
847
|
const surface = HOST_SURFACES[key];
|
|
839
|
-
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop and
|
|
848
|
+
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background and same-work only (not ${key})`);
|
|
840
849
|
const args = [...oatsArgs];
|
|
841
850
|
const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
|
|
842
851
|
const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
|
|
@@ -891,13 +900,19 @@ const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k,
|
|
|
891
900
|
* omits it, and absent ("not reported") must stay distinct from null ("no claim"). The
|
|
892
901
|
* value passes the kernel's own read rule again; anything it refuses is null. */
|
|
893
902
|
const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: readWaitingClaim(i.waitingOnYou) } : {});
|
|
894
|
-
/** `
|
|
903
|
+
/** `background` (feature instance-background) only as `true`, relayed ONLY when the host's row says exactly
|
|
904
|
+
* that: absent is the only reading of "not background", so any other value is dropped, never false. */
|
|
905
|
+
const rowBackground = (i) => (i.background === true ? { background: true } : {});
|
|
906
|
+
/** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
|
|
895
907
|
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
896
908
|
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
897
909
|
const rowRetire = (i) => {
|
|
898
910
|
const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
|
|
899
911
|
return retire ? { retire } : {};
|
|
900
912
|
};
|
|
913
|
+
/** `sameWork` (feature instance-same-work) as `background`: relayed ONLY when the host's row says
|
|
914
|
+
* `sameWork: true`, the one value a row carries; anything else, and a host that omits it, is absent. */
|
|
915
|
+
const rowSameWork = (i) => (i.sameWork === true ? { sameWork: true } : {});
|
|
901
916
|
|
|
902
917
|
/** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
|
|
903
918
|
export const HOST_FEATURES_MAX = 256;
|
|
@@ -1000,7 +1015,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1000
1015
|
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
|
|
1001
1016
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1002
1017
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1003
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i),
|
|
1018
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i),
|
|
1004
1019
|
// Every row the host reports is addressed by its home, saved
|
|
1005
1020
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1006
1021
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
|
@@ -26,6 +26,7 @@ export const ROW_REASON = Object.freeze({
|
|
|
26
26
|
UNKNOWN: "unknown", START_BUSY: "start-busy", NOT_LOST: "not-lost", NOT_SEEN_RECENTLY: "not-seen-recently",
|
|
27
27
|
RESUME_CONFIRMATION: RESUME_WAITING.RESUME_CONFIRMATION, LAUNCH_PROMPT: "launch-prompt",
|
|
28
28
|
START_REFUSED: "start-refused", REFUSED_THIS_BOOT: "refused-this-boot", KEEPS_GETTING_LOST: "keeps-getting-lost",
|
|
29
|
+
LIFECYCLE_BUSY: "lifecycle-busy",
|
|
29
30
|
});
|
|
30
31
|
|
|
31
32
|
/** `deployments[].reason` of a deployment the sweep did not sweep. */
|
package/lib/session-resume.mjs
CHANGED
|
@@ -35,7 +35,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writ
|
|
|
35
35
|
import { join, resolve } from "node:path";
|
|
36
36
|
import { oatsError } from "./errors.mjs";
|
|
37
37
|
import { deploymentState, readDeploymentsDocument } from "./deployments.mjs";
|
|
38
|
-
import { listInstances, missingLaunchEnvRefs, resumeConversation } from "./core.mjs";
|
|
38
|
+
import { homeClaimHolder, listInstances, missingLaunchEnvRefs, owedRetireSaid, resumeConversation } from "./core.mjs";
|
|
39
39
|
import { checkStartEnv, fromEnvNames, launchEnvChangedMessage, launchEnvMissingMessage, launchEnvUnverifiedWarning } from "./start-env.mjs";
|
|
40
40
|
import { FRESH_REASON, NOT_SWEPT, OUTCOME, RESUME_WAITING, ROW_REASON, SESSION_END } from "./session-resume-contract.mjs";
|
|
41
41
|
import { bootId, homeKey, judgeLosses, readSeen, resumeEligible, resumeStateDir } from "./session-seen.mjs";
|
|
@@ -158,11 +158,12 @@ function readDeployment(dir) {
|
|
|
158
158
|
return { entry: { deployment: dir, state, swept: true }, rows };
|
|
159
159
|
}
|
|
160
160
|
|
|
161
|
-
/** The reasons of the rows a sweep answers without judging the loss, so that a later
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
* it
|
|
165
|
-
|
|
161
|
+
/** The reasons of the rows a sweep answers without judging the loss, so that a later sweep may
|
|
162
|
+
* resume it: a home OATS was stopping, upgrading or retiring (`lifecycle-busy`), whose next state
|
|
163
|
+
* is that command's to decide. A loop guard's refusal (`keeps-getting-lost`) judges the loss like
|
|
164
|
+
* any refusal, and nothing brings it back automatically, a reboot included (decided for #1567);
|
|
165
|
+
* naming it here would let the next boot retry it. */
|
|
166
|
+
const NOT_JUDGED = new Set([ROW_REASON.LIFECYCLE_BUSY]);
|
|
166
167
|
/** The outcomes of a start that launched something: the ones RESUME_LIMIT counts. */
|
|
167
168
|
const LAUNCHED = new Set([OUTCOME.RESUMED, OUTCOME.FRESH, OUTCOME.BLOCKED]);
|
|
168
169
|
const base = (row) => ({ deployment: row.deployment, instance: row.instance, home: row.home });
|
|
@@ -192,6 +193,9 @@ export function rowFromStart(row, answer) {
|
|
|
192
193
|
const message = String(answer?.error?.message ?? "the start gave no answer");
|
|
193
194
|
if (code === "E_SPAWN_INCOMPLETE") return { ...base(row), outcome: OUTCOME.BLOCKED, reason: ROW_REASON.LAUNCH_PROMPT, code, ...(answer.error.details?.launchPrompts ? { launchPrompts: answer.error.details.launchPrompts } : {}) };
|
|
194
195
|
if (code === "E_SESSION_START_BUSY") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.START_BUSY, code };
|
|
196
|
+
// The home's lifecycle claim was held, or its retire is owed: whatever OATS is doing decides the
|
|
197
|
+
// home's next state. Not a refusal: none is noted, judged or counted against the loop guard.
|
|
198
|
+
if (code === "E_INSTANCE_RETIRING" || code === "E_LIFECYCLE_BUSY") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.LIFECYCLE_BUSY, code, message };
|
|
195
199
|
if (code === "E_RESUME_NOT_LOST" || code === "E_SESSION_RUNNING") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_LOST, code };
|
|
196
200
|
if (code === "E_SESSION_UNKNOWN") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.UNKNOWN, code, message };
|
|
197
201
|
return { ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.START_REFUSED, code, message };
|
|
@@ -242,7 +246,9 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
|
|
|
242
246
|
for (const row of found ?? []) {
|
|
243
247
|
if (row.running === true) rows.push({ ...base(row), outcome: OUTCOME.ALREADY_RUNNING });
|
|
244
248
|
else if (row.running === null) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.UNKNOWN });
|
|
245
|
-
|
|
249
|
+
// A launched home that is owed a self-retire reads no sessionEnd (its marker withholds it):
|
|
250
|
+
// it is listed as the lost ones are, so that the sweep says it is skipped (lifecycleBusy).
|
|
251
|
+
else if (row.sessionEnd === SESSION_END.LOST || (row.retirePending && row.launched === true && row.running === false)) candidates.push(row);
|
|
246
252
|
}
|
|
247
253
|
}
|
|
248
254
|
const note = readBootNote(boot), now = Date.now();
|
|
@@ -250,11 +256,16 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
|
|
|
250
256
|
// Precedence, the first that applies: not seen recently, refused this boot, keeps getting lost,
|
|
251
257
|
// started. The record and the note name a home by its real path (homeKey), whatever spelling the
|
|
252
258
|
// sweep was given; a row shows the path it listed.
|
|
259
|
+
// A home OATS is stopping, upgrading or retiring, or whose retire is owed, comes first: nothing
|
|
260
|
+
// is started there. This read is only a filter (the sweep is not atomic with it): the start's
|
|
261
|
+
// own claim is what keeps a resume off such a home (lib/core.mjs startInstanceSession).
|
|
253
262
|
for (const row of candidates) {
|
|
254
263
|
const startId = row.startId ?? null, key = homeKey(row.home);
|
|
255
264
|
const prior = note.refused.find((r) => r.home === key && (r.startId ?? null) === startId);
|
|
256
265
|
const fit = resumeEligible(seen.get(key), row, { now });
|
|
257
|
-
|
|
266
|
+
const busy = lifecycleBusy(row);
|
|
267
|
+
if (busy) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.LIFECYCLE_BUSY, message: busy });
|
|
268
|
+
else if (!fit.eligible) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_SEEN_RECENTLY, message: `${row.instance} is not resumed automatically: ${fit.why}; start it by hand (oats session start --resume --home ${row.home}) if it should run` });
|
|
258
269
|
else if (prior) rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.REFUSED_THIS_BOOT, code: prior.code, message: prior.message });
|
|
259
270
|
else if ((note.resumes[key] ?? 0) >= RESUME_LIMIT) rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.KEEPS_GETTING_LOST, message: `${row.instance} was resumed ${note.resumes[key]} times in this boot and was lost again each time; no sweep starts this loss again: start it by hand (oats session start --resume --home ${row.home})` });
|
|
260
271
|
else if (plan) rows.push(predicted(row, env));
|
|
@@ -269,7 +280,11 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
|
|
|
269
280
|
const started = (await inBatches(toStart, RESUME_CONCURRENCY, async (row) => {
|
|
270
281
|
const answer = await start(row);
|
|
271
282
|
for (const w of hostWarnings(answer)) hostWide.add(w);
|
|
272
|
-
|
|
283
|
+
// A home removed between the read and its start (a retire finished in between) is not lost:
|
|
284
|
+
// whatever its start answered.
|
|
285
|
+
const gone = answer?.ok !== true && !existsSync(row.home);
|
|
286
|
+
const answered = gone ? { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_LOST, ...(typeof answer?.error?.code === "string" ? { code: answer.error.code } : {}) } : rowFromStart(row, answer);
|
|
287
|
+
const key = homeKey(row.home);
|
|
273
288
|
try {
|
|
274
289
|
noteSweep({
|
|
275
290
|
refusals: answered.outcome === OUTCOME.REFUSED ? [{ home: key, startId: row.startId ?? null, code: answered.code, message: answered.message, at: new Date().toISOString() }] : [],
|
|
@@ -292,6 +307,18 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
|
|
|
292
307
|
} finally { release?.(); }
|
|
293
308
|
}
|
|
294
309
|
|
|
310
|
+
/** Why a lost home's status row says OATS is stopping, upgrading or retiring it, or that its
|
|
311
|
+
* retire is owed, as one line; null when it says none of that. Read only: the row's `retire` (any
|
|
312
|
+
* value: running, unknown, failed, interrupted) or `retirePending`, then the holder of the home's lifecycle claim,
|
|
313
|
+
* alive or of a liveness that cannot be read (homeClaimHolder). A holder that is gone is not one:
|
|
314
|
+
* the start takes its claim over. */
|
|
315
|
+
function lifecycleBusy(row) {
|
|
316
|
+
if (row.retire || row.retirePending) return owedRetireSaid(row.instance, row.retire?.state ?? "unknown");
|
|
317
|
+
const held = homeClaimHolder(row.home);
|
|
318
|
+
if (!held || held.state === "gone") return null;
|
|
319
|
+
return `${row.instance} is held by ${held.state === "alive" ? "a" : "what may still be a"} ${held.action} (${held.lock}); that command decides what the home is next`;
|
|
320
|
+
}
|
|
321
|
+
|
|
295
322
|
/** `--plan`'s prediction for a lost home, from what its start would check, read only: refused for a
|
|
296
323
|
* home with no recipe, a reference not set in `env` (the environment each start gets) or one whose
|
|
297
324
|
* value changed since the start it would bring back (lib/start-env.mjs, the start's own check), else
|
package/lib/soul-composition.mjs
CHANGED
|
@@ -3,10 +3,11 @@
|
|
|
3
3
|
*
|
|
4
4
|
* It runs spawn's own two halves: the kernel half (composeInstanceAgentsMd: the soul's
|
|
5
5
|
* AGENTS.md, the instance-boundary and work-mode blocks) and materialize (each capability's
|
|
6
|
-
* inject
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
6
|
+
* inject, in the resolution's instruction order, before the kernel's blocks), into a scratch
|
|
7
|
+
* home OUTSIDE the deployment that is removed before it returns (and at exit). Nothing in the
|
|
8
|
+
* deployment is written. Capability blocks are reported home-relative
|
|
9
|
+
* (`.oats/modules/<cap>/<inject>`, where an instance carries them); kernel blocks keep the
|
|
10
|
+
* installed package's absolute path, as spawn writes them.
|
|
10
11
|
*
|
|
11
12
|
* Single-path guard: the reported text is re-rendered by renderInstructionParts (for the
|
|
12
13
|
* ranges), so rendering the same parts with the scratch paths must give back, byte for byte,
|
|
@@ -66,10 +67,13 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
|
|
|
66
67
|
const remove = () => { try { rmSync(scratch, { recursive: true, force: true }); } catch { /* best effort: a temporary copy only */ } };
|
|
67
68
|
process.once("exit", remove);
|
|
68
69
|
try {
|
|
69
|
-
const
|
|
70
|
+
const kernelBlocks = composition.blocks.filter((b) => !b.source.startsWith("capability:"));
|
|
71
|
+
const outcome = await materialize({ ...prepared, soulAgentsMd: body, blocks: kernelBlocks, soulDir }, scratch);
|
|
70
72
|
const written = readFileSync(join(scratch, "AGENTS.md"), "utf8");
|
|
71
|
-
|
|
72
|
-
|
|
73
|
+
// The capability blocks materialize reported, in its order; the kernel's blocks close the document.
|
|
74
|
+
const isKernel = (b) => kernelBlocks.some((k) => k.source === b.source && k.file === b.file);
|
|
75
|
+
const materialized = (Array.isArray(outcome?.blocks) ? outcome.blocks : []).filter((b) => !isKernel(b));
|
|
76
|
+
if (renderInstructionParts(body, [...materialized, ...kernelBlocks]).text !== written) {
|
|
73
77
|
throw fail("E_COMPOSITION_INCOMPLETE", `soul "${soulName}": the instructions materialize wrote are not the kernel's composition plus the capability blocks it reported; nothing is reported in their place`);
|
|
74
78
|
}
|
|
75
79
|
const homeRelative = (file) => {
|
|
@@ -78,10 +82,9 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
|
|
|
78
82
|
return rel.split(sep).join("/");
|
|
79
83
|
};
|
|
80
84
|
const capabilityBlocks = materialized.map((b) => ({ source: b.source, file: homeRelative(b.file), content: b.content, materialized: true }));
|
|
81
|
-
const blocks = [...
|
|
85
|
+
const blocks = [...capabilityBlocks, ...kernelBlocks];
|
|
82
86
|
const parts = renderInstructionParts(body, blocks);
|
|
83
87
|
const length = Math.min(parts.text.length, cap);
|
|
84
|
-
const kernelBlocks = composition.blocks.length;
|
|
85
88
|
const scratchResult = inScratch ? await inScratch({ outcome, scratch }) : undefined;
|
|
86
89
|
return {
|
|
87
90
|
text: parts.text, blocks, resolved: composition.resolved, oatsCoreDeclared: composition.oatsCoreDeclared, scratchResult,
|
|
@@ -89,7 +92,7 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
|
|
|
89
92
|
file: null, text: parts.text.slice(0, length), truncated: parts.text.length > length,
|
|
90
93
|
resolution: prepared.resolution?.revision ?? null,
|
|
91
94
|
body: clampSpan(parts.body, length),
|
|
92
|
-
sources: parts.blocks.map((span, i) => ({ source: blocks[i].source, file: i <
|
|
95
|
+
sources: parts.blocks.map((span, i) => ({ source: blocks[i].source, file: i < capabilityBlocks.length ? blocks[i].file : null, ...clampSpan(span, length) })),
|
|
93
96
|
},
|
|
94
97
|
};
|
|
95
98
|
} catch (e) {
|
package/lib/workspace.mjs
CHANGED
|
@@ -964,10 +964,10 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
|
|
|
964
964
|
// even when the workspace (and its defaults) cannot be read. ANY mention of
|
|
965
965
|
// oats.core in the soul — `{ from: package }`, `{ from: here }`, `{ from: <repo> }`
|
|
966
966
|
// or `off` — suppresses the kernel default: the soul's own choice is then judged
|
|
967
|
-
// by the loop below exactly like every other capability (S4).
|
|
967
|
+
// by the loop below exactly like every other capability (S4). The default is added
|
|
968
|
+
// after the soul's own entries, so its instructions follow theirs, as any default's do.
|
|
968
969
|
const kept = {};
|
|
969
970
|
const declaredCaps = soul.definition.capabilities || {};
|
|
970
|
-
if (!Object.hasOwn(declaredCaps, STANDALONE_DEFAULT_CAPABILITY)) kept[STANDALONE_DEFAULT_CAPABILITY] = { from: "package" };
|
|
971
971
|
for (const [name, choice] of Object.entries(declaredCaps)) {
|
|
972
972
|
const from = isObject(choice) ? choice.from : null;
|
|
973
973
|
if (choice === "off") continue;
|
|
@@ -983,6 +983,7 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
|
|
|
983
983
|
problems.push({ code: "E_NOT_A_MEMBER", repoKey: key, path: `${soul.path}/soul.yaml#/capabilities/${pointerKey(name)}`, message: `${show(name)} comes from ${show(from)}, which cannot be confirmed as a member without the workspace` });
|
|
984
984
|
}
|
|
985
985
|
}
|
|
986
|
+
if (!Object.hasOwn(declaredCaps, STANDALONE_DEFAULT_CAPABILITY)) kept[STANDALONE_DEFAULT_CAPABILITY] = { from: "package" };
|
|
986
987
|
return { ...soul, capabilities: kept };
|
|
987
988
|
});
|
|
988
989
|
return {
|
package/package-catalog.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v5.
|
|
6
|
+
"ref": "v5.5.0",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
@@ -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.16.0",
|
|
32
32
|
"path": "oats-package"
|
|
33
33
|
},
|
|
34
34
|
"oats.cloning": {
|
|
@@ -48,7 +48,7 @@
|
|
|
48
48
|
},
|
|
49
49
|
"oats.framework": {
|
|
50
50
|
"url": "https://github.com/awebai/oats.git",
|
|
51
|
-
"ref": "oats-framework/v1.
|
|
51
|
+
"ref": "oats-framework/v1.16.1",
|
|
52
52
|
"path": "oats-package"
|
|
53
53
|
}
|
|
54
54
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.69.
|
|
3
|
+
"version": "0.69.3",
|
|
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",
|
|
@@ -124,6 +124,11 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
|
|
|
124
124
|
if (typeof opts.yolo !== "boolean") throw Object.assign(new Error("yolo must be a boolean"), { code: "E_BAD_ARGS" });
|
|
125
125
|
argv.push(opts.yolo ? "--yolo" : "--no-yolo");
|
|
126
126
|
}
|
|
127
|
+
// Run in background (feature instance-background, #1579): the instance's own flag, as the soul's default or not.
|
|
128
|
+
if (opts.background !== undefined) {
|
|
129
|
+
if (typeof opts.background !== "boolean") throw Object.assign(new Error("background must be a boolean"), { code: "E_BAD_ARGS" });
|
|
130
|
+
argv.push(opts.background ? "--background" : "--no-background");
|
|
131
|
+
}
|
|
127
132
|
if (opts.suggestName) argv.push("--suggest-name");
|
|
128
133
|
argv.push("--json");
|
|
129
134
|
return argv;
|
|
@@ -648,22 +653,39 @@ export function operationArgs(args) {
|
|
|
648
653
|
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;
|
|
649
654
|
return entries.flatMap(([k, v]) => ['--arg', `${k}=${v}`]);
|
|
650
655
|
}
|
|
651
|
-
/**
|
|
652
|
-
* (
|
|
653
|
-
*
|
|
654
|
-
*
|
|
655
|
-
*
|
|
656
|
-
|
|
656
|
+
/** A verb that writes one field of an instance's own record: `oats instance <verb> <instance> <values…> --home <home>
|
|
657
|
+
* (--dir <context> | --server <server>) --json`, addressed as `oats instance stop` is (lifecycle-cli.mjs: a routed
|
|
658
|
+
* command never carries --dir). Shared by `instance color` and `instance background` (server/instance-record.mjs);
|
|
659
|
+
* each checks its own value first. Anything out of shape is refused here and nothing runs. A read's deadline:
|
|
660
|
+
* 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
|
|
661
|
+
function runInstanceRecord(bin, { instance, home, context, server }, verb, values, io) {
|
|
657
662
|
const fail = code => ({ schemaVersion: 1, ok: false, error: { code } });
|
|
658
663
|
if (typeof bin !== "string" || !isAbsolute(bin) || typeof instance !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(instance)
|
|
659
|
-
|| typeof home !== "string" || !isAbsolute(home) || home.includes("\0")
|
|
664
|
+
|| typeof home !== "string" || !isAbsolute(home) || home.includes("\0")
|
|
660
665
|
|| (server !== undefined ? !/^[a-z0-9][a-z0-9-]{0,63}$/.test(server ?? "") : typeof context !== "string" || !isAbsolute(context))) return fail("E_BAD_ARGS");
|
|
661
|
-
const argv = ["instance",
|
|
666
|
+
const argv = ["instance", verb, instance, ...values, "--home", home,
|
|
662
667
|
...(server !== undefined ? ["--server", server] : ["--dir", context]), "--json"];
|
|
663
668
|
const limit = server !== undefined ? 45_000 : 30_000;
|
|
664
669
|
return runJson(bin, argv, { cwd: server !== undefined ? io.cwd : context, exec: io.exec, strictExit: true,
|
|
665
670
|
timeout: Number.isFinite(io.timeout) && io.timeout > 0 ? Math.min(io.timeout, limit) : limit });
|
|
666
671
|
}
|
|
672
|
+
const instanceRecordRefused = () => ({ schemaVersion: 1, ok: false, error: { code: "E_BAD_ARGS" } });
|
|
673
|
+
/** An instance's colour (feature instance-color, awebai/oats#1421 §2): `oats instance color <instance>
|
|
674
|
+
* (<color> | --clear) …` (runInstanceRecord). `color` is a palette name (soul-colors.mjs SOUL_COLORS) or null to
|
|
675
|
+
* clear; anything else is refused here and nothing runs. */
|
|
676
|
+
export async function cliInstanceColor(bin, args, io = {}) {
|
|
677
|
+
const { color } = args;
|
|
678
|
+
if (!(color === null || SOUL_COLORS.includes(color))) return instanceRecordRefused();
|
|
679
|
+
return runInstanceRecord(bin, args, "color", color === null ? ["--clear"] : [color], io);
|
|
680
|
+
}
|
|
681
|
+
/** Whether an instance runs in the background (feature instance-background, awebai/oats#1579): `oats instance
|
|
682
|
+
* background <instance> (on | off) …` (runInstanceRecord). `background` is a boolean; anything else is refused
|
|
683
|
+
* here and nothing runs. Over `--server`, a host without the feature refuses it (E_REMOTE_INCOMPATIBLE). */
|
|
684
|
+
export async function cliInstanceBackground(bin, args, io = {}) {
|
|
685
|
+
const { background } = args;
|
|
686
|
+
if (typeof background !== "boolean") return instanceRecordRefused();
|
|
687
|
+
return runInstanceRecord(bin, args, "background", [background ? "on" : "off"], io);
|
|
688
|
+
}
|
|
667
689
|
|
|
668
690
|
/** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
|
|
669
691
|
* gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
|