@awebai/oats 0.67.1 → 0.68.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +112 -16
- package/docs/capabilities.md +54 -5
- package/docs/capability-manifest.schema.json +4 -0
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +248 -9
- package/docs/desktop.md +278 -61
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +42 -3
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +625 -223
- package/docs/upgrading.md +62 -6
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +6 -5
- package/lib/core.mjs +222 -38
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-resolution.mjs +5 -5
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +225 -78
- package/lib/servers.mjs +11 -7
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +15 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-panel.mjs +6 -2
- package/packages/client/keymap.mjs +89 -45
- package/packages/client/keys-file.mjs +9 -5
- package/packages/client/panel-views.mjs +16 -3
- package/packages/client/spawn-naming.mjs +7 -6
- package/packages/client/spawn-preview-cli.mjs +37 -1
- package/packages/client/spawn-preview-contract.mjs +35 -0
- package/packages/client/spawn-preview.mjs +35 -2
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +5 -5
- package/packages/tui/lib/actions.mjs +51 -27
- package/packages/tui/lib/client.mjs +3 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +132 -19
- package/packages/tui/lib/store.mjs +343 -68
- package/packages/tui/lib/term/keys.mjs +5 -3
- package/packages/tui/lib/term/kitty.mjs +28 -10
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +33 -28
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +56 -34
- package/packages/tui/lib/views/instances.mjs +4 -2
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +92 -43
package/lib/materialize.mjs
CHANGED
|
@@ -23,7 +23,10 @@
|
|
|
23
23
|
* rollback journal: should any step fail, everything already placed is undone and the
|
|
24
24
|
* previous AGENTS.md / instance.json restored before a named error (E_MATERIALIZE_HOME)
|
|
25
25
|
* propagates. A second materialization racing on the same home surfaces as
|
|
26
|
-
* E_MATERIALIZE_HOME { why: "busy" }, never a raw ENOTEMPTY.
|
|
26
|
+
* E_MATERIALIZE_HOME { why: "busy" }, never a raw ENOTEMPTY. stageMaterialize exposes
|
|
27
|
+
* that same composer before commit, including complete-root replacement for stopped
|
|
28
|
+
* homes. Its durable rename journal can finish forward after provider adoption; ordinary
|
|
29
|
+
* materialize calls continue to roll back a failed commit and discard staging.
|
|
27
30
|
*
|
|
28
31
|
* SOURCES. A module is fetched from its repository at `from.commit` at the capability
|
|
29
32
|
* directory the RESOLVER recorded (`module.dir`: the manifest-listed directory — for a
|
|
@@ -186,15 +189,20 @@ function moduleSource(module, { lock, catalog, remote }) {
|
|
|
186
189
|
/* ───────────────────────────── copying ─────────────────────────────── */
|
|
187
190
|
|
|
188
191
|
/** Full copy of a fetched tree: regular files and directories only, exec bit preserved as 0o755 / 0o644. */
|
|
189
|
-
function copyTree(src, dest, shownRoot) {
|
|
192
|
+
function copyTree(src, dest, shownRoot, allowAliases = false, root = src) {
|
|
190
193
|
const st = lstatSync(src);
|
|
191
194
|
if (st.isSymbolicLink()) throw fail("E_REMOTE_TREE_UNSAFE", `${shownRoot} is a symlink`, { path: shownRoot, why: "symlink" });
|
|
192
195
|
if (!st.isDirectory()) throw fail("E_MATERIALIZE_RESOLUTION", `${shownRoot} is not a directory`, { path: shownRoot });
|
|
193
196
|
mkdirSync(dest, { recursive: true, mode: 0o755 });
|
|
194
197
|
for (const name of readdirSync(src).sort()) {
|
|
195
198
|
const from = join(src, name), to = join(dest, name), shown = `${shownRoot}/${name}`, s = lstatSync(from);
|
|
196
|
-
if (s.isSymbolicLink())
|
|
197
|
-
|
|
199
|
+
if (s.isSymbolicLink()) {
|
|
200
|
+
if (allowAliases && defaultRemote.OATS_ALIAS_SYMLINK(relative(root, from).split(sep).join("/")) && readlinkSync(from) === "AGENTS.md") {
|
|
201
|
+
symlinkSync("AGENTS.md", to); continue;
|
|
202
|
+
}
|
|
203
|
+
throw fail("E_REMOTE_TREE_UNSAFE", `${shown} is a symlink`, { path: shown, why: "symlink" });
|
|
204
|
+
}
|
|
205
|
+
if (s.isDirectory()) { copyTree(from, to, shown, allowAliases, root); continue; }
|
|
198
206
|
if (!s.isFile()) throw fail("E_REMOTE_TREE_UNSAFE", `${shown} is not a regular file`, { path: shown, why: "device" });
|
|
199
207
|
copyFileSync(from, to);
|
|
200
208
|
chmodSync(to, (s.mode & 0o111) ? 0o755 : 0o644);
|
|
@@ -366,8 +374,29 @@ function ensureOatsDir(home) {
|
|
|
366
374
|
* blocks pre-rendered blocks [{ source, file, content }] placed BEFORE the capability injects
|
|
367
375
|
* (the kernel's own kernel:… and work-mode:… blocks, composed by core.mjs)
|
|
368
376
|
* now() ISO timestamp source (tests)
|
|
377
|
+
*
|
|
378
|
+
* stageMaterialize adds `replace` (complete roots), `staging` (explicit scratch
|
|
379
|
+
* directory), `existingModules` (name → frozen source path), and `instanceJson`
|
|
380
|
+
* (derived metadata transform). Its commit({preserveOnFailure:true}) retains
|
|
381
|
+
* forward progress and can be reopened with {staging, resume:true}. Add
|
|
382
|
+
* retainStaging:true until the caller has durably recorded its remaining lifecycle steps.
|
|
369
383
|
*/
|
|
370
384
|
export async function materialize(resolution, home, options = {}) {
|
|
385
|
+
const transaction = await stageMaterialize(resolution, home, options);
|
|
386
|
+
return transaction.commit();
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/** Build the same composition as spawn without publishing it. Replacement transactions
|
|
390
|
+
* swap complete module/skill roots; a caller holds the lifecycle claim while using them.
|
|
391
|
+
* `staging` may be outside the home for a read-only preview. `resume` reopens a staged
|
|
392
|
+
* transaction after an interrupted forward-only commit; no resolution or fetch is needed.
|
|
393
|
+
* `existingModules` names verified frozen copies to retain instead of fetching them.
|
|
394
|
+
* `instanceJson(merged, outcome)` supplies the caller's derived metadata; updateInstance
|
|
395
|
+
* can subsequently record provider hook results before commit. rollback() restores
|
|
396
|
+
* a retained swap when no provider hook has adopted the new version.
|
|
397
|
+
*/
|
|
398
|
+
export async function stageMaterialize(resolution, home, options = {}) {
|
|
399
|
+
if (options.resume) return resumeMaterialization(home, options.staging);
|
|
371
400
|
assertResolution(resolution);
|
|
372
401
|
const homeAbs = assertHome(home);
|
|
373
402
|
const remote = options.remote ?? defaultRemote;
|
|
@@ -380,7 +409,12 @@ export async function materialize(resolution, home, options = {}) {
|
|
|
380
409
|
const { lock, catalog } = options;
|
|
381
410
|
|
|
382
411
|
// Everything that can be decided without touching the network or the disk, first.
|
|
383
|
-
const sources = resolution.modules.map((m) =>
|
|
412
|
+
const sources = resolution.modules.map((m) => {
|
|
413
|
+
const existing = Object.hasOwn(options.existingModules ?? {}, m.name) ? options.existingModules[m.name] : undefined;
|
|
414
|
+
return { module: m, existing,
|
|
415
|
+
source: existing ? { commit: m.from.commit, key: m.from.repoKey } : moduleSource(m, { lock, catalog, remote }),
|
|
416
|
+
};
|
|
417
|
+
});
|
|
384
418
|
const body = soulBody(homeAbs, options);
|
|
385
419
|
const instanceFile = join(homeAbs, "instance.json");
|
|
386
420
|
const previous = readInstanceJson(instanceFile);
|
|
@@ -398,13 +432,13 @@ export async function materialize(resolution, home, options = {}) {
|
|
|
398
432
|
const target = join(modulesRoot, module.name);
|
|
399
433
|
let st = null;
|
|
400
434
|
try { st = lstatSync(target); } catch {}
|
|
401
|
-
if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
|
|
435
|
+
if (st && !options.replace) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
|
|
402
436
|
}
|
|
403
437
|
for (const owner of skillOwners.values()) {
|
|
404
438
|
const name = owner.name, target = join(skillsRoot, name);
|
|
405
439
|
let st = null;
|
|
406
440
|
try { st = lstatSync(target); } catch {}
|
|
407
|
-
if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries a skill named ${name}; materialize never overwrites a skill in place`, { home: homeAbs, module: owner.module, skill: name, path: target });
|
|
441
|
+
if (st && !options.replace) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries a skill named ${name}; materialize never overwrites a skill in place`, { home: homeAbs, module: owner.module, skill: name, path: target });
|
|
408
442
|
}
|
|
409
443
|
for (const p of parents) {
|
|
410
444
|
let st = null;
|
|
@@ -419,33 +453,39 @@ export async function materialize(resolution, home, options = {}) {
|
|
|
419
453
|
};
|
|
420
454
|
assertHomeShape();
|
|
421
455
|
|
|
422
|
-
const oats = ensureOatsDir(homeAbs);
|
|
456
|
+
const oats = options.staging ? { dir: join(homeAbs, ".oats"), created: false } : ensureOatsDir(homeAbs);
|
|
423
457
|
// Unique per call: two materializations of one home in one process (or across processes) never share staging.
|
|
424
|
-
const staging = join(oats.dir, `.staging-${process.pid}-${randomBytes(6).toString("hex")}`);
|
|
458
|
+
const staging = options.staging ? resolve(options.staging) : join(oats.dir, `.staging-${process.pid}-${randomBytes(6).toString("hex")}`);
|
|
459
|
+
assertStagingPath(staging, homeAbs);
|
|
460
|
+
if (linkPresent(staging)) throw fail("E_MATERIALIZE_HOME", `staging directory ${staging} already exists; resume it explicitly or choose another path`, { path: staging, why: "busy" });
|
|
461
|
+
let stagingOwned = false;
|
|
425
462
|
const discard = () => {
|
|
426
|
-
try { rmSync(staging, { recursive: true, force: true }); } catch { /* an unremovable staging dir must not mask the original error */ }
|
|
463
|
+
try { if (stagingOwned) rmSync(staging, { recursive: true, force: true }); } catch { /* an unremovable staging dir must not mask the original error */ }
|
|
427
464
|
if (oats.created) { try { rmdirSync(oats.dir); } catch { /* something else appeared; leave it */ } }
|
|
428
465
|
};
|
|
429
|
-
/** A real directory at `p` (mkdir without following a symlink; EEXIST on a non-directory → refusal). */
|
|
430
|
-
const ensureDir = (p) => {
|
|
431
|
-
try { mkdirSync(p, { mode: 0o755 }); }
|
|
432
|
-
catch (e) {
|
|
433
|
-
if (e?.code !== "EEXIST") throw e;
|
|
434
|
-
if (!lstatSync(p).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${p} exists and is not a directory`, { home: homeAbs, path: p, why: "not-a-directory" });
|
|
435
|
-
}
|
|
436
|
-
};
|
|
437
466
|
|
|
438
467
|
let outcome;
|
|
439
468
|
try {
|
|
440
|
-
mkdirSync(
|
|
441
|
-
|
|
469
|
+
try { mkdirSync(staging, { mode: 0o755 }); }
|
|
470
|
+
catch (e) {
|
|
471
|
+
if (e?.code === "EEXIST") throw fail("E_MATERIALIZE_HOME", `${staging} appeared while materializing`, { path: staging, why: "busy" });
|
|
472
|
+
throw e;
|
|
473
|
+
}
|
|
474
|
+
stagingOwned = true;
|
|
475
|
+
mkdirSync(join(staging, "modules"), { mode: 0o755 });
|
|
476
|
+
mkdirSync(join(staging, "skills"), { mode: 0o755 });
|
|
442
477
|
|
|
443
478
|
const moduleRows = [], skillRows = [], capabilityBlocks = [], recorded = {};
|
|
444
|
-
for (const { module, source } of sources) {
|
|
479
|
+
for (const { module, source, existing } of sources) {
|
|
445
480
|
const stagedModule = join(staging, "modules", module.name);
|
|
446
481
|
const finalModule = join(modulesRoot, module.name);
|
|
447
482
|
let fetched;
|
|
448
|
-
try {
|
|
483
|
+
try {
|
|
484
|
+
if (existing) {
|
|
485
|
+
copyTree(existing, stagedModule, module.name, true);
|
|
486
|
+
fetched = { digest: remote.contentDigest(stagedModule, { allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK }) };
|
|
487
|
+
} else fetched = await fetch(source.ref, source.commit, source.dir, stagedModule, { ...(options.remoteOptions || {}), allowSymlinks: defaultRemote.OATS_ALIAS_SYMLINK });
|
|
488
|
+
}
|
|
449
489
|
catch (e) {
|
|
450
490
|
if (e?.code === "E_REMOTE_PATH_MISSING") {
|
|
451
491
|
throw fail("E_CAPABILITY_MISSING", `module ${module.name}: ${source.dir} is not present in ${source.key}@${source.commit.slice(0, 12)}`,
|
|
@@ -468,9 +508,10 @@ export async function materialize(resolution, home, options = {}) {
|
|
|
468
508
|
throw fail("E_MATERIALIZE_INTEGRITY", `module ${module.name}: the copy digests ${digest} but the fetch reported ${fetched.digest}`,
|
|
469
509
|
{ module: module.name, repoKey: source.key, commit: source.commit, expected: fetched.digest, actual: digest, why: "copy" });
|
|
470
510
|
}
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
511
|
+
const expectedDigest = module.digest ?? (existing ? previous.modules?.[module.name]?.digest : null);
|
|
512
|
+
if (expectedDigest && expectedDigest !== digest) {
|
|
513
|
+
throw fail("E_MATERIALIZE_INTEGRITY", `module ${module.name}: content digest ${digest} does not match the recorded ${expectedDigest}`,
|
|
514
|
+
{ module: module.name, repoKey: source.key, commit: source.commit, expected: expectedDigest, actual: digest, why: "resolution" });
|
|
474
515
|
}
|
|
475
516
|
|
|
476
517
|
for (const skill of moduleSkills(resolution, module, stagedModule)) {
|
|
@@ -498,7 +539,8 @@ export async function materialize(resolution, home, options = {}) {
|
|
|
498
539
|
|
|
499
540
|
const at = now();
|
|
500
541
|
const from = clone(module.from);
|
|
501
|
-
recorded[module.name] =
|
|
542
|
+
recorded[module.name] = existing && previous.modules?.[module.name]?.digest === digest && previous.modules[module.name].commit === source.commit
|
|
543
|
+
? clone(previous.modules[module.name]) : { from, commit: source.commit, digest, materializedAt: at };
|
|
502
544
|
moduleRows.push({ name: module.name, from, commit: source.commit, digest, files: fetched.files ?? null, bytes: fetched.bytes ?? null, path: finalModule, materializedAt: at });
|
|
503
545
|
}
|
|
504
546
|
|
|
@@ -511,65 +553,170 @@ export async function materialize(resolution, home, options = {}) {
|
|
|
511
553
|
const agentsText = renderInstructionText(body.text, blocks);
|
|
512
554
|
writeFileSync(join(staging, "AGENTS.md"), agentsText, { mode: 0o644 });
|
|
513
555
|
|
|
514
|
-
|
|
556
|
+
let merged = { ...previous, modules: recorded, providers: clone(resolution.payloads ?? {}) };
|
|
515
557
|
if (typeof resolution.revision === "string" && resolution.revision) merged.resolutionRevision = resolution.revision;
|
|
558
|
+
outcome = { modules: moduleRows, skills: skillRows, agentsMd: join(homeAbs, "AGENTS.md"), instanceJson: merged, blocks };
|
|
559
|
+
if (typeof options.instanceJson === "function") merged = options.instanceJson(merged, outcome);
|
|
560
|
+
if (!plainObject(merged)) throw fail("E_MATERIALIZE_RESOLUTION", "options.instanceJson must return an object");
|
|
561
|
+
outcome.instanceJson = merged;
|
|
516
562
|
writeFileSync(join(staging, "instance.json"), JSON.stringify(merged, null, 2) + "\n", { mode: 0o644 });
|
|
563
|
+
const state = { api: 1, home: homeAbs, replace: options.replace === true, outcome, operations: [], initialParents: [".claude", SKILLS_DIR, ".agents", MODULES_DIR].filter(p => linkPresent(join(homeAbs, p))) };
|
|
564
|
+
saveMaterialization(staging, state);
|
|
565
|
+
return materializationTransaction(staging, state, { assertHomeShape, discard });
|
|
566
|
+
} catch (error) {
|
|
567
|
+
discard();
|
|
568
|
+
throw error;
|
|
569
|
+
}
|
|
570
|
+
}
|
|
517
571
|
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
};
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
572
|
+
const TRANSACTION_FILE = ".materialize-transaction.json";
|
|
573
|
+
|
|
574
|
+
/** Refuse path aliases before creating or reopening staging. Staging cannot cover the
|
|
575
|
+
* home itself or any published composition path. Ancestors inside the home must be
|
|
576
|
+
* real directories; system ancestors such as macOS /tmp may be directory aliases. */
|
|
577
|
+
function assertStagingPath(staging, home) {
|
|
578
|
+
if (!isAbsolute(staging) || staging === home || relative(staging, home).split(sep)[0] !== "..") {
|
|
579
|
+
throw fail("E_MATERIALIZE_HOME", `unsafe staging directory ${staging}`, { path: staging });
|
|
580
|
+
}
|
|
581
|
+
if ([".oats", ".agents", ".claude", "AGENTS.md", "instance.json", "CLAUDE.md"].some(p => join(home, p) === staging)) throw fail("E_MATERIALIZE_HOME", `staging directory overlaps the home composition: ${staging}`, { path: staging });
|
|
582
|
+
for (const published of [join(home, MODULES_DIR), join(home, SKILLS_DIR)]) {
|
|
583
|
+
const rel = relative(published, staging);
|
|
584
|
+
if (!rel || (!rel.startsWith(`..${sep}`) && rel !== "..")) throw fail("E_MATERIALIZE_HOME", `staging directory is inside ${published}`, { path: staging });
|
|
585
|
+
}
|
|
586
|
+
let at = resolve(staging, "..");
|
|
587
|
+
const insideHome = !relative(home, staging).startsWith(`..${sep}`);
|
|
588
|
+
while (insideHome && at !== home) {
|
|
589
|
+
if (linkPresent(at) && !lstatSync(at).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${at} exists and is not a directory`, { path: at });
|
|
590
|
+
const parent = resolve(at, "..");
|
|
591
|
+
if (parent === at) break;
|
|
592
|
+
at = parent;
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
function saveMaterialization(staging, state) {
|
|
597
|
+
const file = join(staging, TRANSACTION_FILE), temp = `${file}.tmp`;
|
|
598
|
+
writeFileSync(temp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
|
|
599
|
+
renameSync(temp, file);
|
|
600
|
+
}
|
|
601
|
+
|
|
602
|
+
function resumeMaterialization(home, stagingPath) {
|
|
603
|
+
const homeAbs = assertHome(home);
|
|
604
|
+
if (typeof stagingPath !== "string" || !isAbsolute(stagingPath)) throw fail("E_MATERIALIZE_HOME", "resuming materialization requires an absolute staging path");
|
|
605
|
+
const staging = resolve(stagingPath);
|
|
606
|
+
assertStagingPath(staging, homeAbs);
|
|
607
|
+
if (!lstatSync(staging).isDirectory() || !lstatSync(join(staging, TRANSACTION_FILE)).isFile()) throw fail("E_MATERIALIZE_HOME", `invalid materialization staging directory ${staging}`);
|
|
608
|
+
const state = readInstanceJson(join(staging, TRANSACTION_FILE));
|
|
609
|
+
if (state.api !== 1 || state.home !== homeAbs || typeof state.replace !== "boolean" || !plainObject(state.outcome) || !Array.isArray(state.outcome.modules) || !Array.isArray(state.outcome.skills) || !Array.isArray(state.operations)) throw fail("E_MATERIALIZE_HOME", `invalid materialization transaction in ${staging}`);
|
|
610
|
+
return materializationTransaction(staging, state);
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
/** A durable intent before each rename makes an interrupted swap distinguishable from
|
|
614
|
+
* a pending one. Forward-only failures keep both copies and retry the remaining moves;
|
|
615
|
+
* ordinary spawn failures reverse the same journal and discard staging. */
|
|
616
|
+
function materializationTransaction(staging, state, callbacks = {}) {
|
|
617
|
+
const home = state.home, outcome = state.outcome;
|
|
618
|
+
const discard = callbacks.discard ?? (() => { try { rmSync(staging, { recursive: true, force: true }); } catch { /* cleanup must not turn success into rollback */ } });
|
|
619
|
+
let committed = false;
|
|
620
|
+
const operations = () => state.replace
|
|
621
|
+
? [{ label: "modules", dest: join(home, MODULES_DIR) }, { label: "skills", dest: join(home, SKILLS_DIR) }, { label: "AGENTS.md", dest: join(home, "AGENTS.md") }, { label: "instance.json", dest: join(home, "instance.json") }]
|
|
622
|
+
: [...outcome.modules.map(m => ({ label: `modules/${safeName(m.name)}`, dest: join(home, MODULES_DIR, m.name) })),
|
|
623
|
+
...outcome.skills.map(s => ({ label: `skills/${safeName(s.name)}`, dest: join(home, SKILLS_DIR, s.name) })),
|
|
624
|
+
{ label: "AGENTS.md", dest: join(home, "AGENTS.md") }, { label: "instance.json", dest: join(home, "instance.json") }];
|
|
625
|
+
const allowedLabels = new Set(operations().map(op => op.label));
|
|
626
|
+
if (state.operations.some(op => !plainObject(op) || !allowedLabels.has(op.label) || typeof op.had !== "boolean" || !["pending", "backed", "placed"].includes(op.phase)) ||
|
|
627
|
+
(state.aliases !== undefined && (!Array.isArray(state.aliases) || state.aliases.some(alias => !["CLAUDE.md", ".claude/skills"].includes(alias))))) {
|
|
628
|
+
throw fail("E_MATERIALIZE_HOME", `invalid materialization journal in ${staging}`, { path: staging });
|
|
629
|
+
}
|
|
630
|
+
const ensureDir = (p) => {
|
|
631
|
+
if (linkPresent(p)) {
|
|
632
|
+
if (!lstatSync(p).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${p} exists and is not a directory`, { path: p });
|
|
633
|
+
} else mkdirSync(p, { mode: 0o755 });
|
|
634
|
+
};
|
|
635
|
+
const checkParents = () => {
|
|
636
|
+
for (const p of [join(home, ".oats"), join(home, ".agents"), join(home, ".claude")]) ensureDir(p);
|
|
637
|
+
for (const p of [join(home, MODULES_DIR), join(home, SKILLS_DIR)]) if (linkPresent(p) && !lstatSync(p).isDirectory()) throw fail("E_MATERIALIZE_HOME", `${p} exists and is not a directory`, { path: p });
|
|
638
|
+
if (!state.replace) { ensureDir(join(home, MODULES_DIR)); ensureDir(join(home, SKILLS_DIR)); }
|
|
639
|
+
};
|
|
640
|
+
const safeBackup = (label) => join(staging, "previous", ...label.split("/"));
|
|
641
|
+
const safeSource = (label) => join(staging, ...label.split("/"));
|
|
642
|
+
const updateInstance = (json) => {
|
|
643
|
+
if (!plainObject(json) || state.operations.length || committed) throw fail("E_MATERIALIZE_HOME", "instance metadata can only be updated before the materialization swap");
|
|
644
|
+
outcome.instanceJson = clone(json);
|
|
645
|
+
writeFileSync(join(staging, "instance.json"), JSON.stringify(json, null, 2) + "\n", { mode: 0o644 });
|
|
646
|
+
saveMaterialization(staging, state);
|
|
647
|
+
};
|
|
648
|
+
const rollback = ({ suppressErrors = false } = {}) => {
|
|
649
|
+
if (!linkPresent(staging)) throw fail("E_MATERIALIZE_HOME", "materialization staging is gone; rollback requires retainStaging:true", { path: staging });
|
|
650
|
+
const failures = [];
|
|
651
|
+
for (const alias of state.aliases ?? []) {
|
|
652
|
+
try { rmSync(join(home, alias), { force: true }); } catch (e) { failures.push(e.message); }
|
|
653
|
+
}
|
|
654
|
+
for (const op of operations().reverse()) {
|
|
655
|
+
const saved = state.operations.find(row => row.label === op.label);
|
|
656
|
+
if (!saved) continue;
|
|
657
|
+
const src = safeSource(op.label), backup = safeBackup(op.label);
|
|
658
|
+
try {
|
|
659
|
+
if (!linkPresent(src) && linkPresent(op.dest)) { mkdirSync(resolve(src, ".."), { recursive: true }); renameSync(op.dest, src); }
|
|
660
|
+
if (linkPresent(backup)) renameSync(backup, op.dest);
|
|
661
|
+
} catch (e) { failures.push(e.message); }
|
|
662
|
+
}
|
|
663
|
+
// Only remove parents created by this materialization, and only if empty.
|
|
664
|
+
for (const rel of [".claude", SKILLS_DIR, ".agents", MODULES_DIR]) {
|
|
665
|
+
try { if (!state.initialParents?.includes(rel)) rmdirSync(join(home, rel)); } catch {}
|
|
666
|
+
}
|
|
667
|
+
if (!failures.length) discard();
|
|
668
|
+
else if (!suppressErrors) throw fail("E_MATERIALIZE_HOME", `cannot fully roll back materialization; staging retained at ${staging}: ${failures.join("; ")}`, { path: staging, why: "rollback" });
|
|
669
|
+
committed = false;
|
|
670
|
+
};
|
|
671
|
+
const commit = ({ preserveOnFailure = false, retainStaging = false } = {}) => {
|
|
672
|
+
if (committed) return outcome;
|
|
547
673
|
try {
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
674
|
+
// Spawn retains its original pre-commit race checks. A resumed replacement
|
|
675
|
+
// may already have published roots, so only its parent shape is checked.
|
|
676
|
+
if (!state.operations.length) callbacks.assertHomeShape?.();
|
|
677
|
+
checkParents();
|
|
678
|
+
for (const op of operations()) {
|
|
679
|
+
let saved = state.operations.find(row => row.label === op.label);
|
|
680
|
+
const src = safeSource(op.label), backup = safeBackup(op.label);
|
|
681
|
+
if (!saved) {
|
|
682
|
+
saved = { label: op.label, had: linkPresent(op.dest), phase: "pending" };
|
|
683
|
+
if (!state.replace && (op.label.startsWith("modules/") || op.label.startsWith("skills/")) && saved.had) throw fail("E_MATERIALIZE_HOME", `${op.dest} appeared while materializing`, { path: op.dest, why: "busy" });
|
|
684
|
+
state.operations.push(saved); saveMaterialization(staging, state);
|
|
685
|
+
}
|
|
686
|
+
if (saved.phase === "pending") {
|
|
687
|
+
if (saved.had && !linkPresent(backup)) {
|
|
688
|
+
mkdirSync(resolve(backup, ".."), { recursive: true });
|
|
689
|
+
renameSync(op.dest, backup);
|
|
690
|
+
}
|
|
691
|
+
saved.phase = "backed"; saveMaterialization(staging, state);
|
|
692
|
+
}
|
|
693
|
+
if (saved.phase === "backed") {
|
|
694
|
+
if (linkPresent(src)) {
|
|
695
|
+
if (linkPresent(op.dest)) throw fail("E_MATERIALIZE_HOME", `${op.dest} appeared while materializing`, { path: op.dest, why: "busy" });
|
|
696
|
+
renameSync(src, op.dest);
|
|
697
|
+
}
|
|
698
|
+
else if (!linkPresent(op.dest)) throw fail("E_MATERIALIZE_HOME", `staged materialization is missing ${src}`, { path: src });
|
|
699
|
+
saved.phase = "placed"; saveMaterialization(staging, state);
|
|
700
|
+
}
|
|
562
701
|
}
|
|
563
|
-
|
|
702
|
+
const claudeMd = join(home, "CLAUDE.md"), claudeSkills = join(home, ".claude", "skills");
|
|
703
|
+
if (!linkPresent(claudeMd)) { symlinkSync("AGENTS.md", claudeMd); state.aliases = [...(state.aliases ?? []), "CLAUDE.md"]; saveMaterialization(staging, state); }
|
|
704
|
+
if (!linkPresent(claudeSkills)) { symlinkSync(join("..", ".agents", "skills"), claudeSkills); state.aliases = [...(state.aliases ?? []), ".claude/skills"]; saveMaterialization(staging, state); }
|
|
705
|
+
committed = true;
|
|
706
|
+
if (!retainStaging) discard();
|
|
707
|
+
return outcome;
|
|
708
|
+
} catch (error) {
|
|
709
|
+
if (!preserveOnFailure) rollback({ suppressErrors: true });
|
|
710
|
+
if (["EACCES", "EPERM", "EROFS", "EISDIR", "ENOTDIR"].includes(error?.code)) throw fail("E_MATERIALIZE_HOME", `cannot write the instance home ${home}: ${error.message}`, { home, why: "unwritable", cause: error.code });
|
|
711
|
+
throw error;
|
|
564
712
|
}
|
|
565
|
-
|
|
713
|
+
};
|
|
714
|
+
return { outcome, staging, commit, discard, rollback, updateInstance };
|
|
715
|
+
}
|
|
566
716
|
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
throw error;
|
|
571
|
-
}
|
|
572
|
-
return outcome;
|
|
717
|
+
function safeName(name) {
|
|
718
|
+
if (typeof name !== "string" || !SAFE_COMPONENT_RE.test(name)) throw fail("E_MATERIALIZE_HOME", "invalid name in materialization transaction", { name });
|
|
719
|
+
return name;
|
|
573
720
|
}
|
|
574
721
|
|
|
575
722
|
/** Every entry under `dir` is a regular file or a directory (no symlinks, devices, sockets) — E_REMOTE_TREE_UNSAFE. */
|
package/lib/servers.mjs
CHANGED
|
@@ -645,11 +645,11 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
645
645
|
}
|
|
646
646
|
const remote = checkRemote(target, io);
|
|
647
647
|
// A saved route is keyed by name under its server id. An explicit name
|
|
648
|
-
// that already has one here would overwrite that
|
|
649
|
-
// before the mutation (the roster shows the
|
|
650
|
-
// retire it first).
|
|
651
|
-
const
|
|
652
|
-
const explicitName =
|
|
648
|
+
// (--name, or --instance) that already has one here would overwrite that
|
|
649
|
+
// route on success: refuse before the mutation (the roster shows the
|
|
650
|
+
// existing route; forget or retire it first).
|
|
651
|
+
const valueOf = (flag) => { const i = oatsArgs.indexOf(flag); return i >= 0 && oatsArgs[i + 1] && !oatsArgs[i + 1].startsWith("--") ? oatsArgs[i + 1] : undefined; };
|
|
652
|
+
const explicitName = valueOf("--name") ?? valueOf("--instance");
|
|
653
653
|
if (explicitName && readSnapshot(serverId, explicitName)) throw serverError("E_ROUTE_EXISTS", `a saved route for ${explicitName} through server ${serverId} already exists (${readSnapshot(serverId, explicitName).home}); retire it (oats retire ${explicitName} --server ${serverId}) or drop it (oats server forget ${serverId} --instance ${explicitName}) before spawning that name again`);
|
|
654
654
|
// The remote roster: the soul's harness default for the support check,
|
|
655
655
|
// and the remote agents root for the snapshot (the kernel's spawn result
|
|
@@ -662,8 +662,12 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
662
662
|
// spawn-preview-2 is proven to answer --preview without spawning.
|
|
663
663
|
const preview = oatsArgs.includes("--preview");
|
|
664
664
|
if (preview) requireRemoteFeature(remote, target, "spawn-preview-2");
|
|
665
|
-
// #1421 §3: the naming call runs on the host, through its routed preview.
|
|
666
|
-
|
|
665
|
+
// #1421 §3, #1490 §3: the naming call runs on the host, through its routed preview or apply. An
|
|
666
|
+
// older host is told nothing: a caller that would rather number the instance checks the host's
|
|
667
|
+
// features and does not send the flag; the route never drops it.
|
|
668
|
+
if (oatsArgs.includes("--suggest-name")) requireRemoteFeature(remote, target, preview ? "spawn-suggest-name" : "spawn-apply-suggest-name");
|
|
669
|
+
// An exact name is the host's to take: a host without spawn-name would refuse the flag, or worse.
|
|
670
|
+
if (oatsArgs.includes("--name")) requireRemoteFeature(remote, target, "spawn-name");
|
|
667
671
|
const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
|
|
668
672
|
if (preview && envelope.ok && envelope.result?.preview === true && envelope.result.spawnPreviewApi === 2) {
|
|
669
673
|
// The host's preview with the two fields a routed spawn adds; never a
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/** Read-only package-upgrade state shared by the upgrade act and session starts.
|
|
2
|
+
* Kept independent of core.mjs so checking a receipt never loads the lifecycle act. */
|
|
3
|
+
import { lstatSync, readdirSync } from "node:fs";
|
|
4
|
+
import { basename, join } from "node:path";
|
|
5
|
+
import { oatsError } from "./errors.mjs";
|
|
6
|
+
import { shellWord } from "./shell-word.mjs";
|
|
7
|
+
import { driftOf } from "./materialize.mjs";
|
|
8
|
+
import { parseStrictJson } from "./canonical-json.mjs";
|
|
9
|
+
import { readPortableBytes } from "./bounded-read.mjs";
|
|
10
|
+
import { canonicalHomePath } from "./real-path.mjs";
|
|
11
|
+
|
|
12
|
+
export const UPGRADE_RECEIPT_NAME_RE = /^upgrade-receipt\.[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\.json$/;
|
|
13
|
+
const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
14
|
+
const uncertainReceipt = (home, path) => Object.assign(oatsError("E_UPGRADE_PARTIAL", `cannot safely read package-upgrade receipt state at ${path}; cannot prove a session launch is safe. Inspect the receipt and retry its recorded upgrade command, or respawn the instance; nothing was stopped or started`), { details: { home, receipt: path } });
|
|
15
|
+
|
|
16
|
+
/** Read receipt state without following directory or receipt symlinks. A corrupt record cannot
|
|
17
|
+
* prove that provider adoption finished, so every reader refuses before lifecycle effects. */
|
|
18
|
+
export function readUpgradeReceipts(home) {
|
|
19
|
+
const directory = join(home, ".oats");
|
|
20
|
+
let before;
|
|
21
|
+
try { before = lstatSync(directory); }
|
|
22
|
+
catch (error) { if (error.code === "ENOENT") return []; throw uncertainReceipt(home, directory); }
|
|
23
|
+
if (!before.isDirectory()) throw uncertainReceipt(home, directory);
|
|
24
|
+
let names;
|
|
25
|
+
try { names = readdirSync(directory); }
|
|
26
|
+
catch { throw uncertainReceipt(home, directory); }
|
|
27
|
+
const rows = [];
|
|
28
|
+
for (const name of names.sort()) {
|
|
29
|
+
if (!UPGRADE_RECEIPT_NAME_RE.test(name)) continue;
|
|
30
|
+
const path = join(directory, name);
|
|
31
|
+
try {
|
|
32
|
+
const receipt = parseStrictJson(readPortableBytes(path));
|
|
33
|
+
const key = name.slice("upgrade-receipt.".length, -".json".length);
|
|
34
|
+
if (!object(receipt) || receipt.action !== "upgrade" || !["partial", "complete"].includes(receipt.status) || receipt.idempotencyKey !== key
|
|
35
|
+
|| (receipt.steps !== undefined && !object(receipt.steps))
|
|
36
|
+
|| ((receipt.status === "partial" || receipt.steps?.cleaned === false) && (typeof receipt.planRevision !== "string" || !receipt.planRevision.trim()))) throw new Error("invalid upgrade receipt");
|
|
37
|
+
rows.push({ path, receipt });
|
|
38
|
+
} catch { throw uncertainReceipt(home, path); }
|
|
39
|
+
}
|
|
40
|
+
try {
|
|
41
|
+
const after = lstatSync(directory);
|
|
42
|
+
if (!after.isDirectory() || after.dev !== before.dev || after.ino !== before.ino) throw new Error("receipt directory changed");
|
|
43
|
+
} catch { throw uncertainReceipt(home, directory); }
|
|
44
|
+
return rows;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function retryFor(home, receipt) {
|
|
48
|
+
const instance = typeof receipt.instance === "string" && receipt.instance ? receipt.instance : basename(home);
|
|
49
|
+
return { instance, command: `oats instance upgrade ${shellWord(instance)}${receipt.undo === true ? " --undo" : ""} --plan-revision ${shellWord(receipt.planRevision)} --idempotency-key ${shellWord(receipt.idempotencyKey)}` };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The shared start mutex is a directory for starts and a regular file for upgrades.
|
|
53
|
+
* A start never reclaims an upgrade file, even if its owner died during the initial write. */
|
|
54
|
+
export function upgradeMutexRetry(home) {
|
|
55
|
+
const path = join(home, ".oats-start.lock");
|
|
56
|
+
try { if (!lstatSync(path).isFile()) return null; }
|
|
57
|
+
catch { return null; }
|
|
58
|
+
try {
|
|
59
|
+
const owner = parseStrictJson(readPortableBytes(path));
|
|
60
|
+
if (object(owner) && owner.action === "upgrade" && owner.instance === basename(home)
|
|
61
|
+
&& typeof owner.home === "string" && canonicalHomePath(owner.home) === canonicalHomePath(home)
|
|
62
|
+
&& typeof owner.planRevision === "string" && owner.planRevision.trim()
|
|
63
|
+
&& typeof owner.idempotencyKey === "string" && UPGRADE_RECEIPT_NAME_RE.test(`upgrade-receipt.${owner.idempotencyKey}.json`)
|
|
64
|
+
&& (owner.undo === undefined || typeof owner.undo === "boolean")) return retryFor(home, owner).command;
|
|
65
|
+
} catch { /* An empty or incomplete write still belongs to the upgrade act. */ }
|
|
66
|
+
return `${retryFor(home, { planRevision: "<original-plan-revision>", idempotencyKey: "<original-idempotency-key>" }).command} (use the original revision and key, and include --undo if originally used)`;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** A provider may already have adopted host state. A partial upgrade must finish forward
|
|
70
|
+
* before any launch hook or harness runs against the home's module copies. */
|
|
71
|
+
export function assertNoPartialUpgrade(home) {
|
|
72
|
+
for (const { path, receipt } of readUpgradeReceipts(home)) {
|
|
73
|
+
if (receipt.status !== "partial") continue;
|
|
74
|
+
const { instance, command } = retryFor(home, receipt);
|
|
75
|
+
throw Object.assign(oatsError("E_UPGRADE_PARTIAL", `the package upgrade of ${instance} is partial (${path}); nothing was stopped or started. Retry ${command} to finish it; if it cannot finish, respawn the instance`), {
|
|
76
|
+
details: { home, receipt: path, instance, idempotencyKey: receipt.idempotencyKey },
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Swap and baseline already committed: launch is safe while event/cleanup finalization is retried. */
|
|
82
|
+
export function upgradeCleanupWarnings(home) {
|
|
83
|
+
return readUpgradeReceipts(home)
|
|
84
|
+
.filter(({ receipt }) => receipt.status === "complete" && receipt.steps?.cleaned === false)
|
|
85
|
+
.map(({ path, receipt }) => {
|
|
86
|
+
const { instance, command } = retryFor(home, receipt);
|
|
87
|
+
return `the package upgrade of ${instance} is complete, but staging cleanup remains (${path}); retry ${command} to finish cleanup`;
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Only package modules that can move to a different locked commit. Removed packages
|
|
92
|
+
* and member drift remain information for status; neither is offered as an upgrade. */
|
|
93
|
+
export function packageUpgradeDrift(meta, { lock } = {}) {
|
|
94
|
+
return driftOf(meta, null, { lock })
|
|
95
|
+
.filter((row) => row.from.kind === "package" && row.status === "moved")
|
|
96
|
+
.map((row) => ({
|
|
97
|
+
capability: row.module,
|
|
98
|
+
recorded: { version: row.recorded.version ?? null, commit: row.recorded.commit ?? null },
|
|
99
|
+
locked: { version: row.current.version ?? null, commit: row.current.commit ?? null },
|
|
100
|
+
}));
|
|
101
|
+
}
|
package/lib/workspace.mjs
CHANGED
|
@@ -552,6 +552,9 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
|
|
|
552
552
|
|
|
553
553
|
/* ───────────────────────────── enumeration ────────────────────────────── */
|
|
554
554
|
|
|
555
|
+
/** The conventional directory shared by discovery and reads at a recorded soul commit. */
|
|
556
|
+
export const memberSoulPath = (name) => `souls/${name}`;
|
|
557
|
+
|
|
555
558
|
const SOUL_FILE = /^([^/]+)\/soul\.yaml$/;
|
|
556
559
|
const CAP_FILE = /^([^/]+)\/oats\.json$/;
|
|
557
560
|
|
|
@@ -580,7 +583,7 @@ async function enumerateRepo(remote, ref, key, commit) {
|
|
|
580
583
|
for (const entry of await list("souls")) {
|
|
581
584
|
const m = entry.type === "blob" && SOUL_FILE.exec(entry.path);
|
|
582
585
|
if (!m) continue;
|
|
583
|
-
const path =
|
|
586
|
+
const path = memberSoulPath(m[1]);
|
|
584
587
|
const file = `${path}/soul.yaml`;
|
|
585
588
|
let bytes;
|
|
586
589
|
try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }
|