@awebai/oats 0.30.2 → 0.31.0

package/lib/errors.mjs

@@ -5,3 +5,20 @@ export function oatsError(code, message, provenance) {
   if (provenance) e.provenance = provenance;
   return e;
 }
+
+/** Herdr was removed in 0.31.0: every place that meets it refuses with E_HERDR_REMOVED, this stem
+ *  and what to do. */
+export const HERDR_REMOVED = "Herdr is no longer supported by OATS (removed in 0.31.0); tmux is the only session backend.";
+/** A flag or configuration value that selects Herdr: `what` names the flag (`--backend herdr was
+ *  given`), or the file and key (`<file> sets spawn.backend: herdr`). */
+export function herdrSettingRemoved(what) {
+  return oatsError("E_HERDR_REMOVED", `${HERDR_REMOVED} ${what}. Remove it (or use tmux).`);
+}
+/** A session operation on an instance OATS opened in Herdr. */
+export function herdrInstanceRemoved(name) {
+  return oatsError("E_HERDR_REMOVED", `${HERDR_REMOVED} ${name} was opened in Herdr. Retire it (\`oats retire ${name}\`) and spawn a new instance; it opens in tmux.`);
+}
+/** Retiring an instance OATS opened in Herdr while processes still work in its home. */
+export function herdrInstanceBusy(name, pids) {
+  return oatsError("E_HERDR_REMOVED", `${HERDR_REMOVED} ${name} was opened in Herdr. A process still works in this home (pid ${pids.join(", ")}); stop its Herdr pane (for example \`herdr --session oats server stop\`), then retire.`);
+}

package/lib/instance-inspect.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { capabilityManifests, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
+import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
 import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility } from "./resolve.mjs";
@@ -127,7 +127,7 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
   try { launchCurrent = launchReportFor({ layers: homeLaunchLayers(realHome, meta), launchConfigs: launchConfigsAt(deployment), contextDir: deployment }); }
   catch { launchCurrent = null; }
   return {
-    kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent,
+    kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent, session: newSessionDefaults(deployment),
     recordedDefaultTeam: recordedTeams(meta).defaultTeam, teamModel: model, teamKey,
     subject: { kind: "instance", instance: meta.instance, home, soul: meta.agent },
     soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
@@ -183,7 +183,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   try { launchConfigs = launchConfigsAt(deployment); } catch { launchConfigs = {}; }
   const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: teamKey, local: found.local }), launchConfigs, contextDir: deployment });
   return {
-    kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch,
+    kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
     soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
       soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}) },
@@ -195,6 +195,12 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   };
 }
 
+/** The tmux session a NEW tmux spawn here would open in ({tmuxSession}, 0.31); null when the
+ *  deployment's oats-local.yaml cannot be read. */
+function newSessionDefaults(deployment) {
+  try { return sessionDefaults(deployment); } catch { return null; }
+}
+
 /** Is `dir` a v2 context (an oats-local.yaml in reach)? Only a MISSING file means
  *  "not a workspace"; an unreadable or invalid one is the caller's error to report,
  *  never a silent fallback to the classic chain. */
@@ -256,6 +262,8 @@ export function inspectDocument(t, { kernel }) {
     // Feature launch-preference: a soul's launch here; a home's recorded launch and launchCurrent.
     launch: t.launch ?? null,
     ...(t.home ? { launchCurrent: t.launchCurrent ?? null } : {}),
+    // What a new tmux spawn here would open in: {tmuxSession} (0.31).
+    session: t.session ?? null,
     knowledge: kcap ? { provider: kcap.id, version: kcap.version, operations: kcap.operations.map((o) => ({ name: o.name, kind: o.kind, available: o.available, reason: o.reason })) } : { provider: null, version: null, operations: [] },
     instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null, launched: !!m.launched, createdAt: m.createdAt || null,
       resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,

package/lib/schedule.mjs

@@ -29,6 +29,7 @@ import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
 import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
+import { herdrSettingRemoved } from "./errors.mjs";
 import { tickTriggers } from "./triggers.mjs";
 import { resolveMemberClone } from "./instance-resolution.mjs";
 import { AUTOMATION_ID_RE, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
@@ -38,7 +39,6 @@ export const SCHEDULE_FILE = "oats-schedules.json";
 export const SCHEDULE_API = 2;
 const ID_RE = /^[a-z0-9-]{1,40}$/;
 const HARNESSES = new Set(["pi", "claude", "codex"]);
-const BACKENDS = new Set(["tmux", "herdr"]);
 const MESSAGE_MAX = 256 * 1024;
 const OATS_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "oats.mjs");
 const COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
@@ -295,8 +295,17 @@ function validateMessage(message, field) {
   if (typeof message !== "string" || !message.trim() || message.includes("\0") || Buffer.byteLength(message) > MESSAGE_MAX) throw scheduleError("E_SCHEDULE_INVALID", `${field}: non-empty text without NUL, at most 256 KiB`, { field });
 }
 
-/** Validate and normalize one definition against its scope. */
-export function validateDefinition(ws, def, { checkAgent = true } = {}) {
+/** The refusal of a spawn job's `backend: herdr` (Herdr was removed in 0.31.0): `where` names the
+ *  file and key that set it. */
+export function herdrBackendRefusal(where) { return Object.assign(herdrSettingRemoved(`${where}: herdr`), { field: "backend" }); }
+/** A stored local spawn job that selects Herdr: its refusal, naming this scope's definitions file. */
+function storedHerdrBackend(ws, id, def) {
+  return def?.kind === "spawn" && !def.workspace && def.backend === "herdr" ? herdrBackendRefusal(`${definitionsPath(ws)} sets jobs.${id}.backend`) : null;
+}
+
+/** Validate and normalize one definition against its scope. `backendSource` names the file and key
+ *  a definition read from elsewhere sets its backend in (default: this scope's definitions file). */
+export function validateDefinition(ws, def, { checkAgent = true, backendSource } = {}) {
   if (!def || typeof def !== "object" || Array.isArray(def)) throw scheduleError("E_SCHEDULE_INVALID", "definition must be an object", { field: "definition" });
   if (def.kind === "trigger") throw scheduleError("E_SCHEDULE_INVALID", "kind: a trigger is added with `oats trigger add`, not `oats schedule add`", { field: "kind" });
   const id = def.id;
@@ -314,7 +323,8 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
       out.agentsRoot = resolve(def.agentsRoot);
     }
     if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim() || def.repo.startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
-    if (def.backend !== undefined) { if (!BACKENDS.has(def.backend)) throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux or herdr", { field: "backend" }); out.backend = def.backend; }
+    if (def.backend === "herdr") throw herdrBackendRefusal(backendSource ?? `${definitionsPath(ws)} sets jobs.${id}.backend`);
+    if (def.backend !== undefined) { if (def.backend !== "tmux") throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux", { field: "backend" }); out.backend = def.backend; }
     if (def.purpose !== undefined) { if (typeof def.purpose !== "string" || !/^[a-z0-9-]{1,40}$/.test(def.purpose)) throw scheduleError("E_SCHEDULE_INVALID", "purpose: lowercase letters, digits and dashes", { field: "purpose" }); out.purpose = def.purpose; }
     // A run spawns <agent>-<purpose|id>-<YYYYMMDDHHMM>; instance names are at most
     // MAX_INSTANCE_NAME characters, so refuse here what would fail at every firing.
@@ -413,7 +423,7 @@ export function validateWorkspaceSchedule(dep, a) {
     const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
     if (!inside(real(dep), real(spec.cwd))) throw scheduleError("E_SCHEDULE_INVALID", `cwd: ${JSON.stringify(d.cwd)} leaves the deployment; a workspace command's cwd is a directory inside it`, { field: "cwd" });
   }
-  const out = validateDefinition(dep, spec, { checkAgent: false });
+  const out = validateDefinition(dep, spec, { checkAgent: false, backendSource: `${a.origin?.path ?? a.name} sets backend` });
   delete out.enabled;
   return out;
 }
@@ -756,11 +766,13 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     const def = defs.jobs[id];
     const js = stateOf(id);
     let due, cronError;
-    const shape = shapeError(def);
+    const invalidShape = shapeError(def), herdr = invalidShape ? null : storedHerdrBackend(ws, id, def);
+    const shape = invalidShape ?? herdr?.message;
     if (!shape) validateActiveExecution(js, jobLockInfo(ws, id)); // Also covers host pre-observed candidates.
     if (shape) { cronError = shape; due = false; }
     else { try { due = only ? true : dueAt(def, minute); } catch (e) { cronError = e.message; due = false; } }
-    if (cronError) { if (!dryRun) js.lastRun = { ...(js.lastRun || {}), outcome: "invalid", error: `definition cannot be evaluated: ${cronError}` }; record(id, "invalid", { error: cronError }); continue; }
+    const errorCode = herdr ? { errorCode: herdr.code } : {};
+    if (cronError) { if (!dryRun) js.lastRun = { ...(js.lastRun || {}), outcome: "invalid", error: `definition cannot be evaluated: ${cronError}`, ...errorCode }; record(id, "invalid", { error: cronError, ...errorCode }); continue; }
     if (def.kind === "wake" && js.pendingWake && def.enabled && !dryRun && !only) {
       const dueNow = due && js.lastAttemptedMinute !== key;
       const held = !!jobLockInfo(ws, id);
@@ -1066,7 +1078,8 @@ export function describe(ws, qid, io, { defs, st, now = new Date(), ctx = null }
   const { history, recentRuns } = projectHistory(js);
   const { workspace: _w, ...stored } = def; void _w;
   const base = { ...stored, id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun ? { ...js.lastRun, runId: runIdOf(js.lastRun), session: sessionProvenanceOf(js.lastRun) } : null, history, recentRuns, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
-  return scheduleRow(ws, entry ?? localEntry("schedule", { ...def, id: name }, { dep: ws }), base, ctx);
+  const herdr = entry ? null : storedHerdrBackend(ws, id, def);
+  return scheduleRow(ws, entry ?? localEntry("schedule", { ...def, id: name }, { dep: ws, ...(herdr ? { invalid: { code: herdr.code, message: herdr.message, field: herdr.field } } : {}) }), base, ctx);
 }
 /** A schedule's list row: its stored facts, the fields every trigger and schedule row share
  *  (lib/automations.mjs baseRow) and the schedule's own: `kind` is its run (spawn, command, wake,