@awebai/oats 0.49.0 → 0.51.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 +150 -34
- package/docs/capabilities.md +172 -2
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +268 -22
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +120 -9
- package/docs/implementation.md +26 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +20 -7
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/schedules.md +228 -15
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +92 -8
- package/docs/workspaces.md +2 -2
- package/lib/capability-show.mjs +14 -1
- package/lib/claim.mjs +126 -0
- package/lib/core.mjs +428 -102
- package/lib/instance-events.mjs +3 -7
- package/lib/instance-git.mjs +8 -5
- package/lib/instance-inspect.mjs +44 -15
- package/lib/refused-text.mjs +17 -0
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/schedule.mjs +8 -2
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/lib/worktree-hooks.mjs +24 -9
- package/lib/worktree.mjs +14 -86
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
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, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
33
|
+
findInstanceHome, findInstanceHomes, processScanInformation, 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, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, 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 {
|
|
@@ -55,13 +55,14 @@ import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_
|
|
|
55
55
|
import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
|
|
56
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
|
+
import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
|
|
58
59
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
59
60
|
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
60
61
|
import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
|
|
61
62
|
|
|
62
63
|
const rawArgs = process.argv.slice(2);
|
|
63
64
|
/** 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", "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
|
+
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", "run-source", "self", "verbose", "yes", "yolo"]);
|
|
65
66
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
66
67
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
67
68
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -97,7 +98,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]
|
|
|
97
98
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
98
99
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
99
100
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
100
|
-
const KERNEL_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", "server-probe-features", "worktree-event"];
|
|
101
|
+
const KERNEL_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", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key"];
|
|
101
102
|
/** Commands `--server <id>` runs on a registered server. */
|
|
102
103
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
103
104
|
const flag = (name) => {
|
|
@@ -726,6 +727,14 @@ async function doctorJson(dir) {
|
|
|
726
727
|
function legacyLayoutProblems(root) {
|
|
727
728
|
return [legacyLocalAgents(root), legacyCapturedHomes(root)].filter(Boolean);
|
|
728
729
|
}
|
|
730
|
+
/** What retires left in the deployment (#703 part 2a), read-only: the
|
|
731
|
+
* `retained-recovery:` and `retained-worktree:` information lines, as one
|
|
732
|
+
* block per kind (a count line, then one line per item). */
|
|
733
|
+
function doctorRetained(ws) {
|
|
734
|
+
const deployment = dirname(ws.local.path);
|
|
735
|
+
const kept = retainedWorktrees(deployment);
|
|
736
|
+
return [retainedRecoveryLines(join(deployment, "agents"), kept), retainedWorktreeLines(kept)].filter((block) => block.length);
|
|
737
|
+
}
|
|
729
738
|
async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
730
739
|
const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
|
|
731
740
|
const agentsRoot = join(dirname(ws.local.path), "agents");
|
|
@@ -739,7 +748,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
739
748
|
schemaVersion: 1, workspaceApi: 2, context: ctx,
|
|
740
749
|
workspace: { file: ws.local.path, ref: ws.local.workspace },
|
|
741
750
|
workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
|
|
742
|
-
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information],
|
|
751
|
+
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
743
752
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
744
753
|
...(problems.length ? { problems } : {}),
|
|
745
754
|
warnings: hookEvents.warnings,
|
|
@@ -784,7 +793,8 @@ async function doctor(dir) {
|
|
|
784
793
|
for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
785
794
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
786
795
|
for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
|
|
787
|
-
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information]) console.log(`\nINFO: ${line}`);
|
|
796
|
+
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
797
|
+
for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
|
|
788
798
|
if (soulName) {
|
|
789
799
|
const information = operationalKnowledgeNote(composition, soulName);
|
|
790
800
|
if (information) console.log(`\nINFO: ${information}`);
|
|
@@ -1364,7 +1374,7 @@ function sayReadNotices() {
|
|
|
1364
1374
|
}
|
|
1365
1375
|
/** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
|
|
1366
1376
|
* → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
|
|
1367
|
-
const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, and the read forms of teams and soul teams";
|
|
1377
|
+
const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, trigger poll, and the read forms of teams and soul teams";
|
|
1368
1378
|
function maxAgeRefusal(command, head) {
|
|
1369
1379
|
const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
|
|
1370
1380
|
const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
|
|
@@ -1377,6 +1387,8 @@ function maxAgeRefusal(command, head) {
|
|
|
1377
1387
|
case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
|
|
1378
1388
|
// `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
|
|
1379
1389
|
case "soul": return word(1) === "teams" ? null : refuse(["soul", word(1)].filter(Boolean).join(" "));
|
|
1390
|
+
// A capability source's poll resolves its soul as a read (the tick's child passes --max-age 600).
|
|
1391
|
+
case "trigger": return word(1) === "poll" ? null : refuse(["trigger", word(1)].filter(Boolean).join(" "));
|
|
1380
1392
|
default: {
|
|
1381
1393
|
const sub = ["package", "schedule", "session", "trigger", "automations", "launch-config", "server", "instance", "operation", "pane"].includes(command) ? word(1) : undefined;
|
|
1382
1394
|
return refuse([command, sub].filter(Boolean).join(" "));
|
|
@@ -1718,7 +1730,9 @@ async function addWorkspaceAutomation(desc, { id, body, description }) {
|
|
|
1718
1730
|
const content = A.automationFileText(desc, { id, description: description || undefined, runsOn, owner, body });
|
|
1719
1731
|
const parsed = A.parseAutomationFile(desc, { stem: id, path: `${desc.folder}/${id}.yaml`, bytes: Buffer.from(content), member: name, repoKey: row.key, commit: row.commit });
|
|
1720
1732
|
if (parsed.problem) bail(parsed.problem.code, parsed.problem.message, { path: parsed.problem.path });
|
|
1721
|
-
await desc.expand(parsed.entry);
|
|
1733
|
+
const def = await desc.expand(parsed.entry);
|
|
1734
|
+
// A capability source's trigger means something only against its soul's resolution: checked before the file is written.
|
|
1735
|
+
if (desc.kind === "trigger") await (await import("../lib/triggers.mjs")).checkAddMeaning(ctx.deploymentDir, def, { remoteOptions: ctx.remoteOptions });
|
|
1722
1736
|
const sameRepo = (url) => { try { return remoteModule.parseRepoRef(url).key === row.key; } catch { return false; } };
|
|
1723
1737
|
const at = A.memberCheckoutFor(dirFlag(), desc, id, { sameRepo });
|
|
1724
1738
|
const file = { member: name, repoKey: row.key, path: `${desc.folder}/${id}.yaml`, content };
|
|
@@ -2155,6 +2169,17 @@ async function capabilityShowCmd(bail) {
|
|
|
2155
2169
|
if (skill.filesTruncated) console.log(` … more files (the first ${S.FILES_PER_SKILL} are listed)`);
|
|
2156
2170
|
}
|
|
2157
2171
|
}
|
|
2172
|
+
if (doc.triggerSources !== undefined) {
|
|
2173
|
+
// As declared (a malformed declaration is shown, never refused): names, commands and events, made safe to print.
|
|
2174
|
+
const { safeText } = await import("../lib/refused-text.mjs");
|
|
2175
|
+
const decl = doc.triggerSources && typeof doc.triggerSources === "object" && !Array.isArray(doc.triggerSources) ? doc.triggerSources : null;
|
|
2176
|
+
console.log(decl && Object.keys(decl).length ? " trigger sources:" : ` trigger sources: ${decl ? "(none)" : "(malformed — see trigger source problems)"}`);
|
|
2177
|
+
for (const [n, src] of Object.entries(decl ?? {})) {
|
|
2178
|
+
const o = src && typeof src === "object" ? src : {};
|
|
2179
|
+
console.log(` ${safeText(n, 60)} command ${typeof o.command === "string" ? safeText(o.command, 60) : "?"} events ${Array.isArray(o.events) ? o.events.map((e) => safeText(String(e), 40)).join(",") : "?"}${typeof o.description === "string" ? ` — ${safeText(o.description, 200)}` : ""}`);
|
|
2180
|
+
}
|
|
2181
|
+
for (const p of doc.triggerSourceProblems ?? []) console.log(` trigger source problem: ${p.pointer} — ${safeText(p.message, 300)}`);
|
|
2182
|
+
}
|
|
2158
2183
|
for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
|
|
2159
2184
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
2160
2185
|
console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
|
|
@@ -2623,8 +2648,13 @@ async function spawnCmd() {
|
|
|
2623
2648
|
if (f !== undefined) {
|
|
2624
2649
|
if (!existsSync(f)) bail("E_BAD_ARGS", `--trigger-event not found: ${f}`);
|
|
2625
2650
|
try { triggerEvent = JSON.parse(readFileSync(f, "utf8")); } catch (e) { bail("E_BAD_ARGS", `--trigger-event is not valid JSON: ${e.message}`); }
|
|
2626
|
-
|
|
2627
|
-
|
|
2651
|
+
// A pull-request event names its repo and number; a capability source's, its subject and key,
|
|
2652
|
+
// and its fields, recorded in instance.json, are a plain object of strings.
|
|
2653
|
+
const stringMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
|
|
2654
|
+
const ok = triggerEvent && typeof triggerEvent === "object" && !Array.isArray(triggerEvent) && typeof triggerEvent.trigger === "string" && typeof triggerEvent.source === "string" && typeof triggerEvent.event === "string"
|
|
2655
|
+
&& (triggerEvent.source === "github.pull_request" ? typeof triggerEvent.repo === "string" && Number.isInteger(triggerEvent.number)
|
|
2656
|
+
: typeof triggerEvent.subject === "string" && typeof triggerEvent.key === "string" && (triggerEvent.fields === undefined || stringMap(triggerEvent.fields)));
|
|
2657
|
+
if (!ok) bail("E_BAD_ARGS", "--trigger-event must hold { trigger, source, repo, number, url, event, headSha, labels, observedAt } (github.pull_request) or { trigger, source, subject, event, key, url?, fields, observedAt } (a capability source; fields an object of strings)");
|
|
2628
2658
|
} }
|
|
2629
2659
|
const relativeRoot = flag("relative-root");
|
|
2630
2660
|
if (relativeRoot !== undefined && (relativeRoot === true || !String(relativeRoot).trim())) bail("E_BAD_ARGS", "--relative-root needs an agents-root path");
|
|
@@ -2844,27 +2874,42 @@ function retireCmd() {
|
|
|
2844
2874
|
// resolved the home). A guarded apply acts on the children of the plan it
|
|
2845
2875
|
// revalidated; a plain or --self retire computes them as the plan does, and
|
|
2846
2876
|
// passes none when there are none.
|
|
2847
|
-
let replayPath = null,
|
|
2877
|
+
let replayPath = null, fresh, revalidate, stalePlan, planFailure;
|
|
2848
2878
|
if (planRev !== undefined) {
|
|
2849
2879
|
if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
|
|
2850
2880
|
// Replay first: after a successful retire the home is gone, so the receipt
|
|
2851
2881
|
// (beside the instances dir, keyed by the idempotency key) is the answer.
|
|
2852
2882
|
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; } };
|
|
2853
2883
|
for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
|
|
2854
|
-
|
|
2855
|
-
|
|
2856
|
-
|
|
2857
|
-
|
|
2858
|
-
|
|
2859
|
-
|
|
2860
|
-
|
|
2884
|
+
// Before the claim, only the home: where the receipt goes, and the answers of a name that
|
|
2885
|
+
// resolves to no home, to several or to another one.
|
|
2886
|
+
let target;
|
|
2887
|
+
try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
|
|
2888
|
+
replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
|
|
2889
|
+
// The plan the revision is checked against is read once, by retireInstance, when it holds the
|
|
2890
|
+
// home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
|
|
2891
|
+
// the state the retire starts from. Against another retire of this home the answer is that one
|
|
2892
|
+
// is running (E_LIFECYCLE_BUSY), and no plan is read. A revision that no longer matches is
|
|
2893
|
+
// refused there, and nothing was done. What the retire takes from the plan: its children, and
|
|
2894
|
+
// its extra trees as it names them (the retire refuses as stale rather than move or remove one
|
|
2895
|
+
// that no longer reads that way when it gets to them).
|
|
2896
|
+
revalidate = () => {
|
|
2897
|
+
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
|
|
2898
|
+
if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
|
|
2899
|
+
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
|
|
2900
|
+
};
|
|
2861
2901
|
} else {
|
|
2862
|
-
|
|
2863
|
-
|
|
2902
|
+
// A plain or --self retire reads its recorded children the same way: under the claim, as they
|
|
2903
|
+
// are when the retire starts (an earlier retire that kept the home has repaired lineage by
|
|
2904
|
+
// then), and none when there are none.
|
|
2905
|
+
revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
|
|
2864
2906
|
}
|
|
2865
2907
|
let r;
|
|
2866
|
-
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"),
|
|
2908
|
+
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
|
|
2867
2909
|
catch (e) {
|
|
2910
|
+
// The plan could not be read, or its revision is not the one shown: the answers they always had.
|
|
2911
|
+
if (e === planFailure) return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message);
|
|
2912
|
+
if (e === stalePlan) return args.includes("--json") ? jsonFail(e.code, e.message, e.details) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
|
|
2868
2913
|
if (!e?.code) throw e;
|
|
2869
2914
|
// A child still running (or whose stop could not be established) refused the retirement: the
|
|
2870
2915
|
// guarded apply returns the plan it acted on, and the text names each child's reason.
|
|
@@ -3031,13 +3076,24 @@ async function triggerCmd() {
|
|
|
3031
3076
|
const sub = args[1];
|
|
3032
3077
|
const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
|
|
3033
3078
|
const T = await import("../lib/triggers.mjs");
|
|
3079
|
+
const { REFUSED_TEXT, safeText } = await import("../lib/refused-text.mjs");
|
|
3034
3080
|
let scope;
|
|
3035
3081
|
const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
|
|
3036
|
-
|
|
3082
|
+
// A stored definition that fails validation is still listed and shown, as it was written: what a
|
|
3083
|
+
// terminal gets of it never carries a refused character. In a row's text it is replaced (`shown`);
|
|
3084
|
+
// in the JSON `show` prints as text it is escaped (\uXXXX; the layout's own newlines stay), so the document's value is unchanged.
|
|
3085
|
+
const shown = (v, max) => safeText(typeof v === "string" ? v : JSON.stringify(v) ?? String(v), max);
|
|
3086
|
+
const escaped = (json) => json.replace(new RegExp(REFUSED_TEXT.source, "gu"), (c) => (c === "\n" ? c : Array.from({ length: c.length }, (_, i) => `\\u${c.charCodeAt(i).toString(16).padStart(4, "0")}`).join("")));
|
|
3087
|
+
const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : escaped(JSON.stringify(result, null, 2))); };
|
|
3037
3088
|
const needId = () => { if (!id) throw T.triggerError("E_BAD_ARGS", `oats trigger ${sub} <id>`); return id; };
|
|
3038
|
-
const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] | update <id> --description=<text> | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> | status [<id>] [--dir <deployment>] [--json] (<id>: local/<id> or <member>/<id
|
|
3089
|
+
const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] | update <id> --description=<text> | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> [--run-source] | poll <id> --run-source [--max-age <s>] | status [<id>] [--dir <deployment>] [--json] (<id>: local/<id> or <member>/<id>; --run-source: run a capability source's command on this host, which test and poll do only when asked)";
|
|
3039
3090
|
const where = (t) => (t.origin?.kind === "workspace" ? (t.runsHere ? `runs here as ${t.owner}` : `${t.reason === "assigned-elsewhere" ? `runs on ${t.runsOn}` : t.reason ?? "disabled here"}`) : t.enabledHere ? "local" : "local, disabled");
|
|
3040
|
-
|
|
3091
|
+
// A capability source names its params where the built-in names its repository.
|
|
3092
|
+
const watched = (on) => (T.isCapabilitySource(on?.source) ? `${on.source}${Object.keys(on.params || {}).length ? ` ${Object.entries(on.params).map(([k, v]) => `${shown(k, 40)}=${shown(v, 200)}`).join(" ")}` : ""}` : `${on?.source ?? "?"} ${on?.repo ?? "?"}`);
|
|
3093
|
+
// One row, one line, whatever an invalid stored definition holds (its id, labels and soul are as written too).
|
|
3094
|
+
const line = (t) => safeText(`${t.id} ${where(t)} ${watched(t.on)} [${T.isCapabilitySource(t.on?.source) ? shown((t.on?.events || []).join(","), 700) : (t.on?.events || []).join(",")}]${t.on?.labels?.length ? ` labels ${t.on.labels.join(",")}` : ""} every ${t.on?.poll ?? "?"} → spawn ${t.spawn?.soul ?? "?"}${t.spawn?.teams?.length ? ` in ${t.spawn.teams.join(",")}` : ""}${t.invalid ? ` INVALID: ${t.invalid.message}` : ""}`, 8000);
|
|
3095
|
+
// A source's own words are printed only under this label, never as the kernel's (docs/schedules.md).
|
|
3096
|
+
const said = (x) => (x ? `source says: ${x.code}${x.message ? `: ${x.message}` : ""}` : "");
|
|
3041
3097
|
// The workspace automations of this deployment (the snapshot) placed on this host.
|
|
3042
3098
|
let actx;
|
|
3043
3099
|
const ctx = () => (actx ??= scopeAutomations(ws(), {}));
|
|
@@ -3065,7 +3121,31 @@ async function triggerCmd() {
|
|
|
3065
3121
|
return out({ trigger: T.updateTriggerDescription(ws(), needId(), description, ctx()) }, (r) => line(r.trigger));
|
|
3066
3122
|
}
|
|
3067
3123
|
case "remove": return out(T.removeTrigger(ws(), needId(), ctx()), (r) => `removed trigger ${r.removed}${r.live.length ? ` (its live instances keep running: ${r.live.join(", ")})` : ""}`);
|
|
3068
|
-
case "status": return out(T.triggerStatus(ws(), id, ctx()), (r) => r.triggers.map((t) =>
|
|
3124
|
+
case "status": return out(T.triggerStatus(ws(), id, ctx()), (r) => r.triggers.map((t) => {
|
|
3125
|
+
if (!t.source) return `${t.id} last poll ${t.lastPoll ? `${t.lastPoll.at} ${t.lastPoll.ok ? `ok (${t.lastPoll.matching}/${t.lastPoll.prs} PRs match)` : `FAILED: ${t.lastPoll.error}`}` : "never"} pending ${t.pending.length} fired ${t.firedTotal} live ${t.live.map((l) => l.instance).join(",") || "none"}${t.lastError ? `\n last error ${t.lastError.at}: ${t.lastError.message}` : ""}`;
|
|
3126
|
+
const lp = t.lastPoll;
|
|
3127
|
+
return [`${t.id} source ${t.source.capability}:${t.source.name} last poll ${lp ? `${lp.at} ${lp.ok ? `ok (${lp.events} events, ${lp.invalidEvents} invalid, ${lp.skipped} skipped, ${lp.filtered} filtered)` : `FAILED (${lp.cause ?? "?"}): ${lp.error}`}` : "never"} pending ${t.pending.length} fired ${t.firedTotal} live ${t.live.map((l) => l.instance).join(",") || "none"}`,
|
|
3128
|
+
...(t.invalid ? [` INVALID ${t.invalid.at}: ${t.invalid.code}: ${t.invalid.message}`] : []),
|
|
3129
|
+
...(lp && !lp.ok && lp.source ? [` ${said(lp.source)}`] : []),
|
|
3130
|
+
...t.invalidEvents.map((x) => ` invalid event (${x.rule}): ${x.text}`),
|
|
3131
|
+
...t.skipped.map((x) => ` skipped ${x.subject}, source says: ${x.why}`),
|
|
3132
|
+
...(t.lastError && !t.invalid ? [` last error ${t.lastError.at}: ${t.lastError.message}`] : [])].join("\n");
|
|
3133
|
+
}).join("\n") || "(no triggers)");
|
|
3134
|
+
case "poll": {
|
|
3135
|
+
// Runs the capability's source command now (records nothing, spawns nothing), and so only with
|
|
3136
|
+
// --run-source: the caller's intent, never trust consent (the tick's child passes it). The tick's own
|
|
3137
|
+
// child gets OATS_TRIGGER_POLL_DEADLINE (epoch ms; internal between the tick and its child,
|
|
3138
|
+
// not a contract): its source gets only what is left before it (lib/triggers.mjs pollViaChild).
|
|
3139
|
+
const raw = process.env.OATS_TRIGGER_POLL_DEADLINE;
|
|
3140
|
+
const deadline = raw && /^\d+$/.test(raw) ? Number(raw) : null;
|
|
3141
|
+
const r = await T.pollSource(ws(), needId(), { ctx: ctx(), remoteOptions: remoteOptionsFromEnv(), deadline, runSource: args.includes(T.RUN_SOURCE_FLAG) });
|
|
3142
|
+
if (JSON_MODE) { jsonOk(withObservation(r)); return; }
|
|
3143
|
+
return out(r, (x) => [`trigger ${x.id}: ${x.source.capability}:${x.source.name} listed ${x.events.length} event(s) (nothing recorded, nothing spawned)`,
|
|
3144
|
+
...x.events.map((ev) => ` ${ev.event} ${ev.subject} ${ev.key}`),
|
|
3145
|
+
...(x.filtered ? [` ${x.filtered} filtered (events the trigger does not select)`] : []),
|
|
3146
|
+
...x.invalidEvents.map((v) => ` invalid event (${v.rule}): ${v.text}`),
|
|
3147
|
+
...x.skipped.map((k) => ` skipped ${k.subject}, source says: ${k.why}`)].join("\n"));
|
|
3148
|
+
}
|
|
3069
3149
|
case "test": {
|
|
3070
3150
|
let workspaceTeams = null;
|
|
3071
3151
|
try {
|
|
@@ -3075,7 +3155,23 @@ async function triggerCmd() {
|
|
|
3075
3155
|
const shared = typeof local.workspace === "string" && !local.standalone ? (await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace : null;
|
|
3076
3156
|
workspaceTeams = [...teamModel(shared, local).labels.keys()];
|
|
3077
3157
|
} catch { /* reported as unknown (null) */ }
|
|
3078
|
-
|
|
3158
|
+
// --run-source: a capability source's command runs only when asked (inert for the built-in).
|
|
3159
|
+
const tested = await T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx(), remoteOptions: remoteOptionsFromEnv(), runSource: args.includes(T.RUN_SOURCE_FLAG) });
|
|
3160
|
+
if (tested.source) return out(tested, (r) => [
|
|
3161
|
+
`trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (${r.source.invalid || r.source.cause === "resolution" ? "the source did not run" : "the source ran"}; nothing was recorded or spawned)`,
|
|
3162
|
+
` placement ${r.placement.runsOn ? `runs on ${r.placement.runsOn} as ${r.placement.owner}; this host is ${r.placement.host ?? "(unnamed)"} — ${r.placement.runsHere ? "runs here" : r.placement.reason ?? "disabled here"}` : "local (this host)"}`,
|
|
3163
|
+
...(r.gh ? [` gh auth ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`] : []),
|
|
3164
|
+
` source ${r.source.capability}:${r.source.name} ${r.source.ok ? `listed ${r.source.events.length} event(s), ${r.source.invalidEvents.length} invalid, ${r.source.skipped.length} skipped, ${r.source.filtered} filtered` : r.source.invalid ? `INVALID: ${r.source.invalid.message}` : `FAILED (${r.source.cause ?? "?"}): ${r.source.error.message}`}`,
|
|
3165
|
+
...(r.source.source ? [` ${said(r.source.source)}`] : []),
|
|
3166
|
+
...r.source.invalidEvents.map((v) => ` invalid (${v.rule}) ${v.text}`),
|
|
3167
|
+
...r.source.skipped.map((k) => ` skipped ${k.subject}, source says: ${k.why}`),
|
|
3168
|
+
` soul ${r.soul.name} ${r.soul.resolves ? `resolves${r.soul.messaging ? ` (messaging ${r.soul.messaging})` : ""}` : `does NOT resolve: ${r.soul.error.code} ${r.soul.error.message}`}`,
|
|
3169
|
+
` teams ${r.teams.requested.join(", ") || "(none)"}${r.teams.undeclared?.length ? ` undeclared: ${r.teams.undeclared.join(", ")}` : ""}`,
|
|
3170
|
+
` would fire ${r.wouldFire.length ? r.wouldFire.map((w) => `${w.event} ${w.subject}${w.instance ? ` as ${w.instance}` : ""}${w.held ? ` (held: ${w.held})` : ""}`).join(", ") : "nothing now"}`,
|
|
3171
|
+
...r.problems.map((p) => ` problem ${p}`),
|
|
3172
|
+
...(r.warnings ?? []).map((w) => ` warning ${w}`),
|
|
3173
|
+
].join("\n"));
|
|
3174
|
+
return out(tested, (r) => [
|
|
3079
3175
|
`trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (nothing was spawned)`,
|
|
3080
3176
|
` placement ${r.placement.runsOn ? `runs on ${r.placement.runsOn} as ${r.placement.owner}; this host is ${r.placement.host ?? "(unnamed)"} — ${r.placement.runsHere ? "runs here" : r.placement.reason ?? "disabled here"}` : "local (this host)"}`,
|
|
3081
3177
|
` gh auth ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`,
|
|
@@ -3118,7 +3214,9 @@ async function triggerCmd() {
|
|
|
3118
3214
|
return out(r, printWorkspaceAdd);
|
|
3119
3215
|
}
|
|
3120
3216
|
if (spec === undefined) spec = await triggerFromPackage(T, String(from), sets, idFlag);
|
|
3121
|
-
|
|
3217
|
+
// A capability source's meaning needs the soul's resolution (asynchronous, so here, before the write).
|
|
3218
|
+
await T.checkAddMeaning(ws(), T.validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" }), { remoteOptions: remoteOptionsFromEnv() });
|
|
3219
|
+
return out({ trigger: T.addTrigger(ws(), withDescription(spec, description)) }, (r) => `added ${line(r.trigger)}\n(\`oats trigger test ${r.trigger.id}${T.isCapabilitySource(r.trigger.on?.source) ? ` ${T.RUN_SOURCE_FLAG}\` runs ${r.trigger.on.source}'s source command on this host and checks the soul and the teams)` : "` checks gh, the repository, the soul and the teams on this host)"}`);
|
|
3122
3220
|
}
|
|
3123
3221
|
default: throw T.triggerError("E_BAD_ARGS", usage);
|
|
3124
3222
|
}
|
|
@@ -3141,7 +3239,9 @@ async function sessionCmd() {
|
|
|
3141
3239
|
let result;
|
|
3142
3240
|
if (args[1] === "attach") {
|
|
3143
3241
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3144
|
-
|
|
3242
|
+
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3243
|
+
// status 20. Without it every key reaches the agent and there is no keyboard exit.
|
|
3244
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
|
|
3145
3245
|
return;
|
|
3146
3246
|
}
|
|
3147
3247
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -3181,7 +3281,7 @@ async function sessionCmd() {
|
|
|
3181
3281
|
const file = flag("file");
|
|
3182
3282
|
if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
|
|
3183
3283
|
result = uploadAttachment({ file, home: home === true ? undefined : home });
|
|
3184
|
-
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3284
|
+
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3185
3285
|
if (JSON_MODE) jsonOk(result);
|
|
3186
3286
|
else {
|
|
3187
3287
|
console.log(JSON.stringify(result, null, 2));
|
|
@@ -4008,8 +4108,14 @@ async function serverRouteCmd() {
|
|
|
4008
4108
|
return;
|
|
4009
4109
|
}
|
|
4010
4110
|
if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session restart`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
|
|
4111
|
+
// --detach-key travels only to a host that advertises session-attach-detach-key (attachArgv
|
|
4112
|
+
// probes for it, under --print too). The key may be C-\, the tty's QUIT character: pressed
|
|
4113
|
+
// once ssh has given the tty back, it reaches this process as SIGQUIT, whose default action
|
|
4114
|
+
// would replace the relayed status with 131. Held from here until this process exits.
|
|
4115
|
+
const detachKey = valueFlag("detach-key");
|
|
4116
|
+
if (detachKey !== undefined) process.on("SIGQUIT", () => {});
|
|
4011
4117
|
let route;
|
|
4012
|
-
try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
|
|
4118
|
+
try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
|
|
4013
4119
|
// ssh failing before the viewer (the version probe, a name resolved through the host's roster)
|
|
4014
4120
|
// is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
|
|
4015
4121
|
// and an ssh that never started (no link can come back), exits 1.
|
|
@@ -4019,7 +4125,7 @@ async function serverRouteCmd() {
|
|
|
4019
4125
|
// ssh exits 255 for its own failures: a link that died under the viewer
|
|
4020
4126
|
// (keepalives unanswered, the master or the host's sshd gone), or one
|
|
4021
4127
|
// never made. Say what is known rather than ending silently.
|
|
4022
|
-
if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}`);
|
|
4128
|
+
if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}${detachKey !== undefined ? ` --detach-key ${shellQuote(detachKey)}` : ""}`);
|
|
4023
4129
|
process.exit(r.status ?? 1);
|
|
4024
4130
|
}
|
|
4025
4131
|
// A spawn's argv is checked here, before the server is contacted.
|
|
@@ -4303,7 +4409,9 @@ Usage:
|
|
|
4303
4409
|
--instance <name> [--json] saved home on its host
|
|
4304
4410
|
oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
|
|
4305
4411
|
--instance <name> | --home <abs> remote instance, by its saved route or the server's
|
|
4306
|
-
|
|
4412
|
+
[--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
|
|
4413
|
+
attach --detach-key: as below; the server must
|
|
4414
|
+
advertise session-attach-detach-key
|
|
4307
4415
|
oats session start --server <id> start a stopped remote instance in its existing home
|
|
4308
4416
|
--instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
|
|
4309
4417
|
[--model <m>] [--json] session-start (oats 0.22.9 or later)
|
|
@@ -4326,6 +4434,11 @@ Usage:
|
|
|
4326
4434
|
[--check] --check: write nothing; report <dir> (~ = this home),
|
|
4327
4435
|
its state and whether Git reads the workspace remote
|
|
4328
4436
|
oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
|
|
4437
|
+
oats session attach --home <absolute-home> [--detach-key <key>]
|
|
4438
|
+
a viewer of one instance. <key> (C-<letter>, M-<letter
|
|
4439
|
+
or digit>, F1 to F12; 'C-\\' is the suggested one)
|
|
4440
|
+
leaves it with exit status 20; without one no key
|
|
4441
|
+
leaves it: every key goes to the agent
|
|
4329
4442
|
oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
|
|
4330
4443
|
enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
|
|
4331
4444
|
tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
|
|
@@ -4335,9 +4448,12 @@ Usage:
|
|
|
4335
4448
|
oats schedule add|update <id> … --description=<text> a one-line summary (1-200 characters)
|
|
4336
4449
|
oats schedule update <id> --description=<text> change only it (--description= clears it)
|
|
4337
4450
|
oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
|
|
4338
|
-
| disable | remove <id> | test <id> | status [<id>] event-driven spawns
|
|
4339
|
-
|
|
4340
|
-
|
|
4451
|
+
| disable | remove <id> | test <id> | poll <id> | status [<id>] event-driven spawns, polled
|
|
4452
|
+
by the schedule tick: github.pull_request (the
|
|
4453
|
+
host's gh) or a capability's <capability>:<source>;
|
|
4454
|
+
see docs/schedules.md#triggers
|
|
4455
|
+
oats trigger test|poll <id> --run-source run a capability source's command on this host: by
|
|
4456
|
+
hand, test and poll do it only when asked
|
|
4341
4457
|
oats trigger add … --description=<text> a one-line summary (1-200 characters)
|
|
4342
4458
|
oats trigger update <id> --description=<text> change only it (--description= clears it)
|
|
4343
4459
|
oats trigger|schedule add … --workspace <member> --runs-on <host> --owner <host>/<login>
|
package/docs/capabilities.md
CHANGED
|
@@ -205,8 +205,9 @@ A self-contained package has an `oats.json`:
|
|
|
205
205
|
Whether the process exists is the operating system's answer (`kill -0`:
|
|
206
206
|
"no such process" is gone, another user's process exists), the same on
|
|
207
207
|
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
|
-
|
|
209
|
-
|
|
208
|
+
where there is no `/proc`, as on macOS: the system `ps`, from
|
|
209
|
+
`/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
|
|
210
|
+
`TZ=UTC` environment. A start that cannot be read is never taken to mean the process is
|
|
210
211
|
gone, nor shown as alive: `oats status` shows the quarantine
|
|
211
212
|
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
212
213
|
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
|
@@ -353,6 +354,9 @@ A self-contained package has an `oats.json`:
|
|
|
353
354
|
separate from declaring the package.
|
|
354
355
|
- `environment` lists the exact launch variables the capability may set;
|
|
355
356
|
spawn hook output must be a subset and use the capability vendor prefix.
|
|
357
|
+
- `triggerSources` (optional) declares the capability's
|
|
358
|
+
[trigger sources](#trigger-sources-triggersources). It is checked only
|
|
359
|
+
where a source is used, never when the capability loads.
|
|
356
360
|
- Target names never appear in a package manifest.
|
|
357
361
|
|
|
358
362
|
`capability` is the only manifest identity field; it may also carry
|
|
@@ -1264,3 +1268,169 @@ checks in one readiness read share 60 s, and checks the budget does not reach
|
|
|
1264
1268
|
are not run (`unknown`, `time-budget-exhausted`). Answer from configuration
|
|
1265
1269
|
and local state. A provider that must call a remote service should bound that
|
|
1266
1270
|
call well inside the 30 s.
|
|
1271
|
+
|
|
1272
|
+
## Trigger sources (`triggerSources`)
|
|
1273
|
+
|
|
1274
|
+
A capability may declare **trigger sources**: each is one of its own commands
|
|
1275
|
+
that, at each poll, lists the events that are due now. A
|
|
1276
|
+
[trigger](schedules.md#capability-sources) names one as `on.source:
|
|
1277
|
+
"<capability>:<source>"`, and the kernel keeps everything after the list:
|
|
1278
|
+
event keys, at-least-once recording, pending events, concurrency, the
|
|
1279
|
+
instance name, the event file and the spawn.
|
|
1280
|
+
|
|
1281
|
+
```json
|
|
1282
|
+
"commands": { "review-source": "bin/graph.mjs review-source" },
|
|
1283
|
+
"triggerSources": {
|
|
1284
|
+
"harvest-branches": {
|
|
1285
|
+
"command": "review-source",
|
|
1286
|
+
"description": "Ready harvest/* branches, one event per judged head",
|
|
1287
|
+
"events": ["opened", "updated"],
|
|
1288
|
+
"parameters": { "prefix": { "default": "harvest/", "description": "Branch prefix", "pattern": "^[A-Za-z0-9._/-]{1,80}$" } },
|
|
1289
|
+
"fields": { "graph": { "pattern": "^[a-z0-9-]{1,40}$" }, "branch": {} },
|
|
1290
|
+
"urlHosts": ["graph.example.org"]
|
|
1291
|
+
}
|
|
1292
|
+
}
|
|
1293
|
+
```
|
|
1294
|
+
|
|
1295
|
+
- **The source name** is 1 to 40 lowercase letters, digits and dashes,
|
|
1296
|
+
starting with a letter or digit. At most 16 sources.
|
|
1297
|
+
- **`command`** names one of `commands`. Its script must resolve to a regular
|
|
1298
|
+
file inside the module directory.
|
|
1299
|
+
- **`description`** (optional): one line of at most 200 characters.
|
|
1300
|
+
- **`events`**: 1 to 16 distinct names, each 1 to 40 lowercase letters,
|
|
1301
|
+
digits and underscores, starting with a letter.
|
|
1302
|
+
- **`parameters`** (optional, at most 16), named with a letter then letters,
|
|
1303
|
+
digits and underscores (at most 40): `{ required?, default?, description?,
|
|
1304
|
+
pattern? }`. A value is a string of at most 200 characters matching
|
|
1305
|
+
`pattern`, by default `^[A-Za-z0-9._/:@ ,*-]{0,200}$`; a `default` must
|
|
1306
|
+
match it too. Parameters reach the source only, never a task.
|
|
1307
|
+
- **`fields`** (optional, at most 16, named as parameters): `{ pattern? }`, by
|
|
1308
|
+
default `^[A-Za-z0-9._/:@-]{1,200}$`. A trigger's template may name a
|
|
1309
|
+
declared field as `{fields.<name>}`; the value is the event's, validated.
|
|
1310
|
+
Whatever the pattern admits (`.*` included), a value longer than 200
|
|
1311
|
+
characters (code points), or carrying a control character, a line or
|
|
1312
|
+
paragraph separator, a bidi control, U+200B, U+2060, U+FEFF or a tag
|
|
1313
|
+
character, makes its event invalid, and the pattern is never run on one.
|
|
1314
|
+
- **Patterns** are JavaScript regular expressions with the `u` flag (the flag
|
|
1315
|
+
JSON Schema's `pattern` uses), compiled once and always matched whole: the
|
|
1316
|
+
kernel wraps each as `^(?:…)$`. One that does not compile makes the source
|
|
1317
|
+
malformed.
|
|
1318
|
+
- **`urlHosts`** (optional, at most 16): the exact lowercase hostnames an
|
|
1319
|
+
event's `url` may name. With none declared, an event's `url` is invalid.
|
|
1320
|
+
The allow-list lives here, never on an event. An event's `url` must also be
|
|
1321
|
+
printable ASCII with no space (`0x21`–`0x7e`) as written: percent-encode
|
|
1322
|
+
anything else.
|
|
1323
|
+
|
|
1324
|
+
**Containment.** A malformed `triggerSources` **never refuses the
|
|
1325
|
+
capability**. It is not part of the manifest contract that spawn, discovery
|
|
1326
|
+
and the lock check: they ignore it. It is validated only where a source is
|
|
1327
|
+
used, by `trigger add`, a poll, `trigger test` and `trigger poll`, **per
|
|
1328
|
+
source**: a malformed source fails only the triggers naming it
|
|
1329
|
+
(`E_TRIGGER_SOURCE`, `details: { capability, source, pointer }`, the pointer
|
|
1330
|
+
into the manifest), and a well-formed sibling keeps working. A malformed top
|
|
1331
|
+
level (not an object, or more than 16 sources) fails every trigger naming the
|
|
1332
|
+
capability. `oats capabilities show <name> --json` adds `triggerSources`,
|
|
1333
|
+
exactly as declared, and, when the declaration has any, the problems a trigger
|
|
1334
|
+
would get as `triggerSourceProblems: [{ source, pointer, message }]`
|
|
1335
|
+
(`source` `null` for the top level); it never refuses the command. The
|
|
1336
|
+
closed sub-schema is in
|
|
1337
|
+
[`capability-manifest.schema.json`](capability-manifest.schema.json); what a
|
|
1338
|
+
schema cannot say (a pattern compiles, `command` names a command, a default
|
|
1339
|
+
matches its pattern) is checked at use only.
|
|
1340
|
+
|
|
1341
|
+
**Schema tooling.** The runtime ignores manifest keys it does not know, but
|
|
1342
|
+
until this release the published `capability-manifest.schema.json` was closed
|
|
1343
|
+
at the top level (`additionalProperties: false`). A tool validating a manifest
|
|
1344
|
+
against an older copy of the schema flags `triggerSources`: the repository's
|
|
1345
|
+
own `validate-project`, the package dry-run checks, a provider's CI that pins
|
|
1346
|
+
the schema. Validate against this release's schema, or declare the key once
|
|
1347
|
+
your tooling uses it. A provider declaring `triggerSources` does not need to
|
|
1348
|
+
raise `compatibility.oats`: every workspace-model kernel ignores the key, and
|
|
1349
|
+
only the host that runs a trigger naming the source needs this release.
|
|
1350
|
+
|
|
1351
|
+
**Invocation.** A poll runs the command's script with `node`, from the
|
|
1352
|
+
capability's directory in the deployment's verified module store (the
|
|
1353
|
+
capability at its resolved commit, digest-verified, for a member capability
|
|
1354
|
+
as for a package one), with the command's words after the script as
|
|
1355
|
+
arguments and no shell. The host tick runs it through a child `oats trigger
|
|
1356
|
+
poll <id> --run-source --max-age 600`; a person, through `oats trigger poll
|
|
1357
|
+
<id> --run-source` or `oats trigger test <id> --run-source`. Those
|
|
1358
|
+
**execute the capability's source command** whatever the host's trust and
|
|
1359
|
+
the trigger's `runsOn` say, and so only with `--run-source`: without it they
|
|
1360
|
+
are refused (`E_TRIGGER_SOURCE_RUN`) before anything of the capability runs
|
|
1361
|
+
or is written. The flag is caller intent, never trust consent: see
|
|
1362
|
+
[schedules.md](schedules.md#capability-sources). A poll records nothing on
|
|
1363
|
+
its own; the tick records what it folds.
|
|
1364
|
+
|
|
1365
|
+
**Request** — one JSON document on stdin, with exactly these keys:
|
|
1366
|
+
|
|
1367
|
+
```json
|
|
1368
|
+
{"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","trigger":"local/harvest-review",
|
|
1369
|
+
"params":{"prefix":"harvest/"},"settings":{"store":"~/.graph"},
|
|
1370
|
+
"input":{"context":{"kind":"workspace","workspace":"github.com/acme/agents","deployment":"/srv/acme",
|
|
1371
|
+
"soul":"graph-reviewer","host":"kb-bot-server"}}}
|
|
1372
|
+
```
|
|
1373
|
+
|
|
1374
|
+
- `trigger` is the qualified trigger id.
|
|
1375
|
+
- `params` are the trigger's, with the declared defaults applied (a parameter
|
|
1376
|
+
with neither a value nor a default is absent).
|
|
1377
|
+
- `settings` is the merged provider payload the trigger's soul resolves for
|
|
1378
|
+
the capability.
|
|
1379
|
+
- `host` is this host's `host.name`, or `null`.
|
|
1380
|
+
|
|
1381
|
+
**Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
|
|
1382
|
+
gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
|
|
1383
|
+
variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
|
|
1384
|
+
`OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_WORKSPACE`,
|
|
1385
|
+
the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and `OATS_SOUL`. There is no
|
|
1386
|
+
`OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
|
|
1387
|
+
Under the host timer, the inherited environment is the timer's (only `PATH`
|
|
1388
|
+
and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
|
|
1389
|
+
not in an exported variable.
|
|
1390
|
+
|
|
1391
|
+
**Answer** — exit 0, and exactly one JSON document on stdout, at most 1 MiB
|
|
1392
|
+
(whitespace around it is fine; progress text is not):
|
|
1393
|
+
|
|
1394
|
+
```json
|
|
1395
|
+
{"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","ok":true,
|
|
1396
|
+
"result":{"events":[{"key":"harvest/x:9f2c41d","subject":"harvest/x","event":"opened",
|
|
1397
|
+
"url":"https://graph.example.org/x","fields":{"graph":"kb","branch":"harvest/x"}}],
|
|
1398
|
+
"skipped":[{"subject":"harvest/y","why":"not judged yet"}]}}
|
|
1399
|
+
```
|
|
1400
|
+
|
|
1401
|
+
- **The envelope** has exactly `schemaVersion, phase, capability, source, ok,
|
|
1402
|
+
result`; `schemaVersion`, `phase`, `capability` and `source` echo the
|
|
1403
|
+
request. `result` is `{ events, skipped? }`, exactly.
|
|
1404
|
+
- **A refusal** is `{…, "ok": false, "error": { "code", "message"? }}`.
|
|
1405
|
+
- **An event** is `{ key, subject, event, url?, fields? }`: the rules are in
|
|
1406
|
+
[schedules.md](schedules.md#capability-sources). An invalid event is
|
|
1407
|
+
dropped alone; the others go on.
|
|
1408
|
+
- **`skipped`** (optional) is `[{ subject, why }]`: what the source looked at
|
|
1409
|
+
and chose not to list, shown in `trigger status` and `trigger test`.
|
|
1410
|
+
|
|
1411
|
+
| Outcome | `E_TRIGGER_POLL` `details.cause` | recorded |
|
|
1412
|
+
|---|---|---|
|
|
1413
|
+
| nonzero exit or a signal | `exit` | nothing; pending events kept |
|
|
1414
|
+
| not exactly one JSON document, unknown keys, a wrong echo, a malformed `result`, over 1 MiB | `result` | nothing |
|
|
1415
|
+
| more than 500 events, or more than 100 skipped | `too-many-events` | nothing |
|
|
1416
|
+
| over 30 s (killed) | `timeout` | nothing |
|
|
1417
|
+
| `ok: false` | `refused`, with `details.source: { code, message? }` | nothing |
|
|
1418
|
+
| the soul does not resolve | `resolution` | nothing |
|
|
1419
|
+
| the trigger's meaning does not hold | (`E_TRIGGER_SOURCE` / `E_TRIGGER_INVALID`) | nothing; the source does not run |
|
|
1420
|
+
|
|
1421
|
+
**Your text is untrusted.** A skipped item's `why`, a refusal's `message` and
|
|
1422
|
+
its `code` are never composed into a task or any kernel sentence. They are
|
|
1423
|
+
kept only in fields that name the source and printed under `source says:`,
|
|
1424
|
+
capped (`why` 200 characters, `message` 500, `code` 128) and with every
|
|
1425
|
+
control character, line or paragraph separator, bidi control, U+200B,
|
|
1426
|
+
U+2060, U+FEFF and tag character replaced by U+FFFD. What a task may carry
|
|
1427
|
+
(`{subject}`, `{key}`, `{url}`, `{fields.<name>}`) is refused rather than
|
|
1428
|
+
replaced: an event whose `url` is not printable ASCII, or whose field value
|
|
1429
|
+
is longer than 200 characters or carries one of those characters whatever
|
|
1430
|
+
its pattern admits, is an invalid event.
|
|
1431
|
+
|
|
1432
|
+
**Time.** A source gets at most 30 s and is killed after that; the tick's
|
|
1433
|
+
whole poll, resolution included, gets 35 s, and polls run only while they can
|
|
1434
|
+
end within 50 s of the tick's start. Answer from a cache or a quick query: a
|
|
1435
|
+
source slower than that should cache.
|
|
1436
|
+
|