@awebai/oats 0.30.3 → 0.31.0

package/lib/triggers.mjs

@@ -28,7 +28,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry } from "./schedule.mjs";
+import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath } from "./schedule.mjs";
+import { herdrSettingRemoved } from "./errors.mjs";
 import { MODEL_RE, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf } from "./automations.mjs";
 import { lockedPackageRef } from "./packages.mjs";
 
@@ -43,7 +44,6 @@ const SOUL_RE = /^(?:[a-z0-9][a-z0-9._-]*\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const HARNESSES = new Set(["pi", "claude", "codex"]);
 /** A launch configuration name (oats-local.yaml launch-configs, docs/oats-local.schema.json). */
 const LAUNCH_CONFIG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-const BACKENDS = new Set(["tmux", "herdr"]);
 const DEFAULT_POLL = "2m";
 const POLL_MIN_MS = 60_000;
 /** A tick runs once a minute and takes a moment: a poll due within this much is taken now. */
@@ -87,8 +87,9 @@ function checkTemplate(text, field) {
   if (bad.length) throw invalid(field, `the template may name only ${TEMPLATE_FIELDS.map((f) => `{${f}}`).join(" ")} (a PR's title and body are never templated); found ${bad.map((f) => `{${f}}`).join(" ")}`);
 }
 
-/** Validate and normalize one trigger definition. */
-export function validateTrigger(def) {
+/** Validate and normalize one trigger definition. `backendSource` names the file and key that set its
+ *  spawn.backend, for the refusal of `herdr` (Herdr was removed in 0.31.0). */
+export function validateTrigger(def, { backendSource = "the trigger's spawn.backend" } = {}) {
   if (!isObject(def)) throw invalid("definition", "must be an object");
   onlyKeys(def, ["id", "enabled", "kind", "on", "spawn", "concurrency", "template", "createdAt", "updatedAt"], "");
   if (typeof def.id !== "string" || !ID_RE.test(def.id)) throw invalid("id", "lowercase letters, digits and dashes, 1 to 40 characters");
@@ -123,7 +124,8 @@ export function validateTrigger(def) {
   if (sp.harness !== undefined && !HARNESSES.has(sp.harness)) throw invalid("spawn.harness", "pi, claude or codex");
   if (sp.model !== undefined && (typeof sp.model !== "string" || !MODEL_RE.test(sp.model))) throw invalid("spawn.model", "a model id: a letter or digit, then letters, digits and . _ : / @ + - [ ] (at most 128 characters)");
   if (sp.yolo !== undefined && typeof sp.yolo !== "boolean") throw invalid("spawn.yolo", "boolean");
-  if (sp.backend !== undefined && !BACKENDS.has(sp.backend)) throw invalid("spawn.backend", "tmux or herdr");
+  if (sp.backend === "herdr") throw Object.assign(herdrSettingRemoved(`${backendSource}: herdr`), { field: "spawn.backend", details: { field: "spawn.backend" } });
+  if (sp.backend !== undefined && sp.backend !== "tmux") throw invalid("spawn.backend", "tmux");
   const cc = def.concurrency === undefined ? {} : def.concurrency;
   if (!isObject(cc)) throw invalid("concurrency", "{ max?, perKey? }");
   onlyKeys(cc, ["max", "perKey"], "concurrency.");
@@ -207,7 +209,7 @@ export function triggerKind({ lock = null, remote = null } = {}) {
     parseBody: parseTriggerBody,
     expand: async (a) => {
       const raw = a.source.from ? await packageTriggerTemplate(lock, a.source.from, a.source.set, { id: a.name, remote }) : { ...a.source.definition };
-      const def = validateTrigger({ ...raw, id: a.name, kind: "trigger", enabled: true });
+      const def = validateTrigger({ ...raw, id: a.name, kind: "trigger", enabled: true }, { backendSource: `${a.source.from ? `package template ${a.source.from}` : a.origin?.path ?? a.name} sets spawn.backend` });
       // The owner check asks gh on the OWNER's host, and the poll runs on the REPO's host: they must be
       // one GitHub host, or polling would act as whoever is logged in there (re-review B #7).
       const owner = parseOwner(a.owner), repo = parseRepo(def.on.repo);
@@ -239,7 +241,7 @@ export function triggerEntries(ws, ctx) {
   const out = [];
   for (const [id, raw] of Object.entries(triggerJobs(ws)).sort(([a], [b]) => a.localeCompare(b))) {
     let def = null, bad = null;
-    try { def = validateTrigger(raw); } catch (e) { bad = { code: e.code, message: e.message, ...(e.field ? { field: e.field } : {}) }; }
+    try { def = validateTrigger(raw, { backendSource: `${definitionsPath(ws)} sets jobs.${id}.spawn.backend` }); } catch (e) { bad = { code: e.code, message: e.message, ...(e.field ? { field: e.field } : {}) }; }
     out.push({ ...localEntry("trigger", def ?? { ...raw, id }, { invalid: bad, dep: ws }), raw });
   }
   out.push(...(ctx?.triggers || []));
@@ -577,7 +579,7 @@ export function listTriggers(ws, ctx = null, { io } = {}) {
   };
 }
 export function addTrigger(ws, spec) {
-  const def = validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" });
+  const def = validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" }, { backendSource: `${definitionsPath(ws)} sets jobs.${spec?.id}.spawn.backend` });
   return withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (defs.jobs[def.id]) throw triggerError("E_TRIGGER_EXISTS", `${defs.jobs[def.id].kind === "trigger" ? "trigger" : "a schedule"} ${def.id} already exists in ${ws}`, { details: { id: def.id } });

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.17.1",
+      "ref": "v1.17.3",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.30.3",
+  "version": "0.31.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/lib/herdr.mjs

@@ -1,143 +0,0 @@
-/** Herdr 0.8.x/0.9.x host-local backend (explicit protocols 20/22).
- * SSH belongs to the CLI router. A new session records the server's protocol once; a recorded
- * target is never renegotiated. */
-import { execFileSync, spawn } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-
-// The legacy protocol literal; a new session records the protocol its server reports (ensureHerdr).
-export const HERDR_PROTOCOL = 20;
-export const HERDR_SUPPORTED_PROTOCOLS = Object.freeze([20, 22]);
-export const isSupportedHerdrProtocol = (value) => HERDR_SUPPORTED_PROTOCOLS.includes(value);
-function selectedHerdrProtocol(target) {
-  if (!isSupportedHerdrProtocol(target?.protocol)) throw new Error("Herdr endpoint requires explicit supported protocol 20 or 22");
-  return target.protocol;
-}
-const quote = (s) => `'${String(s).replaceAll("'", "'\\''")}'`;
-const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-
-export function herdrSocket(session = "oats") {
-  if (!/^[a-zA-Z0-9_-]+$/.test(session)) throw new Error("invalid Herdr session name");
-  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "herdr", "sessions", session, "herdr.sock");
-}
-
-/** One Herdr CLI call on the target's socket, its stdout as text. */
-function herdrOutput(target, args, { timeout = 10000, exec = execFileSync } = {}) {
-  const env = { ...process.env, HERDR_SOCKET_PATH: target.socket };
-  delete env.HERDR_SESSION;
-  return exec(target.binary || "herdr", args, { env, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
-}
-
-export function herdrCommand(target, args, io) {
-  const output = herdrOutput(target, args, io);
-  // Some successful terminal mutations have no output; reads below require
-  // their documented result shape independently.
-  if (!output.trim()) return {};
-  const response = JSON.parse(output);
-  if (response.error) throw Object.assign(new Error(response.error.message), { code: response.error.code });
-  if (!response.result) throw new Error("Herdr returned no result");
-  return response.result;
-}
-
-export function herdrSnapshot(target, io) {
-  const protocol = selectedHerdrProtocol(target);
-  const snapshot = herdrCommand(target, ["api", "snapshot"], io).snapshot;
-  if (snapshot?.protocol !== protocol) throw new Error(`Herdr snapshot does not match selected protocol ${protocol}`);
-  if (!Array.isArray(snapshot.panes)) throw new Error("Herdr snapshot has no pane inventory");
-  return snapshot;
-}
-
-/** The target for a NEW session on the server at `socket`: it records the supported protocol that server
- * reports (Herdr 0.8 speaks 20, 0.9 speaks 22). Every later call checks the snapshot against that recorded
- * protocol, so a recorded target is never renegotiated. */
-function newSessionTarget(target, io) {
-  const protocol = herdrCommand(target, ["api", "snapshot"], io).snapshot?.protocol;
-  if (!isSupportedHerdrProtocol(protocol)) throw Object.assign(new Error(`Herdr server speaks protocol ${protocol ?? "unknown"}; OATS supports ${HERDR_SUPPORTED_PROTOCOLS.join(" and ")}`), { unsupportedProtocol: true });
-  const selected = { ...target, protocol };
-  herdrSnapshot(selected, io);
-  return selected;
-}
-
-export function ensureHerdr({ binary = "herdr", socket, session = "oats", io } = {}) {
-  const target = { backend: "herdr", binary, socket: resolve(socket || herdrSocket(session)) };
-  try { return newSessionTarget(target, io); }
-  catch (e) {
-    // An explicit socket belongs to an operator-managed server. Never start a
-    // different server when it cannot be inspected or is incompatible.
-    if (socket || existsSync(target.socket)) throw e;
-  }
-  mkdirSync(dirname(target.socket), { recursive: true });
-  const env = { ...process.env };
-  delete env.HERDR_SESSION; delete env.HERDR_SOCKET_PATH;
-  const child = spawn(binary, ["--session", session, "server"], { detached: true, stdio: "ignore", env });
-  child.on("error", () => {});
-  child.unref();
-  let error;
-  for (let i = 0; i < 30; i++) {
-    pause(100);
-    // A server that answers with an unsupported protocol is up: waiting longer cannot change its answer.
-    try { return newSessionTarget(target, io); } catch (e) { if (e.unsupportedProtocol) throw e; error = e; }
-  }
-  throw new Error(`Herdr did not start: ${error?.message || "no socket"}`);
-}
-
-export function allocateHerdr(target, { home, instance }, io) {
-  const protocol = selectedHerdrProtocol(target);
-  const result = herdrCommand(target, ["workspace", "create", "--cwd", home, "--label", instance, "--no-focus"], io);
-  const pane = result.root_pane;
-  if (!pane?.pane_id || !pane?.terminal_id || !pane?.workspace_id) throw new Error("Herdr allocation returned no session identity");
-  return { ...target, protocol, workspaceId: pane.workspace_id, paneId: pane.pane_id, terminalId: pane.terminal_id };
-}
-
-export function inspectHerdr(target, io) {
-  const snapshot = herdrSnapshot(target, io);
-  const matches = snapshot.panes.filter((p) => p.pane_id === target.paneId && p.terminal_id === target.terminalId);
-  if (io?.strictHerdrTarget && (matches.length > 1 || (matches.length === 1 && matches[0].workspace_id !== target.workspaceId))) throw new Error("Herdr target workspace/pane/terminal identity is ambiguous or changed");
-  const pane = matches[0];
-  const agent = pane && snapshot.agents?.find((a) => a.terminal_id === target.terminalId);
-  return { present: !!pane, pane, agent, status: agent?.agent_status || "unknown" };
-}
-
-/** Wait until a new pane's shell has drawn something (its prompt) before typing into it. Text typed
- * earlier sits in the terminal's canonical line buffer, which drops a line past 1024 bytes on macOS:
- * a launch command is longer than that, and arrived cut. Bounded; a Herdr that cannot read a pane
- * leaves the old behaviour (type at once). */
-function awaitShellReady(target, io) {
-  const deadline = Date.now() + (io?.shellReadyMs ?? 10000);
-  for (;;) {
-    let text;
-    // `pane read` answers the screen as plain text, not a JSON envelope.
-    const remaining = Math.max(100, deadline - Date.now());
-    try { text = herdrOutput(target, ["pane", "read", target.paneId, "--source", "visible"], { ...io, timeout: Math.min(2000, remaining) }); }
-    catch { return; }
-    if (typeof text === "string" && text.trim()) return;
-    if (Date.now() >= deadline) return;
-    pause(100);
-  }
-}
-
-export function launchHerdr(target, command, io) {
-  if (!inspectHerdr(target, io).present) throw new Error("Herdr launch pane disappeared");
-  awaitShellReady(target, io);
-  // This is the allocated shell's one launch command. Exec avoids a fallback
-  // shell that could accidentally consume a subsequent agent notification.
-  herdrCommand(target, ["pane", "run", target.paneId, `exec /bin/sh -c ${quote(command)}`], io);
-}
-
-export function stopHerdr(target, io) {
-  if (!inspectHerdr(target, io).present) return;
-  try { herdrCommand(target, ["pane", "close", target.paneId], io); } catch { /* inspect the effect even if the pane exited concurrently */ }
-  if (inspectHerdr(target, io).present) throw new Error(`Herdr pane ${target.paneId} is still present`);
-}
-
-export function inputHerdr(target, text, io) {
-  if (!inspectHerdr(target, io).present) throw new Error("Herdr session stopped or was replaced");
-  herdrCommand(target, ["pane", "run", target.paneId, text], io);
-}
-
-export function validHerdrTarget(value) {
-  return value?.backend === "herdr" && isSupportedHerdrProtocol(value.protocol)
-    && [value.socket, value.binary, value.workspaceId, value.paneId, value.terminalId].every((v) => typeof v === "string" && v.length > 0)
-    && value.socket === resolve(value.socket);
-}