@awebai/oats 0.46.0 → 0.48.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 +70 -30
- package/docs/capabilities.md +8 -0
- package/docs/configuration.md +25 -19
- package/docs/desktop-cli-api.md +78 -14
- package/docs/desktop.md +2 -2
- package/docs/execution-targets.md +74 -2
- package/docs/implementation.md +24 -2
- package/docs/launch-prompt-completion.md +70 -0
- package/docs/official-catalog.md +4 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.47.0.md +93 -0
- package/docs/release-notes/v0.48.0.md +106 -0
- package/docs/souls-and-instances.md +20 -3
- package/docs/workspaces.md +16 -1
- package/lib/core.mjs +48 -7
- package/lib/launch-prompt-completion.mjs +67 -0
- package/lib/launch-prompt-evidence.mjs +159 -0
- package/lib/launch-prompt-fixtures/README.md +72 -4
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +88 -0
- package/lib/launch-prompt-fixtures/structural-completion.json +205 -0
- package/lib/launch-prompt-fixtures.mjs +14 -3
- package/lib/launch-prompts.mjs +25 -3
- package/lib/teams-verbs.mjs +40 -9
- package/package-catalog.json +11 -4
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +15 -4
package/bin/oats.mjs
CHANGED
|
@@ -30,7 +30,7 @@ import {
|
|
|
30
30
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
31
31
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
32
32
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
33
|
-
findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf,
|
|
33
|
+
findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
34
34
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
35
35
|
} from "../lib/core.mjs";
|
|
36
36
|
import {
|
|
@@ -53,7 +53,7 @@ import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/sched
|
|
|
53
53
|
import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
|
|
54
54
|
|
|
55
55
|
import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
|
|
56
|
-
import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
|
|
56
|
+
import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
|
|
57
57
|
import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
|
|
58
58
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
59
59
|
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
@@ -61,7 +61,7 @@ import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mj
|
|
|
61
61
|
|
|
62
62
|
const rawArgs = process.argv.slice(2);
|
|
63
63
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
64
|
-
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
|
|
64
|
+
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
|
|
65
65
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
66
66
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
67
67
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -1775,26 +1775,55 @@ async function teamsContext(bail) {
|
|
|
1775
1775
|
}
|
|
1776
1776
|
const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
|
|
1777
1777
|
|
|
1778
|
-
/** `oats teams
|
|
1779
|
-
*
|
|
1778
|
+
/** The flags each `oats teams` form takes (value flags → true), beyond the global `--dir` and `--json`.
|
|
1779
|
+
* Anything else is refused, never ignored: a kernel that ignored `--if-absent` would set unconditionally. */
|
|
1780
|
+
const TEAMS_FLAGS = {
|
|
1781
|
+
"": { "--max-age": true },
|
|
1782
|
+
add: { "--team": true, "--description": true, "--no-default": false },
|
|
1783
|
+
remove: {},
|
|
1784
|
+
default: { "--if-absent": false, "--expect": true },
|
|
1785
|
+
};
|
|
1786
|
+
/** The first flag `oats teams <sub>` does not take, or undefined. A value flag's value is skipped as flag()
|
|
1787
|
+
* reads it (the next word unless it starts with `--`). */
|
|
1788
|
+
function teamsUnknownFlag(sub) {
|
|
1789
|
+
const takes = { "--dir": true, "--json": false, ...TEAMS_FLAGS[sub ?? ""] };
|
|
1790
|
+
for (let i = 1; i < args.length; i++) {
|
|
1791
|
+
const a = args[i];
|
|
1792
|
+
if (!a.startsWith("-")) continue;
|
|
1793
|
+
if (!Object.hasOwn(takes, a)) return a;
|
|
1794
|
+
if (takes[a] && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++;
|
|
1795
|
+
}
|
|
1796
|
+
return undefined;
|
|
1797
|
+
}
|
|
1798
|
+
|
|
1799
|
+
/** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
|
|
1800
|
+
* default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
|
|
1801
|
+
* never a provider call. */
|
|
1780
1802
|
async function teamsCmd() {
|
|
1781
1803
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
1782
|
-
const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] | oats teams remove <label> | oats teams default <label> [--dir <deployment>] [--json]";
|
|
1783
|
-
|
|
1804
|
+
const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
|
|
1805
|
+
// A single-dash word (`-x`) is a flag, never the subcommand: teamsUnknownFlag names it.
|
|
1806
|
+
const sub = positional(1)?.startsWith("-") ? undefined : positional(1);
|
|
1784
1807
|
if (sub !== undefined && !["add", "remove", "default"].includes(sub)) bail("E_USAGE", usage);
|
|
1808
|
+
const unknown = teamsUnknownFlag(sub);
|
|
1809
|
+
if (unknown !== undefined) {
|
|
1810
|
+
const form = sub ? `oats teams ${sub}` : "oats teams";
|
|
1811
|
+
bail("E_USAGE", `${form} does not take ${unknown} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${usage}`, { flag: unknown });
|
|
1812
|
+
}
|
|
1785
1813
|
const label = sub ? positional(2) : undefined;
|
|
1786
1814
|
if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
|
|
1787
1815
|
const ctx = await teamsContext(bail);
|
|
1788
1816
|
const V = await import("../lib/teams-verbs.mjs");
|
|
1789
1817
|
let result = null;
|
|
1790
1818
|
try {
|
|
1791
|
-
if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description") });
|
|
1819
|
+
if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description"), noDefault: args.includes("--no-default") });
|
|
1792
1820
|
else if (sub === "remove") result = V.teamsRemove(ctx, label);
|
|
1793
|
-
else if (sub === "default") result = V.teamsDefault(ctx, label);
|
|
1821
|
+
else if (sub === "default") result = V.teamsDefault(ctx, label, { ifAbsent: args.includes("--if-absent"), expect: valueFlag("expect") });
|
|
1794
1822
|
} catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
|
|
1795
1823
|
const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
|
|
1796
|
-
if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
|
|
1797
|
-
if (result) console.log(
|
|
1824
|
+
if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed, ...(result.reused ? { reused: true } : {}) } : withObservation(doc)); return; }
|
|
1825
|
+
if (result?.reused) console.log(`Team ${label} is already declared with that id: nothing to change`);
|
|
1826
|
+
else if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
|
|
1798
1827
|
console.log(`default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
|
|
1799
1828
|
console.log(`local ${doc.localTeams === null ? "allowed (standalone)" : doc.localTeams ? "allowed (localTeams: true)" : "not allowed"}`);
|
|
1800
1829
|
if (!doc.teams.length) console.log("teams (none: `oats aweb setup` creates them, or `oats teams add <label> --team <id>`)");
|
|
@@ -2612,35 +2641,41 @@ function retireCmd() {
|
|
|
2612
2641
|
const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
|
|
2613
2642
|
if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
|
|
2614
2643
|
if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
|
|
2615
|
-
|
|
2644
|
+
// What the plan says about recorded children holds on every apply path: the
|
|
2645
|
+
// retirement stops them first and keeps them (retireInstance, once it has
|
|
2646
|
+
// resolved the home). A guarded apply acts on the children of the plan it
|
|
2647
|
+
// revalidated; a plain or --self retire computes them as the plan does, and
|
|
2648
|
+
// passes none when there are none.
|
|
2649
|
+
let replayPath = null, plannedExtraWorktrees, fresh, children;
|
|
2616
2650
|
if (planRev !== undefined) {
|
|
2617
2651
|
if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
|
|
2618
2652
|
// Replay first: after a successful retire the home is gone, so the receipt
|
|
2619
2653
|
// (beside the instances dir, keyed by the idempotency key) is the answer.
|
|
2620
2654
|
const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
|
|
2621
2655
|
for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
|
|
2622
|
-
let fresh;
|
|
2623
2656
|
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
|
|
2624
2657
|
replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
|
|
2625
2658
|
// The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
|
|
2626
2659
|
// move or remove one that no longer reads that way when it gets to them.
|
|
2627
2660
|
plannedExtraWorktrees = fresh.facts.extraWorktrees;
|
|
2628
2661
|
if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
|
|
2629
|
-
|
|
2630
|
-
|
|
2631
|
-
|
|
2632
|
-
|
|
2633
|
-
for (const kid of fresh.facts.children) {
|
|
2634
|
-
try { const s = stopInstanceSession(kid.home, {}); childrenStopped.push({ instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }); }
|
|
2635
|
-
catch (e) { childrenStopped.push({ instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }); }
|
|
2636
|
-
}
|
|
2637
|
-
const running = childrenStopped.filter((k) => !k.ok);
|
|
2638
|
-
if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
|
|
2662
|
+
children = fresh.facts.children;
|
|
2663
|
+
} else {
|
|
2664
|
+
const recorded = descendantsOf(root, name);
|
|
2665
|
+
if (recorded.length) children = recorded;
|
|
2639
2666
|
}
|
|
2640
2667
|
let r;
|
|
2641
|
-
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}) }); }
|
|
2642
|
-
catch (e) {
|
|
2643
|
-
|
|
2668
|
+
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}), ...(children ? { children } : {}) }); }
|
|
2669
|
+
catch (e) {
|
|
2670
|
+
if (!e?.code) throw e;
|
|
2671
|
+
// A child still running (or whose stop could not be established) refused the retirement: the
|
|
2672
|
+
// guarded apply returns the plan it acted on, and the text names each child's reason.
|
|
2673
|
+
if (e.code === "E_CHILDREN_RUNNING") {
|
|
2674
|
+
const running = e.details.childrenStopped.filter((k) => !k.ok);
|
|
2675
|
+
return args.includes("--json") ? jsonFail(e.code, e.message, { ...e.details, ...(planRev !== undefined ? { plan: fresh } : {}) }) : die(`children still running: ${running.map((k) => `${k.instance} (${k.code})`).join(", ")}; nothing retired`);
|
|
2676
|
+
}
|
|
2677
|
+
return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message);
|
|
2678
|
+
}
|
|
2644
2679
|
if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
|
|
2645
2680
|
// A retired home's wake jobs are forgotten (definitions only; nothing is
|
|
2646
2681
|
// stopped by this); a deferred self-retire keeps them until the home is gone.
|
|
@@ -2677,6 +2712,7 @@ function retireCmd() {
|
|
|
2677
2712
|
process.exit(1);
|
|
2678
2713
|
}
|
|
2679
2714
|
console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
|
|
2715
|
+
for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}`);
|
|
2680
2716
|
// Preserving work and not saying so leaves the operator believing it is gone,
|
|
2681
2717
|
// which is most of the harm of deleting it. Name the classes and the path.
|
|
2682
2718
|
for (const line of workRecoveryLines(r)) console.log(line);
|
|
@@ -3414,7 +3450,7 @@ function versionCmd() {
|
|
|
3414
3450
|
// Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
|
|
3415
3451
|
// runs on resolve/materialize (contract §6); a feature the binary does not implement is
|
|
3416
3452
|
// never listed.
|
|
3417
|
-
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["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"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
|
|
3453
|
+
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["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"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
|
|
3418
3454
|
return;
|
|
3419
3455
|
}
|
|
3420
3456
|
console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
|
|
@@ -4217,10 +4253,14 @@ Usage:
|
|
|
4217
4253
|
[--max-age <s>] (souls have no private mode), with origin
|
|
4218
4254
|
(member <key> @ <commit> | package <id> v<ver>) and its
|
|
4219
4255
|
teams on this deployment
|
|
4220
|
-
oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label>
|
|
4221
|
-
| default <label>
|
|
4256
|
+
oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label>
|
|
4257
|
+
| default <label> [--if-absent | --expect <label>]
|
|
4258
|
+
[--dir <d>] this deployment's teams (shared + local), the
|
|
4222
4259
|
[--max-age <s>] (the read form only) default, the workspace's souls:; add/remove/default
|
|
4223
|
-
edit oats-local.yaml (only with localTeams: true)
|
|
4260
|
+
edit oats-local.yaml (only with localTeams: true);
|
|
4261
|
+
--no-default: the mapping only (an exact repeat is
|
|
4262
|
+
reuse); --if-absent / --expect: set the default only
|
|
4263
|
+
where there is none / it is <label>
|
|
4224
4264
|
oats soul teams <soul>|'*' [--dir <d>] which teams a soul may join here, its default, and
|
|
4225
4265
|
[--max-age <s>] [--json] why (the workspace's souls: and local teams)
|
|
4226
4266
|
oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
|
package/docs/capabilities.md
CHANGED
|
@@ -495,6 +495,14 @@ start (a renewed session grant, for example) leaves the CURRENT one on record. A
|
|
|
495
495
|
launch hook that answers without `meta` keeps its previous entry; a start whose
|
|
496
496
|
preparation fails changes nothing.
|
|
497
497
|
|
|
498
|
+
A launch hook's `brief` is not used. A home's `TASK.md` (which carries the
|
|
499
|
+
spawn hooks' briefs) and `AGENTS.md` are composed once, at spawn, and no start
|
|
500
|
+
rewrites them. A provider whose state changes at a start records it in `meta`.
|
|
501
|
+
`oats inspect --home <abs> --json` reads the served identity a provider
|
|
502
|
+
recorded there (the messaging provider's, when it has one) as `identity`. A
|
|
503
|
+
spawn brief that describes such state should say it is the state at spawn and
|
|
504
|
+
point to that command.
|
|
505
|
+
|
|
498
506
|
A launch hook may do idempotent provider registration on a real start (an
|
|
499
507
|
aweb home registering with the host wake broker, for example). How the
|
|
500
508
|
kernel runs it depends on whether its capability declares **preview
|
package/docs/configuration.md
CHANGED
|
@@ -63,7 +63,7 @@ refused (`E_WORKSPACE_SCHEMA`).
|
|
|
63
63
|
| `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
|
|
64
64
|
| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
|
|
65
65
|
| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
|
|
66
|
-
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
|
|
66
|
+
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
|
|
67
67
|
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
|
|
68
68
|
| `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
|
|
69
69
|
| `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
|
|
@@ -121,24 +121,30 @@ The qualified channel frame starts on its accepted option and permits one
|
|
|
121
121
|
Enter only. Folder-trust and API-key questions remain unexpected and block.
|
|
122
122
|
A qualified normal-output boundary closes observation without asserting readiness.
|
|
123
123
|
|
|
124
|
-
**Qualified completion and limitation:** exact captured
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
124
|
+
**Qualified completion and limitation:** the existing exact captured and
|
|
125
|
+
source-derived empty API/subscription frames remain supported. After one recorded
|
|
126
|
+
submitted channel Enter, the same qualified Claude 2.1.289 darwin-arm64 executable
|
|
127
|
+
also recognizes the [bounded bottom input/footer structure](launch-prompt-completion.md)
|
|
128
|
+
at 110x35. Its six mode labels, five effort labels and finite hints are
|
|
129
|
+
source-qualified; header/billing/model and preceding task text are not structural
|
|
130
|
+
completion conditions. The 21 exact question markers take precedence over both
|
|
131
|
+
completion paths after submission. Normal `? for shortcuts` and `esc to interrupt`
|
|
132
|
+
are not markers. Input authorization and exact-home consent are unchanged.
|
|
133
|
+
|
|
134
|
+
**Accepted reporting risk:** an unknown dialog retaining the composer/footer can
|
|
135
|
+
be misclassified completed. Completion permanently closes input authority, but
|
|
136
|
+
proves neither absence of all questions nor idle/account/channel readiness.
|
|
137
|
+
Missing effort, trailing notices, wrapped footers and other unsupported shapes
|
|
138
|
+
still block. A feature-flag footer change can reduce matches without a binary
|
|
139
|
+
change. A matched structural frame must be saved privately before completed is
|
|
140
|
+
audited; failure reports incomplete with the answer and target preserved.
|
|
141
|
+
|
|
142
|
+
A submitted Enter can therefore precede `E_SPAWN_INCOMPLETE`; the pane may already
|
|
143
|
+
be active. Inspect the answer, checked event receipt and retained target, rather
|
|
144
|
+
than automatically retrying input or relaunching. Existing API fixtures used
|
|
145
|
+
isolated dummy credentials; the observed Max regression is a labeled home-only
|
|
146
|
+
sanitized derivative of one controller-compared in-progress frame, not a new
|
|
147
|
+
end-to-end launch proof or general production-success claim.
|
|
142
148
|
|
|
143
149
|
When a harness update changes the version-bound prompt frame, opted-in homes
|
|
144
150
|
block again with `blocked: unexpected prompt` until fixtures are refreshed.
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -40,7 +40,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
|
40
40
|
"team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
|
|
41
41
|
"preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
|
|
42
42
|
"workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
|
|
43
|
-
"automation-descriptions","souls-capabilities","soul-composed-instructions"],
|
|
43
|
+
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default"],
|
|
44
44
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
45
45
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
46
46
|
"capabilityShowApi":1}
|
|
@@ -112,6 +112,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
|
112
112
|
| `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
|
|
113
113
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
114
114
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
115
|
+
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
115
116
|
|
|
116
117
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
117
118
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -367,7 +368,7 @@ An instance subject, abridged:
|
|
|
367
368
|
| `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
|
|
368
369
|
| `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
|
|
369
370
|
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
|
|
370
|
-
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null` |
|
|
371
|
+
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
|
|
371
372
|
| `problems` | below |
|
|
372
373
|
|
|
373
374
|
**Soul row** (`soulsApi: 2`). For a home it is read from the recorded
|
|
@@ -1250,9 +1251,9 @@ unknown.
|
|
|
1250
1251
|
|
|
1251
1252
|
```text
|
|
1252
1253
|
oats teams [--dir <d>] [--max-age <s>] --json
|
|
1253
|
-
oats teams add <label> --team <id> [--description <d>] --json
|
|
1254
|
+
oats teams add <label> --team <id> [--description <d>] [--no-default] --json
|
|
1254
1255
|
oats teams remove <label> --json
|
|
1255
|
-
oats teams default <label> --json
|
|
1256
|
+
oats teams default <label> [--if-absent | --expect <label>] --json
|
|
1256
1257
|
```
|
|
1257
1258
|
|
|
1258
1259
|
```json
|
|
@@ -1284,13 +1285,41 @@ oats teams default <label> --json
|
|
|
1284
1285
|
still runs there: taking local teams away is the last step of committing
|
|
1285
1286
|
them in the workspace.
|
|
1286
1287
|
- **`add`**: the first team added also becomes the local `defaultTeam`. A
|
|
1287
|
-
label already declared is `E_TEAM_EXISTS {label, from
|
|
1288
|
-
|
|
1288
|
+
label already declared is `E_TEAM_EXISTS {label, from, observed: {label,
|
|
1289
|
+
team, from}}` (`observed` is the declared mapping; `from` is `"local"` or
|
|
1290
|
+
`"shared"`); a bad label or no `--team` is `E_BAD_ARGS`.
|
|
1291
|
+
- **`add --no-default`** (feature `teams-conditional-default`) writes the
|
|
1292
|
+
mapping and never touches `defaultTeam`. A mapping already declared with
|
|
1293
|
+
the same label and the same team id (local or shared) is reuse: the answer
|
|
1294
|
+
is `changed: false, reused: true`, so a setup can retry it. The description
|
|
1295
|
+
is neither compared nor changed. The same label with another id is
|
|
1296
|
+
`E_TEAM_EXISTS` as above. `reused` appears only on that answer. Where local
|
|
1297
|
+
teams are not allowed, `add --no-default` is refused with local-teams-closed
|
|
1298
|
+
like every `add`, before reuse is considered.
|
|
1289
1299
|
- **`remove`**: a label the local `defaultTeam` names is `E_TEAM_IN_USE
|
|
1290
1300
|
{label, usedBy: ["defaultTeam"]}`; a shared label is `E_TEAM_SHARED {label,
|
|
1291
1301
|
at}` (a label in both files can be removed locally); unknown is
|
|
1292
1302
|
`E_TEAM_UNKNOWN {label}`.
|
|
1293
1303
|
- **`default`**: any declared label, else `E_TEAM_UNKNOWN`.
|
|
1304
|
+
- **`default --if-absent`** sets it only where the deployment has no effective
|
|
1305
|
+
default (this document's `defaultTeam` is `null`); **`default --expect
|
|
1306
|
+
<label0>`** only where the effective default's label is `<label0>`, local
|
|
1307
|
+
or inherited from the workspace (feature `teams-conditional-default`). The
|
|
1308
|
+
two together are `E_BAD_ARGS`. A failed condition is `E_TEAM_DEFAULT_MISMATCH
|
|
1309
|
+
{expected: {absent: true} | {label}, observed}`, `observed` being the
|
|
1310
|
+
`defaultTeam` exactly as this document reports it (or `null`); nothing was
|
|
1311
|
+
written. A soul's `souls:` default is not the deployment's and is not
|
|
1312
|
+
looked at. The refusals above run first, in order: `E_BAD_ARGS`,
|
|
1313
|
+
local-teams-closed, `E_TEAM_UNKNOWN`, then the condition. When the
|
|
1314
|
+
condition holds and `<label>` already is the local default, `changed` is
|
|
1315
|
+
`false`.
|
|
1316
|
+
- **Flags**: each form refuses a flag it does not take with `E_USAGE {flag}`,
|
|
1317
|
+
naming the flag and the usage, before anything is read. `add` takes
|
|
1318
|
+
`--team`, `--description`, `--no-default`; `remove` none; `default`
|
|
1319
|
+
`--if-absent`, `--expect`; every form `--dir` and `--json`, and the read
|
|
1320
|
+
form `--max-age` (on a write form, `--max-age` is the kernel's own
|
|
1321
|
+
`E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
|
|
1322
|
+
answer, as for every command.
|
|
1294
1323
|
- A write that would introduce an unknown reference is refused with that
|
|
1295
1324
|
code; an invalid result is `E_WORKSPACE_SCHEMA`.
|
|
1296
1325
|
- **Writes** edit `oats-local.yaml` in place and touch only the entries that
|
|
@@ -1298,7 +1327,22 @@ oats teams default <label> --json
|
|
|
1298
1327
|
entries, are kept. Each verb re-reads the file and judges its refusals on it
|
|
1299
1328
|
as it is now, and writes only if the file did not change meanwhile (else it
|
|
1300
1329
|
redoes the edit on the new content). A file that keeps changing is
|
|
1301
|
-
`E_LOCAL_CHANGED {path}`; nothing was written.
|
|
1330
|
+
`E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
|
|
1331
|
+
and `--expect` is judged the same way, on the file as it is now and again on
|
|
1332
|
+
every redo.
|
|
1333
|
+
- **Concurrency.** Every `add`, `remove` and `default` holds
|
|
1334
|
+
`<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
|
|
1335
|
+
Among concurrent `oats teams` writers on one deployment, a conditional write
|
|
1336
|
+
therefore never overwrites a default another of them set: when two race, the
|
|
1337
|
+
later one sees the earlier result and refuses with
|
|
1338
|
+
`E_TEAM_DEFAULT_MISMATCH`. A lock still held after 5 s is `E_LOCAL_BUSY
|
|
1339
|
+
{path, lock}`, naming the directory to remove when no oats process is
|
|
1340
|
+
editing; nothing was written. The limits: a person or tool editing
|
|
1341
|
+
`oats-local.yaml` directly does not take the lock (the content compare still
|
|
1342
|
+
catches most such edits, but not one landing between the compare and the
|
|
1343
|
+
rename), and changes to the committed `oats-workspace.yaml` (a pull, a
|
|
1344
|
+
merge) are not serialized with it: the condition reads the workspace file
|
|
1345
|
+
when it is judged, and that is the only promise.
|
|
1302
1346
|
|
|
1303
1347
|
<a id="oats-soul-teams"></a>
|
|
1304
1348
|
### `oats soul teams`
|
|
@@ -1626,13 +1670,15 @@ allocated. Use runtime inspection and the existing start/restart lifecycle.
|
|
|
1626
1670
|
Same-key spawn replay cannot convert a blocked outcome to successful spawn.
|
|
1627
1671
|
|
|
1628
1672
|
`answers` can contain a `submitted` answer even when the final status is
|
|
1629
|
-
`blocked`:
|
|
1630
|
-
|
|
1631
|
-
source-derived Max/Pro/Team/Enterprise variants of the empty API frame. A different normal-looking banner can block after Enter
|
|
1673
|
+
`blocked`: even after exact or structural completion recognition is qualified,
|
|
1674
|
+
unsupported input/footer shapes and known question markers can block after Enter
|
|
1632
1675
|
while the actual pane is active. Consumers must preserve that submitted receipt
|
|
1633
1676
|
and never translate this outcome into “nothing started” or automatic retry.
|
|
1634
1677
|
The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
|
|
1635
|
-
is part of the shipping contract.
|
|
1678
|
+
is part of the shipping contract. Structural completion closes observation only;
|
|
1679
|
+
unknown dialogs retaining the recognized composer/footer can be misclassified.
|
|
1680
|
+
Mandatory structural evidence-save failure reports checked `incomplete` with the
|
|
1681
|
+
same answer and target preserved. Private receipt v2 adds no public DTO fields.
|
|
1636
1682
|
|
|
1637
1683
|
Strict Desktop/pi readers must accept these additive fields and the new event
|
|
1638
1684
|
kind before a writer containing them ships. For operator recovery, see
|
|
@@ -2846,14 +2892,32 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
2846
2892
|
pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
|
|
2847
2893
|
`{…, alreadyScheduled: true, requestedAt}`.
|
|
2848
2894
|
|
|
2895
|
+
**Recorded children**, on every apply (plain, guarded and `--self`), as the
|
|
2896
|
+
plan says: each child the plan lists is stopped first (bounded SIGTERM,
|
|
2897
|
+
never escalated) and kept, once the retire has resolved the home and before
|
|
2898
|
+
the instance's own session is stopped. `childrenStopped[]` lists them,
|
|
2899
|
+
deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
|
|
2900
|
+
`{instance, home, ok: false, code, message, stillRunning}`. A plain or
|
|
2901
|
+
`--self` receipt carries it only when there are children; a guarded receipt
|
|
2902
|
+
always does (`[]` when there are none). One child still running after the
|
|
2903
|
+
grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
|
|
2904
|
+
`E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
|
|
2905
|
+
`E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
|
|
2906
|
+
`code`). **`--force` does not bypass it**: `--force` covers incomplete
|
|
2907
|
+
cleanup, not a running child. A `--self` retirement stops the children
|
|
2908
|
+
recorded when it was scheduled that are still instances (a child retired in
|
|
2909
|
+
between is skipped), in its detached completion before it stops the caller;
|
|
2910
|
+
a refusal there leaves the caller's window and home in place and
|
|
2911
|
+
writes `{ok: false, error: {code: "E_CHILDREN_RUNNING"}, childrenStopped,
|
|
2912
|
+
retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
|
|
2913
|
+
|
|
2849
2914
|
**Guarded apply** (what the Desktop sends): `--plan-revision` and
|
|
2850
2915
|
`--idempotency-key` together.
|
|
2851
2916
|
- A used key replays its receipt as an **envelope** with `replayed: true`
|
|
2852
2917
|
(receipts live beside the instances directory and outlive the home).
|
|
2853
2918
|
- The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
|
|
2854
|
-
-
|
|
2855
|
-
|
|
2856
|
-
{childrenStopped, plan}`.
|
|
2919
|
+
- The children stopped are those of the revalidated plan, and a refusal
|
|
2920
|
+
carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
|
|
2857
2921
|
- A first guarded retire prints the raw receipt with `planRevision`,
|
|
2858
2922
|
`idempotencyKey` and `replayed: false`.
|
|
2859
2923
|
|
package/docs/desktop.md
CHANGED
|
@@ -294,12 +294,12 @@ for a password or key, and never runs anything over ssh itself.
|
|
|
294
294
|
## Instances on servers
|
|
295
295
|
|
|
296
296
|
Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
|
|
297
|
-
can open its terminal, start, restart, stop and
|
|
297
|
+
can open its terminal, start, restart, stop and retire it, and read its readiness, activity, Git
|
|
298
298
|
and diffs, as for a local one. The context panel's Soul tab and its Messaging & Teams list read
|
|
299
299
|
through the server too (`oats inspect --server <id> --home <path>`), and its Work card, "model
|
|
300
300
|
from" line and "older build" chip show the facts the server relays. Only its pull request is not read here, since the forge reads this
|
|
301
301
|
computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
|
|
302
|
-
<path>`), never by a bare name. Stop and
|
|
302
|
+
<path>`), never by a bare name. Stop and Retire show the plan the server makes, and confirm
|
|
303
303
|
against it.
|
|
304
304
|
|
|
305
305
|
A read waits for the server: the view says "Reading from <server>…", and gives up after about
|
|
@@ -615,7 +615,8 @@ anchor edited or removed since the original pre-hook snapshot, instead of
|
|
|
615
615
|
replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
|
|
616
616
|
`answers`, `reason` and event `receipt`; unknown prompts use
|
|
617
617
|
`blocked: unexpected prompt`. Status `incomplete` means the audit could not be
|
|
618
|
-
completed, including a possible key followed by an audit failure
|
|
618
|
+
completed, including a possible key followed by an audit failure or failure to
|
|
619
|
+
retain mandatory structural-completion evidence. It is
|
|
619
620
|
not proof that no input was sent. Both outcomes record `launched:false` while
|
|
620
621
|
retaining the real process/endpoint for inspection: this is never permission
|
|
621
622
|
to allocate another harness.
|
|
@@ -636,11 +637,79 @@ No audit or metadata write is directed into the replacement home.
|
|
|
636
637
|
A blocked result can follow a successfully submitted Enter. The accepted
|
|
637
638
|
completion families cover exact installed-plugin and plugin-absent banners,
|
|
638
639
|
plus source-derived billing-only variants of those empty frames (Max, Pro,
|
|
639
|
-
Team and Enterprise)
|
|
640
|
+
Team and Enterprise), and source-derived empty Max/bypass/medium frames.
|
|
641
|
+
Other model, billing, effort or permission text can leave the pane active while
|
|
640
642
|
reporting a retained block. Inspect `answers` and the event receipts; never infer
|
|
641
643
|
that nothing started or nothing was answered. See the
|
|
642
644
|
[completion limitation](configuration.md#exact-home-launch-prompt-consent).
|
|
643
645
|
|
|
646
|
+
### Private unmatched launch evidence
|
|
647
|
+
|
|
648
|
+
This section also covers mandatory structural-completion evidence.
|
|
649
|
+
|
|
650
|
+
After a submitted launch answer, an unmatched 110x35 frame is retained locally
|
|
651
|
+
at `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
|
|
652
|
+
`receipt.json` published last. This is the exact UTF-8 text already compared by
|
|
653
|
+
the controller, including whitespace and final newline, not a later recapture.
|
|
654
|
+
It is bounded to 64 KiB and 35 rows. There is no new input, observation, retry,
|
|
655
|
+
geometry change or readiness claim. Evidence is also mandatory when the post-answer
|
|
656
|
+
[structural completion rule](launch-prompt-completion.md) selects completion.
|
|
657
|
+
Previously qualified exact completion does not acquire that requirement. No
|
|
658
|
+
frame is saved before a submitted answer or for unrelated blocked reasons.
|
|
659
|
+
|
|
660
|
+
Find the invocation's existing `launch-prompt` event in the home's
|
|
661
|
+
`.oats-events.jsonl` (or the checked event rows in `launchPrompts.receipt`). Its
|
|
662
|
+
`data.startId` supplies the string to hash with SHA-256, UTF-8, yielding the
|
|
663
|
+
lowercase hexadecimal directory name. Match the event's home, socket, window,
|
|
664
|
+
pane, PID and `signatureDigest`; do not assume a top-level spawn-result `startId`.
|
|
665
|
+
Spawn and same-home start/restart use this same controller and event path.
|
|
666
|
+
|
|
667
|
+
New evidence directories are owner-only 0700 and files 0600. The writer checks
|
|
668
|
+
canonical directory identities, ownership, modes and symlinks, refuses ACLs on
|
|
669
|
+
evidence directories/files (including macOS ACLs hidden by xattrs), refuses an
|
|
670
|
+
existing invocation directory, and publishes bounded files without overwrite.
|
|
671
|
+
The private receipt binds the start, target, original home identity, dimensions,
|
|
672
|
+
frame inode, byte count and SHA-256. `retainedAt` is write time; `captureTime:null`
|
|
673
|
+
means no independent capture timestamp was recorded. It does not substitute an
|
|
674
|
+
event timestamp for capture time. Same-uid concurrent mutation between checks is
|
|
675
|
+
not excluded.
|
|
676
|
+
|
|
677
|
+
Private receipt version 2 uses `kind:"launch-prompt-frame"` and admits only
|
|
678
|
+
`outcome:"blocked", recognition:"unmatched"` or
|
|
679
|
+
`outcome:"completed", recognition:"structural"`. These fields describe the
|
|
680
|
+
recognition whose frame was saved, not the final public launch result: a later
|
|
681
|
+
audit or cleanup failure can still report `incomplete`. Historical version 1
|
|
682
|
+
receipts with `kind:"launch-prompt-unmatched"` describe blocked/unmatched
|
|
683
|
+
evidence. Readers must reject unknown versions, kinds or crossed pairs rather
|
|
684
|
+
than infer completion from an artifact's presence.
|
|
685
|
+
|
|
686
|
+
Before collecting a frame, verify its original `frameIdentity`, byte count,
|
|
687
|
+
digest and dimensions against the receipt, and bind the receipt's `startId`,
|
|
688
|
+
home and target to the checked launch event. A copied file has a different
|
|
689
|
+
inode: preserve the original identity as provenance instead of comparing the
|
|
690
|
+
copy's inode with it. Missing, partial, mismatched or failed-save evidence, or
|
|
691
|
+
an incomplete public launch result, must not be reported as a successful
|
|
692
|
+
completed observation. Collection never recaptures the pane or retries input.
|
|
693
|
+
|
|
694
|
+
Verify both files, receipt/identity/digest and the corresponding checked event
|
|
695
|
+
before treating the save as complete. A frame alone is partial evidence. Failed
|
|
696
|
+
publication, fsync, readback or temporary-file cleanup leaves the launch blocked
|
|
697
|
+
and adds only `; private launch evidence retention failed` to its diagnostic
|
|
698
|
+
reason. Already published files may remain, including a receipt if a later
|
|
699
|
+
verification fails; their presence alone is not a success claim. The submitted
|
|
700
|
+
answer is preserved. Existing event-audit failures still report `incomplete`.
|
|
701
|
+
A structural-completion save failure instead reports checked `incomplete` with
|
|
702
|
+
`private launch evidence retention failed`, preserving the submitted answer and
|
|
703
|
+
retained target. It never retries publication or input. An audit failure remains
|
|
704
|
+
incomplete even if private evidence was saved. No public result or event contains
|
|
705
|
+
the raw screen or private receipt.
|
|
706
|
+
|
|
707
|
+
The frame can contain private task or account text. It stays on this host with
|
|
708
|
+
no automatic transmission or expiry. Preserve needed evidence privately before
|
|
709
|
+
retirement; it follows the home's ordinary conservative recovery behavior, with
|
|
710
|
+
no integrity-neutral exclusion or new cleanup policy. A saved frame is evidence
|
|
711
|
+
for review, never automatic permission to activate a new matcher.
|
|
712
|
+
|
|
644
713
|
Retiring a blocked or incomplete spawned home can preserve a recovery copy
|
|
645
714
|
labelled `changed instance-home bytes`, even without authored changes: the
|
|
646
715
|
kernel changed metadata from `launched:true` to `false` after its baseline.
|
|
@@ -675,6 +744,9 @@ oats session attach --home /abs/home
|
|
|
675
744
|
harness, `shell` for a fallback shell,
|
|
676
745
|
`stopped` for an absent or dead terminal, or `not-launched`. An unavailable
|
|
677
746
|
backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
|
|
747
|
+
A home without its session receipt is refused with
|
|
748
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for; what
|
|
749
|
+
to do is in [souls and instances](souls-and-instances.md#retire).
|
|
678
750
|
Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
|
|
679
751
|
live claim that the instance needs input from a human, `{since, producer,
|
|
680
752
|
reason, message}`, or `null`; it is non-null only for a running harness
|
package/docs/implementation.md
CHANGED
|
@@ -13,8 +13,9 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
|
|
|
13
13
|
catalog (`package-catalog.json`). It has no runtime dependencies.
|
|
14
14
|
- **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
|
|
15
15
|
instance's own resources. It registers no agent tools.
|
|
16
|
-
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup
|
|
17
|
-
`oats.knowledge-theory` capabilities and the
|
|
16
|
+
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
|
|
17
|
+
`oats.support` and `oats.knowledge-theory` capabilities and the
|
|
18
|
+
`knowledge-theory-expert` soul,
|
|
18
19
|
released as a package under its own `oats-framework/v<version>` tags.
|
|
19
20
|
`oats.core` is the one with executables: its spawn and launch hook and the
|
|
20
21
|
Claude Code waiting emitter (`capabilities/oats-core/bin/`).
|
|
@@ -66,6 +67,8 @@ published to npm. Its developer docs are in
|
|
|
66
67
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
|
|
67
68
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
68
69
|
| `servers.mjs` | routing commands to a registered server |
|
|
70
|
+
| `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
71
|
+
| `launch-prompt-completion.mjs` | pure, qualified post-answer completion reporting using a finite bottom input/footer table and 21 question markers; never an input matcher |
|
|
69
72
|
| `launch-prompt-policy.mjs` | strict host-local exact-home aweb development-channel consent, canonical directory validation and config provenance |
|
|
70
73
|
| `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts and the fixture-gated exact aweb development-channel signature |
|
|
71
74
|
| `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
|
|
@@ -365,3 +368,22 @@ and acts on every existing session through its recorded socket
|
|
|
365
368
|
`list-windows`, `new-window` (a window id) and `set-option`.
|
|
366
369
|
- A server a test starts is killed by its socket, never by name and never
|
|
367
370
|
with a bare `tmux kill-server`.
|
|
371
|
+
|
|
372
|
+
Nor does a test depend on where or how the suite runs:
|
|
373
|
+
|
|
374
|
+
- A worker whose working directory is inside an instance home (a developer
|
|
375
|
+
agent running the suite from its work tree) is that instance to the
|
|
376
|
+
kernel. `isolateSessionEnvironment` leaves it; a fixture that builds its
|
|
377
|
+
environment itself calls `leaveEnclosingInstance(base)` and moves back
|
|
378
|
+
when it is done.
|
|
379
|
+
- `isolateSessionEnvironment` drops `CLAUDECODE`, which a worker inherits
|
|
380
|
+
from a Claude Code session: a server the worker starts would hold it.
|
|
381
|
+
- An expected path is built on a canonical fixture base,
|
|
382
|
+
`realpathSync(mkdtempSync(…))`: the platform's temporary directory can be
|
|
383
|
+
a symlink (`/var` on macOS), and the kernel builds the paths it reports on
|
|
384
|
+
its working directory, which the OS gives as the physical path.
|
|
385
|
+
- A probe of the host that reads under `HOME` (the scheduler's installed
|
|
386
|
+
unit) runs with the fixture's own `HOME`.
|
|
387
|
+
- A fixture the filesystem may not represent (a file name that is not valid
|
|
388
|
+
UTF-8, which APFS refuses) is probed in the fixture directory and skipped
|
|
389
|
+
with its reason only when refused; Linux CI runs it.
|