@awebai/oats 0.69.8 → 0.69.10

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/lib/schedule.mjs CHANGED
@@ -341,7 +341,7 @@ function storedHerdrBackend(ws, id, def) {
341
341
 
342
342
  /** Validate and normalize one definition against its scope. `backendSource` names the file and key
343
343
  * a definition read from elsewhere sets its backend in (default: this scope's definitions file). */
344
- export function validateDefinition(ws, def, { checkAgent = true, backendSource } = {}) {
344
+ export function validateDefinition(ws, def, { checkAgent = true, backendSource, io } = {}) {
345
345
  if (!def || typeof def !== "object" || Array.isArray(def)) throw scheduleError("E_SCHEDULE_INVALID", "definition must be an object", { field: "definition" });
346
346
  if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_INVALID", "kind: a trigger is added with `oats trigger add`, not `oats schedule add`", { field: "kind" });
347
347
  const id = def.id;
@@ -385,7 +385,7 @@ export function validateDefinition(ws, def, { checkAgent = true, backendSource }
385
385
  validateCron(w.cron, w.tz, "wake.cron"); validateMessage(w.message, "wake.message");
386
386
  out.wake = { cron: w.cron.trim(), tz: w.tz.trim(), message: w.message };
387
387
  }
388
- if (checkAgent) resolveScheduledAgent(ws, out);
388
+ if (checkAgent) confirmScheduledSoul(ws, out, io);
389
389
  } else if (def.kind === "command") {
390
390
  if (typeof def.cwd !== "string" || !isAbsolute(def.cwd) || !inside(ws, def.cwd) || !existsSync(def.cwd)) throw scheduleError("E_SCHEDULE_INVALID", "cwd: an existing absolute directory inside the scope", { field: "cwd" });
391
391
  if (!Array.isArray(def.argv) || !def.argv.length || def.argv.some((a) => typeof a !== "string" || a.includes("\0")) || def.argv[0] !== "oats") throw scheduleError("E_SCHEDULE_INVALID", "argv: oats-only argument list starting with \"oats\"", { field: "argv" });
@@ -468,16 +468,31 @@ export function validateWorkspaceSchedule(dep, a) {
468
468
 
469
469
  /** The soul a spawn job launches, under the deployment's one agents root
470
470
  * (a definition's agentsRoot, when given, must be that root). `repo` is the
471
- * work repository and never selects a soul. */
471
+ * work repository and never selects a soul. Every spawn job names its soul as
472
+ * `oats spawn <soul>` does: the spawn resolves it through discovery (a member or
473
+ * package soul), whether or not this deployment has spawned it before; the
474
+ * agents/<soul>/soul copy is only spawn's per-commit cache. A local job still
475
+ * passes --agents-root (spawn checks it is its root). */
472
476
  export function resolveScheduledAgent(ws, def) {
473
477
  const [root] = scopeRoots(ws);
474
- // A workspace schedule (0.29.0) names its soul as `oats spawn <soul>` does: discovery resolves
475
- // it (a member or package soul), whether or not this deployment has spawned it before.
476
478
  if (def.workspace) return { root, agent: { name: def.agent }, discover: true };
477
479
  if (def.agentsRoot && resolve(def.agentsRoot) !== root) throw scheduleError("E_SCHEDULE_INVALID", `agentsRoot: ${def.agentsRoot} is not this deployment's agents root (${root})`, { field: "agentsRoot" });
478
- const agent = findAgent(root, def.agent);
479
- if (!agent) throw scheduleError("E_SCHEDULE_INVALID", `agent: no soul named ${JSON.stringify(def.agent)} under ${root}`, { field: "agent" });
480
- return { root, agent };
480
+ return { root, agent: { name: def.agent } };
481
+ }
482
+ /** The save-time check of a local spawn job's soul (`add`, `update`): refuse what `oats spawn`
483
+ * would refuse. A soul already under the agents root is accepted without a child, so offline
484
+ * adds and stale cached souls stay accepted; any other name goes through spawn's own preview,
485
+ * with the job's selectors (a selector the run needs, such as its repo, would otherwise fail
486
+ * the preview's checks). */
487
+ function confirmScheduledSoul(ws, def, io) {
488
+ const { root, discover } = resolveScheduledAgent(ws, def);
489
+ if (findAgent(root, def.agent)) return;
490
+ try { spawnPreview(ws, def, { root, discover }, io); }
491
+ catch (e) {
492
+ if (e.unconfirmed) throw scheduleError("E_SCHEDULE_INVALID", `agent: soul ${JSON.stringify(def.agent)} could not be confirmed: ${e.message}`, { field: "agent" });
493
+ if (e.refusal) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${e.message}`, { field: "agent", details: { code: e.code } });
494
+ throw e;
495
+ }
481
496
  }
482
497
 
483
498
  // ----------------------------------------------------------------- time
@@ -556,6 +571,37 @@ export function workspaceSpawnContext(ws) {
556
571
  try { const found = loadLocal(ws); return { kind: "local", local: found.path, dir: dirname(found.path) }; }
557
572
  catch (e) { return { kind: "local", local: null, dir: ws, error: { code: e.code || "E_WORKSPACE_SCHEMA", message: e.message } }; }
558
573
  }
574
+ /** The `oats spawn` selectors a spawn job's run passes (beside its purpose, task and launch
575
+ * flags), so a preview checks what the run will: one builder for the run and its previews.
576
+ * Every value travels as ONE `--flag=value` token. */
577
+ function spawnSelectorArgs(opts) {
578
+ const argv = [];
579
+ if (opts.launchConfig) argv.push(`--launch-config=${opts.launchConfig}`);
580
+ if (opts.harness) argv.push(`--harness=${opts.harness}`);
581
+ if (opts.model) argv.push(`--model=${opts.model}`);
582
+ if (opts.backend) argv.push(`--backend=${opts.backend}`);
583
+ if (opts.repo) argv.push(`--repo=${opts.repo}`);
584
+ return argv;
585
+ }
586
+ /** The kernel's own `oats spawn <agent> --preview --json` in the deployment, with the job's
587
+ * selectors (spawnSelectorArgs): what the run's spawn would resolve and refuse, written nowhere.
588
+ * Answers the preview's result; throws spawn's refusal (its code and message, `refusal: true`),
589
+ * an unconfirmed answer (`unconfirmed: true`: interrupted, timed out, no envelope), or the
590
+ * deployment's own error. */
591
+ function spawnPreview(ws, def, { root, discover }, io) {
592
+ const context = workspaceSpawnContext(ws);
593
+ if (context.error) throw scheduleError(context.error.code, context.error.message);
594
+ if (String(def.agent).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(def.agent)} is not a soul name`, { field: "agent" });
595
+ const argv = ["spawn", def.agent, `--dir=${context.dir}`, ...(discover ? [] : [`--agents-root=${root}`]), "--preview", "--json", ...spawnSelectorArgs(def)];
596
+ const r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, maxBuffer: 16 * 1024 * 1024, env: childEnv() });
597
+ const unconfirmed = (message) => scheduleError("E_SPAWN_FAILED", message, { unconfirmed: true });
598
+ if (r.interrupted === true) throw unconfirmed("the spawn preview was interrupted; its result is unconfirmed");
599
+ if (r.error?.code === "ETIMEDOUT" || (r.status === null && ["SIGTERM", "SIGKILL"].includes(r.signal))) throw unconfirmed("the spawn preview timed out; its result is unconfirmed");
600
+ const envelope = parseEnvelopeText(r.stdout);
601
+ if (!envelope || typeof envelope.ok !== "boolean") throw unconfirmed(`the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);
602
+ if (!envelope.ok) throw scheduleError(envelope.error?.code || "E_SPAWN_FAILED", String(envelope.error?.message || "spawn preview failed"), { refusal: true });
603
+ return envelope.result;
604
+ }
559
605
  /** A workspace spawn materializes EXACTLY like `oats spawn` — prepareInstance →
560
606
  * ensureWorkspaceSoul → spawnInstanceAsync (resolve over the remotes, copy every
561
607
  * module whole into the home, compose AGENTS.md from the modules' injects).
@@ -572,12 +618,7 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
572
618
  // Every value travels as ONE `--flag=value` token, so no value can be read as a flag of its own;
573
619
  // the soul is the one positional, and an option-shaped one is refused.
574
620
  if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
575
- const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json"];
576
- if (opts.launchConfig) argv.push(`--launch-config=${opts.launchConfig}`);
577
- if (opts.harness) argv.push(`--harness=${opts.harness}`);
578
- if (opts.model) argv.push(`--model=${opts.model}`);
579
- if (opts.backend) argv.push(`--backend=${opts.backend}`);
580
- if (opts.repo) argv.push(`--repo=${opts.repo}`);
621
+ const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json", ...spawnSelectorArgs(opts)];
581
622
  if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
582
623
  if (opts.launch === false) argv.push("--no-launch");
583
624
  // The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
@@ -1089,6 +1130,7 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
1089
1130
  });
1090
1131
  if (homes.length === 1) adopted = { instance: `${def.agent}-${purpose}`, home: homes[0] };
1091
1132
  else if (homes.length > 1) ambiguous = `${homes.length} homes named ${def.agent}-${purpose}: ${homes.join(", ")}`;
1133
+ else if (!clear && !runNameProven(ws, def)) return { schedule: describeHere(), reconciled: "unknown", remedy: `spawn names the runs of soul ${def.agent} after its own stem, not ${def.agent}-${purpose}, so the spawn's effects cannot be proven from its name; check the roster and the host by hand, then run oats schedule reconcile ${id} --clear to record launch-failed and free the slot, or oats schedule remove --force ${id}` };
1092
1134
  } else if (attemptKind === "command" || attemptKind === "operation") {
1093
1135
  const named = namedHomes(ws, js);
1094
1136
  if (named.length === 1) adopted = named[0];
@@ -1111,6 +1153,16 @@ export function reconcile(ws, qid, { io, now = new Date(), clear = false, ctx =
1111
1153
  });
1112
1154
  }
1113
1155
 
1156
+ /** Whether a spawn job's runs are named `<agent>-<purpose>`, so a home's absence proves a lost
1157
+ * receipt launched nothing: only for a bare name of a member soul under the agents root, whose
1158
+ * agent name is that name. Spawn names a run after the soul's stem (core.mjs
1159
+ * deriveInstanceName): a qualified name is resolved by spawn, and a package soul homes at
1160
+ * <package>--<soul>, its runs named <package>-<soul>-<purpose>. */
1161
+ function runNameProven(ws, def) {
1162
+ if (typeof def.agent !== "string" || def.agent.includes("/") || def.agent.includes("--")) return false;
1163
+ const [root] = scopeRoots(ws);
1164
+ return findAgent(root, def.agent)?.name === def.agent;
1165
+ }
1114
1166
  /** The homes in the scope of the instance a command attempt's answer named: its only adoptable
1115
1167
  * receipt. Exactly one is adoptable; none or several leave its effects unproven. */
1116
1168
  function namedHomes(ws, js) {
@@ -1235,18 +1287,7 @@ export function testSchedule(ws, qid, io, { now = new Date(), ctx = null } = {})
1235
1287
  soul = { name: def.agent, origin: row.soul?.origin ?? null, resolves: false, error: null };
1236
1288
  try {
1237
1289
  const { root, discover } = resolveScheduledAgent(ws, def);
1238
- const context = workspaceSpawnContext(ws);
1239
- if (context.error) throw scheduleError(context.error.code, context.error.message);
1240
- if (String(def.agent).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(def.agent)} is not a soul name`, { field: "agent" });
1241
- const argv = ["spawn", def.agent, `--dir=${context.dir}`, ...(discover ? [] : [`--agents-root=${root}`]), "--preview", "--json"];
1242
- if (def.launchConfig) argv.push(`--launch-config=${def.launchConfig}`);
1243
- if (def.harness) argv.push(`--harness=${def.harness}`);
1244
- if (def.model) argv.push(`--model=${def.model}`);
1245
- const r = runScheduleCommand(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, graceMs: io?.commandGraceMs, maxBuffer: 16 * 1024 * 1024, env: childEnv() });
1246
- if (r.interrupted === true) throw scheduleError("E_SPAWN_FAILED", "the spawn preview was interrupted; its result is unconfirmed");
1247
- const envelope = parseEnvelopeText(r.stdout);
1248
- if (!envelope || typeof envelope.ok !== "boolean") throw scheduleError("E_SPAWN_FAILED", `the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);
1249
- if (!envelope.ok) throw scheduleError(envelope.error?.code || "E_SPAWN_FAILED", String(envelope.error?.message || "spawn preview failed"));
1290
+ spawnPreview(ws, def, { root, discover }, io);
1250
1291
  soul.resolves = true;
1251
1292
  } catch (e) {
1252
1293
  soul.error = { code: e.code || "E_SPAWN_FAILED", message: e.message };
@@ -1352,7 +1393,7 @@ export function listSchedules(ws, io, { now = new Date(), ctx = null } = {}) {
1352
1393
  return { scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, integrity: scheduleIntegrity(ws), host: { name: ctx?.host?.name ?? null, ghUser: ctx?.ghUsers ? ctx.ghUsers() : {} }, schedules: [...local, ...workspace], triggers: { count: triggers, command: "oats trigger list" }, snapshot: ctx?.snapshot ? { takenAt: ctx.snapshot.takenAt, problems: (ctx.snapshot.problems || []).length } : null, scheduler: schedulerStatus(ws, io) };
1353
1394
  }
1354
1395
  export function addSchedule(ws, spec, io) {
1355
- const def = validateDefinition(ws, spec);
1396
+ const def = validateDefinition(ws, spec, { io });
1356
1397
  return withScopeLock(ws, () => {
1357
1398
  const defs = readDefinitions(ws);
1358
1399
  if (defs.jobs[def.id]) throw scheduleError("E_SCHEDULE_EXISTS", `schedule ${def.id} already exists in ${ws}`);
@@ -1368,7 +1409,7 @@ export function addSchedule(ws, spec, io) {
1368
1409
  * while the job holds a slot or has an unresolved attempt; timing and text can. */
1369
1410
  export function updateSchedule(ws, qid, spec, io) {
1370
1411
  const id = localScheduleId(qid, "update");
1371
- const def = validateDefinition(ws, { ...spec, id });
1412
+ const def = validateDefinition(ws, { ...spec, id }, { io });
1372
1413
  return withHostLock(() => withScopeLock(ws, () => {
1373
1414
  const defs = readDefinitions(ws);
1374
1415
  if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
@@ -18,6 +18,38 @@ export const livenessWord = (i) => i.running === true ? "RUNNING" : i.running ==
18
18
  /** A row's word: a retire under way wins over its liveness. */
19
19
  export const statusWord = (i) => i.retirePending ? "RETIRING" : livenessWord(i);
20
20
 
21
+ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
22
+
23
+ /** Plain status's claim line, or null unless running. The clock defaults to the CLI machine's
24
+ * timezone; explicit `now` and `timeZone` keep calendar-boundary tests independent of the host.
25
+ * Elapsed words match the client's waitedText without a dependency on packages/client. */
26
+ export function waitingLine(i, { now = Date.now(), timeZone } = {}) {
27
+ if (i.running !== true || !i.waitingOnYou) return null;
28
+ const claim = i.waitingOnYou, since = Date.parse(claim.since);
29
+ let timing = "";
30
+ if (Number.isFinite(since)) {
31
+ const clock = new Intl.DateTimeFormat("en-US", {
32
+ timeZone, year: "numeric", month: "2-digit", day: "numeric",
33
+ hour: "2-digit", minute: "2-digit", hourCycle: "h23",
34
+ });
35
+ const parts = (at) => Object.fromEntries(clock.formatToParts(at).map(p => [p.type, p.value]));
36
+ const at = parts(since), today = parts(now);
37
+ const time = `${at.hour}:${at.minute}`;
38
+ let start = time;
39
+ if (at.year !== today.year) {
40
+ start = `${at.year.padStart(4, "0")}-${at.month}-${at.day.padStart(2, "0")} ${time}`;
41
+ } else if (at.month !== today.month || at.day !== today.day) start = `${MONTHS[Number(at.month) - 1]} ${at.day} ${time}`;
42
+ timing = ` since ${start}`;
43
+ const ms = now - since;
44
+ if (ms >= 0) {
45
+ const min = Math.floor(ms / 60000), h = Math.floor(min / 60);
46
+ const elapsed = min < 1 ? "under a minute" : min < 60 ? `${min} min` : h < 24 ? `${h} h` : `${Math.floor(h / 24)} d`;
47
+ timing += `, ${elapsed}`;
48
+ }
49
+ }
50
+ return `! needs input (${claim.reason ?? "unknown"})${timing}${claim.message ? `: ${claim.message}` : ""}`;
51
+ }
52
+
21
53
  /** The one line under a LOST row that says how to bring it back, or null for any other row. Local:
22
54
  * the resume by hand, or the next sweep. `host` (a `--server` or roster row): both refuse `--server`
23
55
  * (E_BAD_ARGS), so the line says to run them on that host. */
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.32.1",
11
+ "ref": "v1.34.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "oats.engineering": {
30
30
  "url": "https://github.com/awebai/oats-engineering.git",
31
- "ref": "v1.17.2",
31
+ "ref": "v1.18.0",
32
32
  "path": "oats-package"
33
33
  },
34
34
  "oats.cloning": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.18.0",
51
+ "ref": "oats-framework/v1.20.0",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.8",
3
+ "version": "0.69.10",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -0,0 +1,25 @@
1
+ // docs/release-notes/v0.40.0.md: oats.framework 1.6.0 carries oats.core 2.4.0,
2
+ // the first Claude needs-input hooks. Compare the home's recorded version, never the lock.
3
+ const NEEDS_INPUT_FRAMEWORK_MIN = Object.freeze([1, 6, 0]);
4
+
5
+ /** The recorded framework version when Claude dialogs cannot be reported as needs input, else null.
6
+ * Both local and remote rows carry drift rows, or a recorded map when the workspace
7
+ * wasn't read. Missing evidence says nothing about reporting coverage. */
8
+ export function needsInputReportingGap(row) {
9
+ if (row?.harness !== 'claude') return null;
10
+ const modules = row.modules;
11
+ const core = Array.isArray(modules) ? modules.find(m => m?.name === 'oats.core')
12
+ : modules && typeof modules === 'object' && Object.hasOwn(modules, 'oats.core') ? modules['oats.core'] : null;
13
+ const from = core?.from;
14
+ if (from?.kind !== 'package' || from.package !== 'oats.framework' || typeof from.version !== 'string') return null;
15
+ // Semver: core numbers and numeric prerelease identifiers have no leading zeros;
16
+ // build identifiers do.
17
+ const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(from.version);
18
+ if (!match || match[4]?.split('.').some(id => /^\d+$/.test(id) && id.length > 1 && id[0] === '0')) return null;
19
+ for (let i = 0; i < NEEDS_INPUT_FRAMEWORK_MIN.length; i++) {
20
+ const number = Number(match[i + 1]), minimum = NEEDS_INPUT_FRAMEWORK_MIN[i];
21
+ if (number !== minimum) return number < minimum ? from.version : null;
22
+ }
23
+ // A prerelease of the first supporting release still sorts below it.
24
+ return match[4] ? from.version : null;
25
+ }