@awebai/oats 0.69.23 → 0.69.24
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 +56 -17
- package/docs/capabilities.md +353 -5
- package/docs/capability-manifest.schema.json +36 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +257 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +5 -1
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/souls-and-instances.md +45 -0
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +13 -5
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1176 -181
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +97 -8
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +28 -4
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/bin/oats.mjs
CHANGED
|
@@ -26,17 +26,25 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
28
|
import { spawnSync as spawnSyncProc } from "node:child_process";
|
|
29
|
+
import { nodeVersionFailure } from "../lib/node-version.mjs";
|
|
29
30
|
import { enableCliCompileCache } from "../lib/compile-cache.mjs";
|
|
30
31
|
import { hotImport, hotRead } from "../lib/hot-reads.mjs";
|
|
31
32
|
import { installStamp } from "../lib/install-stamp.mjs";
|
|
32
33
|
|
|
34
|
+
const unsupportedNode = nodeVersionFailure(process.versions.node);
|
|
35
|
+
if (unsupportedNode) {
|
|
36
|
+
if (process.argv.includes("--json")) process.stdout.write(`${JSON.stringify(unsupportedNode)}\n`);
|
|
37
|
+
else process.stderr.write(`${unsupportedNode.error.message}\n`);
|
|
38
|
+
process.exit(1);
|
|
39
|
+
}
|
|
40
|
+
|
|
33
41
|
// The warm reader's baseline (lib/reader.mjs): its install's stamp before any kernel module loads, so that an
|
|
34
42
|
// install changed while the kernel loads is never the install the reader believes it answers from.
|
|
35
43
|
const READER_STAMP = process.argv[2] === "reader" ? installStamp() : null;
|
|
36
44
|
|
|
37
45
|
// Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
|
|
38
|
-
// all parsed and linked before this module's body runs, so they are Node built-ins and the
|
|
39
|
-
// dependency-free modules above, and the kernel and `yaml` are imported here
|
|
46
|
+
// all parsed and linked before this module's body runs, so they are Node built-ins and the small
|
|
47
|
+
// dependency-free startup modules above, and the kernel and `yaml` are imported here once it is on.
|
|
40
48
|
enableCliCompileCache();
|
|
41
49
|
// A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
|
|
42
50
|
// the leaves its names come from, and every other command imports every module, in this order. A hot
|
|
@@ -95,7 +103,7 @@ const { readBoardDetail, askBoardQuestion, clearBoardQuestion, setBoardFact, uns
|
|
|
95
103
|
const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
|
|
96
104
|
const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
|
|
97
105
|
const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
|
|
98
|
-
const { BOARD_API, KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
|
|
106
|
+
const { BOARD_API, BUILTIN_SESSION_BACKENDS, KERNEL_FEATURES, READER_API, SESSION_PROVIDER_NAME_RE } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
|
|
99
107
|
const { inheritedContextRefusal } = await kernelImport("captured-context", () => import("../lib/captured-context.mjs"));
|
|
100
108
|
const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call", () => import("../lib/read-call.mjs"));
|
|
101
109
|
const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
|
|
@@ -518,7 +526,8 @@ function scopeSouls(ctx, { extraRoots = [] } = {}) {
|
|
|
518
526
|
const roots = [...new Set([findRoot(ctx), ...extraRoots].filter(Boolean).map((p) => realOrResolved(resolve(p))))];
|
|
519
527
|
const souls = [];
|
|
520
528
|
for (const root of roots) {
|
|
521
|
-
|
|
529
|
+
// Names only: no session provider is asked.
|
|
530
|
+
for (const a of listInstances(root, undefined, undefined, { askProviders: false })) {
|
|
522
531
|
const soul = findAgent(root, a.name) || a;
|
|
523
532
|
const e = soulEntry(soul, root);
|
|
524
533
|
e.instances = (a.instances || []).map((i) => i.instance);
|
|
@@ -676,6 +685,8 @@ function printWorkspaceInspect(doc) {
|
|
|
676
685
|
if (doc.identity) console.log(` identity: ${servedIdentityLine(doc.identity)}`);
|
|
677
686
|
for (const l of LAYERS) console.log(` ${l} capability: ${doc.layers[l].id || "none"}`);
|
|
678
687
|
for (const c of doc.capabilities) console.log(` ${c.id}@${c.version || "?"} ${c.from?.kind === "package" ? `package ${c.from.package}` : c.from?.kind === "member" ? `member ${c.from.repoKey}` : ""}${c.operations.length ? ` ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
|
|
688
|
+
// Feature session-providers: the backends `--backend` takes here beside tmux, each with the capability that supplies it.
|
|
689
|
+
if (doc.sessionProviders?.length) console.log(` session backends: tmux, ${doc.sessionProviders.map((p) => `${p.name} (${p.capability})`).join(", ")}`);
|
|
679
690
|
for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
|
|
680
691
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
681
692
|
const board = doc.instance?.board;
|
|
@@ -890,6 +901,16 @@ function doctorMachineLaunchConfigs() {
|
|
|
890
901
|
return { file, present: true, ok: false, configurations: [], error: e.message };
|
|
891
902
|
}
|
|
892
903
|
}
|
|
904
|
+
/** The shared Git version probe reports support, not each repository's recorded fetch mode.
|
|
905
|
+
* An older Git is supported too; this is information, never a warning or a refusal. */
|
|
906
|
+
async function doctorGitInformation() {
|
|
907
|
+
const version = await remoteModule.gitVersion();
|
|
908
|
+
if (!version) return "git-version: Git version could not be read; partial-cache support unknown";
|
|
909
|
+
const mode = remoteModule.keepsPartialCache(version)
|
|
910
|
+
? "partial caches supported (a remote or an existing cache may still use whole-tree fetches)"
|
|
911
|
+
: `whole-tree fallback (partial caches need Git ${remoteModule.PARTIAL_FETCH_GIT.join(".")} or later)`;
|
|
912
|
+
return `git-version: Git ${terminalText(version.text)}; ${mode}`;
|
|
913
|
+
}
|
|
893
914
|
/** The machine's resume lock when it needs a person (lib/session-resume.mjs resumeLockProblem), as
|
|
894
915
|
* doctor's problems: read where a sweep would take it, nothing taken. It is this machine's, the
|
|
895
916
|
* same from every deployment. */
|
|
@@ -913,7 +934,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
913
934
|
schemaVersion: 1, workspaceApi: 2, context: ctx,
|
|
914
935
|
workspace: { file: ws.local.path, ref: ws.local.workspace },
|
|
915
936
|
workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
|
|
916
|
-
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
937
|
+
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
917
938
|
machineLaunchConfigs: doctorMachineLaunchConfigs(),
|
|
918
939
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
919
940
|
...(problems.length ? { problems } : {}),
|
|
@@ -973,7 +994,7 @@ async function doctor(dir) {
|
|
|
973
994
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
974
995
|
for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
|
|
975
996
|
if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
|
|
976
|
-
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
997
|
+
for (const line of [await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
977
998
|
for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
|
|
978
999
|
if (soulName) {
|
|
979
1000
|
const information = operationalKnowledgeNote(composition, soulName);
|
|
@@ -1156,8 +1177,11 @@ function launchPreview(bail) {
|
|
|
1156
1177
|
let plan;
|
|
1157
1178
|
try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
|
|
1158
1179
|
const { recipe } = plan;
|
|
1159
|
-
|
|
1160
|
-
|
|
1180
|
+
// A home on a session provider has no command line: its launch is handed to the provider as data
|
|
1181
|
+
// (`command` and `argv` null, the executable's path null); its environment is listed by name.
|
|
1182
|
+
const onProvider = plan.command === undefined;
|
|
1183
|
+
const command = onProvider ? null : renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
|
|
1184
|
+
const d = onProvider ? { argv: null, environment: [...Object.keys(recipe.hooks?.env || {}).sort().map((name) => ({ name, redacted: true })), ...Object.keys(recipe.env || {}).sort().map((name) => (typeof recipe.env[name] === "string" ? { name, redacted: true } : { name, reference: true }))] } : describeLaunchCommand(command);
|
|
1161
1185
|
const environment = d.environment.map((e) => e.reference && recipe.env[e.name] && typeof recipe.env[e.name] === "object" ? { name: e.name, ...recipe.env[e.name] } : e);
|
|
1162
1186
|
jsonOk({ context, selected, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
|
|
1163
1187
|
}
|
|
@@ -2603,6 +2627,17 @@ async function capabilityShowCmd(bail) {
|
|
|
2603
2627
|
}
|
|
2604
2628
|
for (const p of doc.triggerSourceProblems ?? []) console.log(` trigger source problem: ${p.pointer} — ${safeText(p.message, 300)}`);
|
|
2605
2629
|
}
|
|
2630
|
+
if (doc.sessionProviders !== undefined) {
|
|
2631
|
+
// As declared (a malformed declaration is shown, never refused), made safe to print.
|
|
2632
|
+
const { safeText } = await import("../lib/refused-text.mjs");
|
|
2633
|
+
const decl = doc.sessionProviders && typeof doc.sessionProviders === "object" && !Array.isArray(doc.sessionProviders) ? doc.sessionProviders : null;
|
|
2634
|
+
console.log(decl && Object.keys(decl).length ? " session providers:" : ` session providers: ${decl ? "(none)" : "(malformed — see session provider problems)"}`);
|
|
2635
|
+
for (const [n, provider] of Object.entries(decl ?? {})) {
|
|
2636
|
+
const o = provider && typeof provider === "object" ? provider : {};
|
|
2637
|
+
console.log(` ${safeText(n, 60)} harnesses ${Array.isArray(o.harnesses) ? o.harnesses.map((h) => safeText(String(h), 40)).join(",") : "?"}${typeof o.description === "string" ? ` — ${safeText(o.description, 200)}` : ""}`);
|
|
2638
|
+
}
|
|
2639
|
+
for (const p of doc.sessionProviderProblems ?? []) console.log(` session provider problem: ${p.pointer} — ${safeText(p.message, 300)}`);
|
|
2640
|
+
}
|
|
2606
2641
|
for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
|
|
2607
2642
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
2608
2643
|
console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
|
|
@@ -2731,7 +2766,7 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
|
|
|
2731
2766
|
if (a.description) console.log(` ${a.description}`);
|
|
2732
2767
|
for (const i of a.instances) {
|
|
2733
2768
|
// Feature instance-background: the row is marked; it is listed like any other.
|
|
2734
|
-
console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
|
|
2769
|
+
console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"}${i.session ? `, on ${i.backend}` : ""})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
|
|
2735
2770
|
{ const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
|
|
2736
2771
|
// Feature waiting-on-you: non-null only on a running row; the reader has
|
|
2737
2772
|
// already validated the message (one line, no control characters).
|
|
@@ -2798,7 +2833,9 @@ async function spawnCmd() {
|
|
|
2798
2833
|
const yolo = yoloFlag();
|
|
2799
2834
|
{ const herdr = herdrSpawnFlag(); if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); } }
|
|
2800
2835
|
const backend = valueFlag("backend");
|
|
2801
|
-
|
|
2836
|
+
// tmux, or a session provider one of the soul's capabilities declares: the kernel resolves the name
|
|
2837
|
+
// against the instance's modules (E_BACKEND_UNKNOWN names the backends available there).
|
|
2838
|
+
if (backend !== undefined && !SESSION_PROVIDER_NAME_RE.test(backend)) bail("E_BAD_ARGS", "--backend must be tmux or a session provider's name (1 to 40 lowercase letters, digits and dashes)");
|
|
2802
2839
|
const requestedWork = valueFlag("work");
|
|
2803
2840
|
const workDir = valueFlag("work-dir"), branch = valueFlag("branch"), repo = valueFlag("repo");
|
|
2804
2841
|
const checkDirectoryOptions = (work) => {
|
|
@@ -3067,7 +3104,8 @@ async function spawnCmd() {
|
|
|
3067
3104
|
// #917: what this spawn's start did with Claude's development-channel prompt, as a start answers it.
|
|
3068
3105
|
...(r.launchPrompts ? { launchPrompts: r.launchPrompts } : {}),
|
|
3069
3106
|
...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
|
|
3070
|
-
|
|
3107
|
+
// A home on a session provider carries its backend's name and `session` ({ provider, endpoint }), and no tmux.
|
|
3108
|
+
tmux: r.tmux || null, backend: r.session ? r.backend : "tmux", ...(r.session ? { session: r.session } : {}), repo: r.repo || null, harness: r.harness || null,
|
|
3071
3109
|
model: r.model || null, parent: r.parentInstance || null,
|
|
3072
3110
|
sibling: r.siblingInstance || null, relation: r.relation || null,
|
|
3073
3111
|
spawnOrigin: r.spawnOrigin, attach: r.attach,
|
|
@@ -3085,7 +3123,7 @@ async function spawnCmd() {
|
|
|
3085
3123
|
});
|
|
3086
3124
|
return;
|
|
3087
3125
|
}
|
|
3088
|
-
console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
|
|
3126
|
+
console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? (r.session ? ` — ${r.backend} session` : ` — tmux window "${r.tmux.window}"`) : " — not launched"}`);
|
|
3089
3127
|
console.log(` home: ${shortPath(r.home)}`);
|
|
3090
3128
|
if (r.background === true) console.log(` list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
|
|
3091
3129
|
{ const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
|
|
@@ -3095,7 +3133,8 @@ async function spawnCmd() {
|
|
|
3095
3133
|
if (wakeScheduleError) console.error(` wake: NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
|
|
3096
3134
|
if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
|
|
3097
3135
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
3098
|
-
console.log(` attach: ${r.attach}`);
|
|
3136
|
+
if (r.attach) console.log(` attach: ${r.attach}`);
|
|
3137
|
+
else if (r.session) console.log(` open: oats session inspect --home ${shellQuote(r.home)} --json (its \`open\` link; ${terminalText(r.backend)} has no terminal to attach to)`);
|
|
3099
3138
|
}
|
|
3100
3139
|
|
|
3101
3140
|
/** The line naming the branch a FAILED_SPAWN_BRANCH_LEFT item speaks of, on a line of its own: the item names
|
|
@@ -3586,7 +3625,7 @@ async function sessionCmd() {
|
|
|
3586
3625
|
const deployment = flag("deployment");
|
|
3587
3626
|
if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
|
|
3588
3627
|
const { resumeSessions } = await import("../lib/session-resume.mjs");
|
|
3589
|
-
const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
|
|
3628
|
+
const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), askProviders: !args.includes("--without-provider-inspect"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
|
|
3590
3629
|
if (JSON_MODE) { jsonOk(answer); return; }
|
|
3591
3630
|
for (const d of answer.deployments) console.log(`${d.deployment}: ${d.swept ? "swept" : `not swept (${d.reason}${d.code ? `, ${d.code}` : ""})`}`);
|
|
3592
3631
|
for (const r of answer.rows) console.log(` ${r.instance} ${answer.plan ? "would be " : ""}${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
|
|
@@ -4307,7 +4346,7 @@ function versionCmd() {
|
|
|
4307
4346
|
// Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
|
|
4308
4347
|
// runs on resolve/materialize (contract §6); a feature the binary does not implement is
|
|
4309
4348
|
// never listed.
|
|
4310
|
-
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends:
|
|
4349
|
+
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: BUILTIN_SESSION_BACKENDS, launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, readerApi: READER_API, boardApi: BOARD_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
|
|
4311
4350
|
return;
|
|
4312
4351
|
}
|
|
4313
4352
|
console.log(`${OATS_PACKAGE_NAME} ${OATS_VERSION} (desktop API v1)`);
|
|
@@ -4787,7 +4826,7 @@ async function serverRouteCmd() {
|
|
|
4787
4826
|
// The host's answer decides, not the flag: one that spawned is reported as the spawn it was.
|
|
4788
4827
|
if (cmd === "spawn" && rest.includes("--preview") && r.preview === true) printSpawnPreview(r, { server: id, soulFetched: r.soulFetched === true });
|
|
4789
4828
|
else if (cmd === "spawn") {
|
|
4790
|
-
console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
|
|
4829
|
+
console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? (r.session ? ` — ${terminalText(r.backend)} session on ${r.target.sshHost}` : ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}`) : " — not launched"}`);
|
|
4791
4830
|
console.log(` remote home: ${r.home}`);
|
|
4792
4831
|
{ const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
|
|
4793
4832
|
console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
|
|
@@ -5187,7 +5226,7 @@ Usage:
|
|
|
5187
5226
|
is a unit (a conflicting --harness is refused)
|
|
5188
5227
|
[--model <id>|@native-default] override the selected model; @native-default
|
|
5189
5228
|
selects the harness's own model default
|
|
5190
|
-
[--backend tmux] [--yolo|--no-yolo]
|
|
5229
|
+
[--backend tmux|<provider>] [--yolo|--no-yolo] session backend (tmux, or a session provider of the soul's capabilities) and launch permission option
|
|
5191
5230
|
[--background|--no-background] list the instance under Background (presentation
|
|
5192
5231
|
only); default: the soul's background:, else no
|
|
5193
5232
|
[--no-launch] [--json] scaffold without launching; JSON result envelope
|
package/docs/capabilities.md
CHANGED
|
@@ -441,6 +441,10 @@ A self-contained package has an `oats.json`:
|
|
|
441
441
|
- `triggerSources` (optional) declares the capability's
|
|
442
442
|
[trigger sources](#trigger-sources-triggersources). It is checked only
|
|
443
443
|
where a source is used, never when the capability loads.
|
|
444
|
+
- `sessionProviders` (optional) declares the session backends the
|
|
445
|
+
capability supplies beside the kernel's tmux
|
|
446
|
+
([session providers](#session-providers-sessionproviders)). It is checked
|
|
447
|
+
only where a provider is used, never when the capability loads.
|
|
444
448
|
- Target names never appear in a package manifest.
|
|
445
449
|
|
|
446
450
|
`capability` is the only manifest identity field; it may also carry
|
|
@@ -655,11 +659,17 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
|
|
|
655
659
|
`OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
|
|
656
660
|
`OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
|
|
657
661
|
preview (only a preview-aware hook does, below); on a real run
|
|
658
|
-
`OATS_LAUNCH_PREVIEW` is not set. A
|
|
662
|
+
`OATS_LAUNCH_PREVIEW` is not set. A spawn hook and a launch hook also get
|
|
663
|
+
`OATS_BACKEND` (feature `session-providers`): the session
|
|
664
|
+
backend the instance launches on, `tmux` or the name of a
|
|
665
|
+
[session provider](#session-providers-sessionproviders). A spawn that launches
|
|
666
|
+
nothing (`--no-launch`) sets it too: it is what a later start launches on. A
|
|
667
|
+
kernel without the feature sets none, which means tmux. A worktree hook also gets the tree
|
|
659
668
|
variables of [The worktree event](#the-worktree-event).
|
|
660
669
|
|
|
661
670
|
A spawn or launch hook also gets `OATS_HARNESS_EXECUTABLE`, for every harness
|
|
662
|
-
and the same way in a preview
|
|
671
|
+
on tmux and the same way in a preview (a session provider runs the harness
|
|
672
|
+
itself, so the variable is absent there): the absolute real path of the executable the
|
|
663
673
|
pane will run, found the way the pane finds it. It is reserved, so a launch
|
|
664
674
|
configuration's `env` or a trigger cannot set it, and an inherited value is
|
|
665
675
|
dropped. It doesn't reach the harness's pane, even from an existing server's
|
|
@@ -1424,8 +1434,9 @@ waiting clear --producer oats.core --home <home>` from anywhere.
|
|
|
1424
1434
|
- **Its own entries only.** oats.core marks its entries by the absolute
|
|
1425
1435
|
path of its `claude-waiting.sh`. Each run removes only the entries that
|
|
1426
1436
|
name that path (and any matcher group or event array the removal
|
|
1427
|
-
empties), then appends its current ones.
|
|
1428
|
-
|
|
1437
|
+
empties), then appends its current ones. Apart from adding `tui` when
|
|
1438
|
+
absent (below), every other key and entry stays as it was, in order.
|
|
1439
|
+
The file is written atomically, mode 0600, and only
|
|
1429
1440
|
when its content changes. A temp file an interrupted write left behind
|
|
1430
1441
|
(`.claude/.settings.json.oats-core-<pid>-<ms>.tmp`) is removed by the next
|
|
1431
1442
|
spawn or start once its writer is gone, so it needs no retirement
|
|
@@ -1546,10 +1557,25 @@ that file replaces earlier ones wholesale, even one with no hooks. The
|
|
|
1546
1557
|
project `.claude/settings.json` composes with the user's settings (under any
|
|
1547
1558
|
`CLAUDE_CONFIG_DIR`) and with a `--settings`. So any capability that needs
|
|
1548
1559
|
Claude settings uses the same managed `<home>/.claude/settings.json` with
|
|
1549
|
-
its
|
|
1560
|
+
marked entries for its hooks, never `--settings`. oats.core leaves
|
|
1550
1561
|
`.claude/settings.local.json` to Claude Code, which writes its "don't ask
|
|
1551
1562
|
again" permission rules there.
|
|
1552
1563
|
|
|
1564
|
+
**Renderer selection.** In the same merge, at spawn and every launch,
|
|
1565
|
+
oats.core adds `"tui": "default"` when the project's settings have no `tui`
|
|
1566
|
+
key. Any existing value, including a non-string, is kept: a scalar has no
|
|
1567
|
+
marker to distinguish the person's choice from oats.core's. Any `tui` in
|
|
1568
|
+
Claude's merged settings skips its fullscreen-renderer offer, which can
|
|
1569
|
+
otherwise stop an unattended agent before it receives a wake. `"default"`
|
|
1570
|
+
selects the classic renderer used by the launch-prompt captures and keeps
|
|
1571
|
+
tmux scrollback. The cost: agent panes use Claude's classic renderer even
|
|
1572
|
+
where Claude defaults to fullscreen, and the project setting overrides a
|
|
1573
|
+
user-level `"tui": "fullscreen"`. An existing project `tui` still wins.
|
|
1574
|
+
A pass that changes nothing does not rewrite the file. The existing file
|
|
1575
|
+
refusals, preview behaviour and non-Claude behaviour above apply to `tui`
|
|
1576
|
+
too. If oats.core ever stops adding it, existing homes keep the key until
|
|
1577
|
+
respawn.
|
|
1578
|
+
|
|
1553
1579
|
**Limits.**
|
|
1554
1580
|
|
|
1555
1581
|
- If the user's Claude configuration sets `disableAllHooks` or
|
|
@@ -1944,3 +1970,325 @@ whole poll, resolution included, gets 35 s, and polls run only while they can
|
|
|
1944
1970
|
end within 50 s of the tick's start. Answer from a cache or a quick query: a
|
|
1945
1971
|
source slower than that should cache.
|
|
1946
1972
|
|
|
1973
|
+
## Session providers (`sessionProviders`)
|
|
1974
|
+
|
|
1975
|
+
A kernel that lists the feature `session-providers` in `oats version --json`
|
|
1976
|
+
has this contract. tmux is the kernel's own session backend. A capability can supply another one, a
|
|
1977
|
+
**session provider**: the instance's agent then runs wherever the provider
|
|
1978
|
+
runs it (a thread of another product, a remote runner), and the kernel reaches
|
|
1979
|
+
it through four of the capability's own commands. The kernel keeps what a
|
|
1980
|
+
backend must not own: the receipts and the authority check, the lifecycle
|
|
1981
|
+
claims, the refusals and the JSON answers. What an operator sees is in
|
|
1982
|
+
[execution-targets.md](execution-targets.md#session-providers).
|
|
1983
|
+
|
|
1984
|
+
```json
|
|
1985
|
+
"commands": { "session-launch": "bin/session.mjs launch", "session-inspect": "bin/session.mjs inspect",
|
|
1986
|
+
"session-input": "bin/session.mjs input", "session-stop": "bin/session.mjs stop",
|
|
1987
|
+
"session-inspect-many": "bin/session.mjs inspect-many" },
|
|
1988
|
+
"sessionProviders": {
|
|
1989
|
+
"bb": {
|
|
1990
|
+
"description": "Runs the agent as a bb thread",
|
|
1991
|
+
"harnesses": ["claude"],
|
|
1992
|
+
"commands": { "launch": "session-launch", "inspect": "session-inspect", "input": "session-input",
|
|
1993
|
+
"stop": "session-stop", "inspectMany": "session-inspect-many" }
|
|
1994
|
+
}
|
|
1995
|
+
}
|
|
1996
|
+
```
|
|
1997
|
+
|
|
1998
|
+
- The **name** is 1 to 40 lowercase letters, digits and dashes, starting with
|
|
1999
|
+
a letter or digit. `tmux`, `session-provider` and `herdr` are reserved. It
|
|
2000
|
+
is what `--backend` takes, and what a hook reads in `OATS_BACKEND`. At most
|
|
2001
|
+
16 providers.
|
|
2002
|
+
- **`commands`** names `launch`, `inspect`, `input` and `stop`, and optionally
|
|
2003
|
+
`inspectMany` and `check`. Each value is a key of the manifest's
|
|
2004
|
+
`commands`.
|
|
2005
|
+
- **`harnesses`** lists the harnesses the provider runs (1 to 16 names). A
|
|
2006
|
+
spawn or a start on another one is refused `E_BACKEND_HARNESS`.
|
|
2007
|
+
- **`description`** is optional: one line of at most 200 characters.
|
|
2008
|
+
- No other key.
|
|
2009
|
+
|
|
2010
|
+
**Containment.** A malformed `sessionProviders` never refuses the capability:
|
|
2011
|
+
it is validated where a provider is used. A problem inside one provider
|
|
2012
|
+
disables that provider only, and `--backend <name>` then answers
|
|
2013
|
+
`E_BACKEND_UNKNOWN` with the problem. `oats capabilities show <name> --json`
|
|
2014
|
+
adds `sessionProviders` (as declared) and, when there is one,
|
|
2015
|
+
`sessionProviderProblems: [{provider, pointer, message}]`.
|
|
2016
|
+
[`docs/capability-manifest.schema.json`](capability-manifest.schema.json)
|
|
2017
|
+
carries the same shape; that a verb names one of the manifest's commands is
|
|
2018
|
+
checked by the kernel only.
|
|
2019
|
+
|
|
2020
|
+
**One name, one meaning.** A provider is selected among the capabilities of
|
|
2021
|
+
the instance being spawned. Two of them declaring the same name is
|
|
2022
|
+
`E_BACKEND_AMBIGUOUS`: compose only one.
|
|
2023
|
+
|
|
2024
|
+
### The call
|
|
2025
|
+
|
|
2026
|
+
Every call runs the **home's own copy** of the capability:
|
|
2027
|
+
`node <home>/.oats/modules/<capability>/<script> <args>`. **Its working
|
|
2028
|
+
directory is not the home** (it is the filesystem root): read the home from
|
|
2029
|
+
the request (`input.home`) or `OATS_INSTANCE_HOME`, and leave
|
|
2030
|
+
nothing of the call's own running in the home (the session's processes work
|
|
2031
|
+
there; a helper of your command must not). OATS looks for
|
|
2032
|
+
processes working in a home before it resumes a lost session and before it
|
|
2033
|
+
retires the home, and a provider's call must never be one of them.
|
|
2034
|
+
|
|
2035
|
+
- **Environment:** what a lifecycle hook of the capability gets in that home
|
|
2036
|
+
([Commands and hooks](#commands-and-hooks)): `OATS_INSTANCE`,
|
|
2037
|
+
`OATS_INSTANCE_HOME`, `OATS_SETTINGS` (the settings captured at spawn),
|
|
2038
|
+
`OATS_META`, `OATS_CLI_BIN` and the rest, with `OATS_EVENT=session` and
|
|
2039
|
+
`OATS_BACKEND=<name>`.
|
|
2040
|
+
- **stdin:** one JSON request,
|
|
2041
|
+
`{ "schemaVersion": 1, "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
|
|
2042
|
+
- **stdout:** exactly one JSON document of at most 1 MiB, the same five header
|
|
2043
|
+
keys echoed, then `"ok": true, "result": { … }` or
|
|
2044
|
+
`"ok": false, "error": { "code": "E_…", "message": "…" }`. No other key.
|
|
2045
|
+
A refusal's code is `E_` followed by capitals, digits and underscores.
|
|
2046
|
+
- **Exit status 0**, for a result and for a refusal.
|
|
2047
|
+
- **Timeouts:** launch 120 s, stop 20 s plus the grace it is given, every
|
|
2048
|
+
other verb 20 s. The command is killed at its timeout.
|
|
2049
|
+
- **Process group:** OATS runs each command in a process group of its own,
|
|
2050
|
+
and ends the whole group (SIGKILL) at the timeout, and when the `oats`
|
|
2051
|
+
command that ran a `launch`, an `input` or a `stop` was itself killed
|
|
2052
|
+
while it waited (the next stop, start, input or retire of the home does
|
|
2053
|
+
it, before it calls you again). A stop also waits for an `input` that is
|
|
2054
|
+
being sent, up to its timeout, before it asks you to `stop`. **Run your helpers inside that group and never detach
|
|
2055
|
+
them** (no `setsid`, no daemon): a helper that escapes it can start a
|
|
2056
|
+
session OATS has no record of.
|
|
2057
|
+
- stderr is never read.
|
|
2058
|
+
|
|
2059
|
+
A call that does not end that way (another exit status, a signal, the
|
|
2060
|
+
timeout, no or malformed JSON, a wrong envelope, a result that breaks its
|
|
2061
|
+
verb's rules) is a **failed call**. A failed call is never read as an answer:
|
|
2062
|
+
an inspect that failed is never "stopped".
|
|
2063
|
+
|
|
2064
|
+
| Verb | A failed call, or a refusal the kernel does not relay |
|
|
2065
|
+
|---|---|
|
|
2066
|
+
| `inspect`, `inspectMany` | `E_SESSION_UNAVAILABLE`; the status row reads `running: null`, `runtimeState: "unreachable"` |
|
|
2067
|
+
| `check` | the readiness item reads `unknown`; a launch is refused `E_BACKEND_NOT_READY` |
|
|
2068
|
+
| `input` | `E_SESSION_INPUT_FAILED` |
|
|
2069
|
+
| `stop` | `E_SESSION_STOP_FAILED` |
|
|
2070
|
+
| `launch` | `E_SESSION_START_FAILED` |
|
|
2071
|
+
|
|
2072
|
+
The kernel relays these refusals under the provider's own code: from
|
|
2073
|
+
`launch`, any `E_BACKEND_*`; from `input`, `E_SESSION_PROMPT_OPEN` and
|
|
2074
|
+
`E_SESSION_INPUT_QUEUED`. The message of any refusal is carried into the
|
|
2075
|
+
kernel's, made safe to print and cut to 500 characters.
|
|
2076
|
+
|
|
2077
|
+
### launch
|
|
2078
|
+
|
|
2079
|
+
In:
|
|
2080
|
+
|
|
2081
|
+
```json
|
|
2082
|
+
{ "home": "/abs/home", "instance": "dev-a", "harness": "claude", "model": "id-or-null", "yolo": true,
|
|
2083
|
+
"env": [ { "name": "OATS_INSTANCE", "value": "dev-a", "source": "kernel" },
|
|
2084
|
+
{ "name": "AWEB_IDENTITY_HOME", "value": "/abs/…", "source": "capability", "capability": "oats.aweb" },
|
|
2085
|
+
{ "name": "REGION", "value": "eu", "source": "launch-config" },
|
|
2086
|
+
{ "name": "API_KEY", "value": "…", "source": "launch-config-reference", "secret": true } ],
|
|
2087
|
+
"unset": ["NAME"],
|
|
2088
|
+
"pathPrepend": ["/abs/home/.oats/bin"],
|
|
2089
|
+
"args": ["--flag", "value"],
|
|
2090
|
+
"promptFile": "/abs/home/TASK.md",
|
|
2091
|
+
"previous": null }
|
|
2092
|
+
```
|
|
2093
|
+
|
|
2094
|
+
- `env` is every variable the launch sets, in the order a tmux launch sets
|
|
2095
|
+
them. `source` says where each comes from: `kernel` (the instance's
|
|
2096
|
+
identity, a trigger's event file), `capability` (a hook's `env`, with the
|
|
2097
|
+
`capability` that owns it), `launch-config` (a launch configuration's
|
|
2098
|
+
literal value) or `launch-config-reference` (a launch configuration's
|
|
2099
|
+
`fromEnv` or `fromFile`: a secret source, marked `secret: true`, its value
|
|
2100
|
+
read on this host).
|
|
2101
|
+
- `unset` lists the names the launch removes: declared by a capability and
|
|
2102
|
+
left out of this launch.
|
|
2103
|
+
- `pathPrepend` is the home's kernel shim directory. Put it first on the
|
|
2104
|
+
agent's `PATH`, so its plain `oats` is the kernel that launched it.
|
|
2105
|
+
- `args` is the launch configuration's arguments, then the capabilities'
|
|
2106
|
+
launch arguments for the harness, as the words a shell would hand it
|
|
2107
|
+
(arguments the kernel cannot read as words are refused,
|
|
2108
|
+
`E_BACKEND_LAUNCH_ARG`, naming the capability). The kernel's own choices are never in
|
|
2109
|
+
it: they are `model` (null: the harness's default), `yolo` (`true`,
|
|
2110
|
+
`false`, or `null` when nobody chose) and the prompt.
|
|
2111
|
+
- `promptFile` is the home's `TASK.md`: the briefing a fresh conversation
|
|
2112
|
+
starts on.
|
|
2113
|
+
- `previous` is the endpoint of the session a start or a restart replaces;
|
|
2114
|
+
`null` for the home's first launch. The kernel has asked you to stop it
|
|
2115
|
+
just before, always (a restart's stop, once more for a home OATS had
|
|
2116
|
+
stopped, and for a session you answered as gone too: an input that reached
|
|
2117
|
+
it since may have had you restart it).
|
|
2118
|
+
|
|
2119
|
+
**A provider that cannot carry an env entry, an argument or `unset`
|
|
2120
|
+
refuses, naming it** (`E_BACKEND_LAUNCH_ENV`, `E_BACKEND_LAUNCH_ARG`). It
|
|
2121
|
+
never drops one silently, and it never stores a `secret` value where others
|
|
2122
|
+
can read it.
|
|
2123
|
+
|
|
2124
|
+
Out: `{ "endpoint": { … } }`. The endpoint is a JSON object whose canonical
|
|
2125
|
+
JSON is at most 4 KiB (4096 bytes). **It names one session: answer an
|
|
2126
|
+
endpoint you never answered before for that home** (a new thread id, not a
|
|
2127
|
+
locator a later session takes over). The kernel stops a session by its
|
|
2128
|
+
endpoint, also after a newer one was launched. The kernel records it as given, in the
|
|
2129
|
+
home's `instance.json` and its receipt, and hands it back on every call. It
|
|
2130
|
+
holds **locators only, never a credential**.
|
|
2131
|
+
|
|
2132
|
+
The kernel refuses, before anything is created, a launch configuration that
|
|
2133
|
+
declares `executable` for a provider backend (`E_BACKEND_LAUNCH_ARG`): the
|
|
2134
|
+
provider runs the harness itself.
|
|
2135
|
+
|
|
2136
|
+
### inspect and inspectMany
|
|
2137
|
+
|
|
2138
|
+
`inspect` in: `{ "home", "endpoint" }`. Out:
|
|
2139
|
+
`{ "present": true|false, "state": "unknown"|"shell"|"stopped", "running": true|false|null, "open"?: { "label", "url" } }`,
|
|
2140
|
+
exactly those keys.
|
|
2141
|
+
|
|
2142
|
+
| The session | present | state | running |
|
|
2143
|
+
|---|---|---|---|
|
|
2144
|
+
| a turn or a start is in progress | true | `unknown` | true |
|
|
2145
|
+
| there, and the provider cannot tell a live idle session from a settled one | true | `unknown` | null |
|
|
2146
|
+
| gone: missing, deleted, or in error with nothing running | false | `stopped` | false |
|
|
2147
|
+
| the harness ended and something else holds the session, as a terminal left at its shell | true | `shell` | false |
|
|
2148
|
+
|
|
2149
|
+
A session that is not there (`present: false`) is `stopped` and runs nothing:
|
|
2150
|
+
any other answer with `present: false` is outside the table, and is read as
|
|
2151
|
+
no answer (unavailable), like a word outside the contract.
|
|
2152
|
+
|
|
2153
|
+
Map only what the product shows; never infer. **A session that is gone on a
|
|
2154
|
+
home OATS did not stop is a lost session**: OATS resumes it through `input`,
|
|
2155
|
+
under its cap ([below](#what-the-kernel-does-around-the-verbs)). So answer a
|
|
2156
|
+
session whose run ended in error as gone, not as `shell`, when your product
|
|
2157
|
+
restarts it on the next input. `open` is what a client may
|
|
2158
|
+
show instead of a terminal: a one-line `label` of at most 100 characters and
|
|
2159
|
+
an `http` or `https` `url` of at most 2000, without credentials.
|
|
2160
|
+
|
|
2161
|
+
`inspectMany` (optional) in:
|
|
2162
|
+
`{ "homes": [ { "home", "instance", "endpoint" } ] }`, at most 200. Out:
|
|
2163
|
+
`{ "results": [ … ] }`, one per home in the same order, each an inspect
|
|
2164
|
+
result or `{ "error": { "code", "message" } }`. `oats status` calls it once
|
|
2165
|
+
per group of homes that share the capability's module copy (same digest),
|
|
2166
|
+
the provider and the settings; the call's environment is the group's first
|
|
2167
|
+
home's. Each entry is judged as one `inspect` answer would be. A batch that
|
|
2168
|
+
fails or is not one result per home, and an entry that is neither a result
|
|
2169
|
+
nor a refusal, fall back to that home's own `inspect`, never to "stopped".
|
|
2170
|
+
Without `inspectMany`, status calls `inspect` per home.
|
|
2171
|
+
|
|
2172
|
+
**The kernel never calls inspect for a home OATS stopped** (below).
|
|
2173
|
+
|
|
2174
|
+
### input
|
|
2175
|
+
|
|
2176
|
+
In: `{ "home", "endpoint", "text" }`. Out: `{ "submitted": true, "verified": true|false }`
|
|
2177
|
+
**only when the text was dispatched** to the session. `submitted` is never
|
|
2178
|
+
`false` in a result: an input that was not dispatched is a refusal.
|
|
2179
|
+
|
|
2180
|
+
- A session with a prompt open (a permission prompt, a question) is not
|
|
2181
|
+
answered by an input: refuse `E_SESSION_PROMPT_OPEN` and send nothing.
|
|
2182
|
+
Otherwise any mail could approve a permission.
|
|
2183
|
+
- An input the product queued instead of dispatching is not a submission:
|
|
2184
|
+
withdraw it and refuse `E_SESSION_INPUT_QUEUED`.
|
|
2185
|
+
|
|
2186
|
+
Both reach the caller as they are, with `ok: false`. The messaging broker
|
|
2187
|
+
leaves such a mail unread; a scheduled wake records it not delivered.
|
|
2188
|
+
|
|
2189
|
+
### stop
|
|
2190
|
+
|
|
2191
|
+
In: `{ "home", "endpoint", "graceSeconds", "launchSent"? }`. Out: `{ "stopped": true }`.
|
|
2192
|
+
`endpoint` is `null` when the kernel has no endpoint for a session you may
|
|
2193
|
+
have started: a launch whose answer was lost, and a launch it sent whose
|
|
2194
|
+
spawn or start ended before recording your answer (it was killed while you
|
|
2195
|
+
launched). Then stop whatever live session is rooted at the home, and answer
|
|
2196
|
+
`stopped: true` also when there is none. The input then also carries
|
|
2197
|
+
`"launchSent": "<instant>"`, the time the kernel recorded for that launch,
|
|
2198
|
+
when it has one: what the launch started was created at or after it, so you
|
|
2199
|
+
can leave alone what was in the home's place before (a person's own session
|
|
2200
|
+
there). **The kernel relies on this stop**: it is the only way a session
|
|
2201
|
+
started by a killed spawn is ever stopped.
|
|
2202
|
+
|
|
2203
|
+
### check (optional)
|
|
2204
|
+
|
|
2205
|
+
The provider's readiness. In: `{ "home": "/abs/home" | null, "soul": "<name>" | null, "settings": { … } }`:
|
|
2206
|
+
a home, or, before any home exists, a soul. Out:
|
|
2207
|
+
`{ "status": "ready" | "needs-configuration" | "authorization-required" | "unavailable", "problems": [ { "code", "message" } ], "warnings": [ { "code", "message" } ] }`
|
|
2208
|
+
(`warnings` optional; no problem on `ready`). Say where a credential comes
|
|
2209
|
+
from, never print it.
|
|
2210
|
+
|
|
2211
|
+
- `oats readiness` relays the answer as a `providers` item, the shape a
|
|
2212
|
+
binding check's answer has: for a home, its own backend's, required; for a
|
|
2213
|
+
soul, each provider its capabilities offer, not required (the soul can
|
|
2214
|
+
launch on tmux).
|
|
2215
|
+
- **The kernel asks it right before every launch** (a spawn's, a start's, a
|
|
2216
|
+
restart's before its stop). A status other than `ready` refuses the launch:
|
|
2217
|
+
with the first problem's code when that is an `E_BACKEND_*` code, else
|
|
2218
|
+
`E_BACKEND_NOT_READY`, the message carrying your problems. A check that
|
|
2219
|
+
fails or answers outside these words is not ready.
|
|
2220
|
+
|
|
2221
|
+
### Requirements by backend (`requires[].backends`)
|
|
2222
|
+
|
|
2223
|
+
A harness-package requirement (`requires: [{ harness, package, … }]`) is for
|
|
2224
|
+
the harness install on this host. A row may say which backends it is for:
|
|
2225
|
+
`"backends": ["tmux"]`, `["session-provider"]` (any session provider) or
|
|
2226
|
+
both. Without the key it applies to every backend, a provider's launch
|
|
2227
|
+
included, where it is probed on this host. It is a key of its own, never
|
|
2228
|
+
inside `when`, whose keys are the capability's settings. A kernel without
|
|
2229
|
+
`session-providers` knows no such key and applies the row to every launch:
|
|
2230
|
+
a package that uses `backends` raises its OATS floor to a kernel that lists
|
|
2231
|
+
the feature.
|
|
2232
|
+
|
|
2233
|
+
### What the kernel does around the verbs
|
|
2234
|
+
|
|
2235
|
+
- **Stop stays stopped.** At every OATS stop (`oats instance stop`, a
|
|
2236
|
+
restart's stop, a retire, `oats host run`'s shutdown) the kernel records
|
|
2237
|
+
`stoppedAt` in the home's receipt **before** it calls `stop`, and a start
|
|
2238
|
+
clears it. While it is set, inspect answers stopped (`present: false`,
|
|
2239
|
+
`running: false`) without calling the provider, and every input (a
|
|
2240
|
+
person's `oats session input`, a scheduled wake, a client, the messaging
|
|
2241
|
+
broker) is refused `E_SESSION_NOT_RUNNING` before any call. A provider
|
|
2242
|
+
whose product restarts a session on its next input can rely on this.
|
|
2243
|
+
- **Hooks first.** The capabilities' spawn hooks (at a spawn) and launch
|
|
2244
|
+
hooks (at a start or a restart) run before `launch`, as before a tmux
|
|
2245
|
+
window, with `OATS_BACKEND`.
|
|
2246
|
+
- **Retire** records `stoppedAt`, calls `stop`, then runs the retire hooks
|
|
2247
|
+
and removes the home. The retire hook is not handed the endpoint: a
|
|
2248
|
+
provider that archives its session finds it by the home.
|
|
2249
|
+
- **A launch that fails** leaves the home as it was (stopped, or never
|
|
2250
|
+
launched; a spawn is rolled back). When its answer was lost, the kernel
|
|
2251
|
+
calls `stop` with `endpoint: null` first.
|
|
2252
|
+
- **A launch that was sent and never recorded.** The kernel writes in the
|
|
2253
|
+
home's receipt that a launch is being sent, right before it calls you, and
|
|
2254
|
+
takes that away when it has recorded your endpoint. A spawn or a start
|
|
2255
|
+
that is killed while you launch leaves it there: the home then reads as
|
|
2256
|
+
unknown, and the next stop, start or retire first calls `stop` with
|
|
2257
|
+
`endpoint: null`.
|
|
2258
|
+
- **Which stop it was** is on the home's stop receipt, never a field of
|
|
2259
|
+
yours: `oats host run`'s shutdown is a loss that the sweep resumes, an
|
|
2260
|
+
operator's stop is the intent that keeps the home down.
|
|
2261
|
+
- **A lost session is resumed through `input`.** A home whose session you
|
|
2262
|
+
answer as gone, and that OATS did not stop, is resumed by the sweep with
|
|
2263
|
+
one notice, and any other input to it is a resume too. The kernel counts
|
|
2264
|
+
each against the home's cap before it calls `input` (at most 3 in an hour,
|
|
2265
|
+
within one boot), refuses at the cap with `E_SESSION_NOT_RUNNING` without
|
|
2266
|
+
calling you, and first waits (a resume) or refuses (an input) while a
|
|
2267
|
+
process still works in the home. So an `inspect` precedes every `input` to
|
|
2268
|
+
a home OATS did not stop (the resume of a home stopped with the host sends
|
|
2269
|
+
its notice without one).
|
|
2270
|
+
An input you refuse (`ok: false`: nothing was sent) is not counted. One
|
|
2271
|
+
whose call fails or answers outside the rules stays counted: you may have
|
|
2272
|
+
restarted the session on it.
|
|
2273
|
+
- **`stop` is idempotent.** The kernel calls it again wherever it needs the
|
|
2274
|
+
session gone: an operator's stop of a home that is already stopped (how a
|
|
2275
|
+
stop you did not confirm is finished), a start of a stopped home before
|
|
2276
|
+
its launch, and after an input that crossed a stop (an input holds no
|
|
2277
|
+
claim: when a stop or a restart lands while one is being sent, the kernel
|
|
2278
|
+
asks you to stop that session again and does not deliver the input,
|
|
2279
|
+
whatever you answered to it, a refusal included). After a restart it asks
|
|
2280
|
+
that only when the new session has another endpoint: where you hand a
|
|
2281
|
+
restart the same locator again, that locator is the new session's, and the
|
|
2282
|
+
kernel tells the two apart by its own record of the start. An input that
|
|
2283
|
+
is in flight when a start begins its launch is such a crossing too.
|
|
2284
|
+
Answer `stopped: true` for a session that is already stopped.
|
|
2285
|
+
- **A spawn holds the home while you launch.** From before the home can be
|
|
2286
|
+
acted on until your launch's endpoint is recorded (or the spawn is undone),
|
|
2287
|
+
the spawn holds the home's lifecycle claim: a stop, a start or a retire
|
|
2288
|
+
that arrives meanwhile is refused as busy, never answered as if there were
|
|
2289
|
+
nothing to stop.
|
|
2290
|
+
- **Nothing of your endpoint leaves the host.** A status row carries the
|
|
2291
|
+
capability and, on its own host only, the endpoint's `threadId` when it
|
|
2292
|
+
is a string; the endpoint is on local inspect, spawn and start answers.
|
|
2293
|
+
`open` is relayed: make its `url` one a viewer may open, never your API's
|
|
2294
|
+
address off its host, and put no token in either.
|