@awebai/oats 0.22.14 → 0.22.17

package/lib/schedule.mjs

@@ -40,11 +40,12 @@ export function scheduleError(code, message, extra) { return Object.assign(new E
  *  is never observed or executed, and is reported invalid on that job only. */
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
-  if (!["spawn", "command", "wake"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command or wake`;
+  if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
   if (typeof def.cron !== "string" || typeof def.tz !== "string") return "cron and tz must be strings";
   if (def.kind === "spawn" && typeof def.agent !== "string") return "agent must be a string";
   if (def.kind === "command" && (typeof def.cwd !== "string" || !Array.isArray(def.argv))) return "cwd and argv are required";
   if (def.kind === "wake" && (typeof def.home !== "string" || typeof def.message !== "string")) return "home and message are required";
+  if (def.kind === "operation" && (typeof def.operation !== "string" || typeof def.home !== "string")) return "operation and home are required";
   return null;
 }
 
@@ -229,7 +230,14 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
     if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
     validateMessage(def.message, "message");
     out.home = resolve(def.home); out.message = def.message;
-  } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command or wake", { field: "kind" });
+  } else if (def.kind === "operation") {
+    // A provider operation in a running home, resolved when the job runs
+    // (oats operation run <layer>:<name> --home): the provider is whatever
+    // fills that layer for the home then; nothing about it is stored here.
+    if (typeof def.operation !== "string" || !/^(knowledge|messaging|tasks):[a-z][a-z0-9-]*$/.test(def.operation)) throw scheduleError("E_SCHEDULE_INVALID", "operation: <layer>:<name>, e.g. knowledge:harvest", { field: "operation" });
+    if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
+    out.operation = def.operation; out.home = resolve(def.home);
+  } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command, wake or operation", { field: "kind" });
   return out;
 }
 
@@ -320,6 +328,13 @@ function launchSpawn(ws, def, minute, io) {
   }
   return run;
 }
+/** The command job an operation job becomes when it runs: the kernel's own
+ *  operation runner in the home, which resolves the provider at that moment
+ *  and reports a launch receipt (instance/home) only for what the provider
+ *  launched, never for the source home. */
+export function operationAsCommand(def) {
+  return { ...def, kind: "command", cwd: def.home, argv: ["oats", "operation", "run", def.operation, "--home", def.home] };
+}
 /** Parse a command's stdout as one JSON document (remote output can be
  *  multi-line); fall back to the last {...} block; null when nothing parses. */
 export function parseEnvelopeText(text) {
@@ -355,9 +370,16 @@ function launchCommand(ws, def, io) {
   if (instance && !home) { const found = findHomesInScope(ws, instance); if (found.length === 1) home = found[0]; }
   if (envelope.ok && instance && !home) return { kind: "command", launched: true, instance, unconfirmed: true, error: `the envelope names instance ${instance} but no home for it is in this scope's roster; run oats schedule reconcile once it appears` };
   // A valid ok:false answer that reports an incomplete rollback (a harvest
-  // spawn whose compensation could not stop or remove everything) is not a
-  // confirmed failure either.
-  if (!envelope.ok && reportsRetainedEffects(envelope.error?.message)) return { kind: "command", launched: false, unconfirmed: true, ...(instance ? { instance } : {}), error: `command failed with retained effects: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+  // spawn whose compensation could not stop or remove everything), or an
+  // operation runner's unconfirmed outcome (timeout, no valid receipt, a
+  // receipt contradicted by the exit status), is not a confirmed failure.
+  // Whatever name the provider managed to answer travels in error.details
+  // so reconcile can adopt it.
+  if (!envelope.ok && (UNCONFIRMED_ERROR_CODES.has(envelope.error?.code) || envelope.error?.details?.unconfirmed === true || reportsRetainedEffects(envelope.error?.message))) {
+    const partial = envelope.error?.details?.envelope?.result;
+    const named = instance || (partial && typeof partial.instance === "string" ? partial.instance : undefined);
+    return { kind: "command", launched: false, unconfirmed: true, ...(named ? { instance: named } : {}), error: `command outcome unconfirmed: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+  }
   return { kind: "command", launched: envelope.ok === true, ...(instance ? { instance } : {}), ...(home ? { home } : {}), ...(envelope.ok ? {} : { error: envelope.error?.message || "command failed", errorCode: envelope.error?.code }) };
 }
 /** One wake. `startIfStopped` false between due minutes (a harness that
@@ -367,6 +389,8 @@ function launchCommand(ws, def, io) {
  *  confirm (spawn compensation's "rollback INCOMPLETE", a quarantined or
  *  retained home): the launch's effects are unconfirmed, never a confirmed
  *  failure. Shared by caught spawn errors and ok:false command envelopes. */
+/** Error codes whose meaning is "the effects are unconfirmed" by contract. */
+const UNCONFIRMED_ERROR_CODES = new Set(["E_OPERATION_TIMEOUT", "E_OPERATION_RESULT"]);
 export function reportsRetainedEffects(message) { return /INCOMPLETE|quarantin|retain|could not (?:be )?(?:verif|confirm)/i.test(String(message || "")); }
 function performWake(def, io, { startIfStopped = true, canStart = true, reserve } = {}) {
   const seen = observeHome(def.home, io);
@@ -498,7 +522,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     js.lastLaunchedAt = now.toISOString();
     writeState(ws, st);
     let run;
-    try { run = def.kind === "command" ? launchCommand(ws, def, io) : launchSpawn(ws, def, minute, io); }
+    try { run = def.kind === "spawn" ? launchSpawn(ws, def, minute, io) : launchCommand(ws, def.kind === "operation" ? operationAsCommand(def) : def, io); }
     catch (e) {
       // spawnInstance compensates its own failures, but its rollback can be
       // INCOMPLETE (a pane it could not stop, a quarantined home it kept):
@@ -595,7 +619,7 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
       const homes = findHomesInScope(ws, `${def.agent}-${purpose}`);
       if (homes.length === 1) adopted = { instance: `${def.agent}-${purpose}`, home: homes[0] };
       else if (homes.length > 1) ambiguous = `${homes.length} homes named ${def.agent}-${purpose}: ${homes.join(", ")}`;
-    } else if (def.kind === "command") {
+    } else if (def.kind === "command" || def.kind === "operation") {
       const named = js.lastRun?.instance ? findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home })) : [];
       if (named.length === 1) adopted = named[0];
       else if (named.length > 1) ambiguous = `${named.length} homes named ${js.lastRun.instance}: ${named.map((c) => c.home).join(", ")}`;
@@ -651,7 +675,7 @@ export function updateSchedule(ws, id, spec, io) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
-    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv]);
+    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
     if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its kind, agent, agentsRoot, repo, purpose, home, cwd and argv cannot change until it ends (cron, tz, task, message, runtime, model and enabled can)`);
     defs.jobs[id] = { ...def, createdAt: defs.jobs[id].createdAt, updatedAt: new Date().toISOString() };

package/lib/servers.mjs

@@ -232,6 +232,7 @@ export function checkRemote(target, io = {}) {
     launchOptions: list("launchOptions", []),
     remote: list("remote", []),
     features: list("features", []),
+    operationsApi: probe.operationsApi === 1 ? 1 : null,
     advertised: Array.isArray(probe.runtimes),
   };
 }
@@ -479,7 +480,34 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     const { envelope, stderr } = runRemote(target, json(withScope(["status", ...oatsArgs])), io);
     return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
   }
-  throw serverError("E_USAGE", `--server routes spawn, retire, status, session and okf harvest only (not ${cmd})`);
+  if (OPERATIONS_COMMANDS.has(cmd)) {
+    // The operations contract (inspect, operation run, use, soul set): the
+    // remote must advertise it before anything is sent. An explicit --dir is
+    // the exact member context the caller chose and travels as is; without
+    // one, a --home selection is left to the host (the home is its own
+    // context) and anything else runs in the registered workspace.
+    // An exact remote home (or a saved instance name) resolves through its
+    // FROZEN route exactly as session attach does: the snapshot's target,
+    // and a home/name disagreement is refused; the registration's target is
+    // used only for scope requests, which get its workspace as --dir.
+    let args = [...oatsArgs];
+    const valueOf = (name) => { const i = args.indexOf(name); return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
+    let route;
+    if (valueOf("--home") !== undefined || valueOf("--instance") !== undefined) {
+      route = resolveRoute(serverId, { instance: valueOf("--instance"), home: valueOf("--home") }, cmd);
+      target = route.target;
+      const ii = args.indexOf("--instance");
+      if (ii >= 0) { args.splice(ii, 2); if (valueOf("--home") === undefined) args.push("--home", route.home); }
+    }
+    const remote = checkRemote(target, io);
+    if (!Array.isArray(remote.features) || !remote.features.includes("operations") || remote.operationsApi !== 1) {
+      throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the operations contract (kernels from ${OPERATIONS_REMOTE_VERSION} do); upgrade it there; nothing was sent`);
+    }
+    const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
+    const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
+    return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
+  }
+  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, use and soul only (not ${cmd})`);
 }
 
 // ------------------------------------------------------------------- roster
@@ -621,6 +649,9 @@ export function inspectRemote(serverId, { instance, home } = {}, io = {}) {
 /** The kernel version whose probe first advertises the `session-start`
  *  feature; the probe's features list is the actual check. */
 export const SESSION_START_REMOTE_VERSION = "0.22.9";
+/** The kernel version whose probe first advertises the operations contract. */
+export const OPERATIONS_REMOTE_VERSION = "0.22.16";
+const OPERATIONS_COMMANDS = new Set(["inspect", "operation", "use", "soul"]);
 
 /** `session start` on the execution host for a remote instance: the same
  *  route resolution as inspect, refused before any mutation when the remote

package/package-catalog.json

@@ -2,7 +2,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.5.2",
+      "ref": "v1.6.1",
       "path": "oats-package"
     },
     "oats.aweb": {
@@ -33,12 +33,33 @@
   },
   "capabilities": {
     "oats.review": "oats.dev",
-    "oas.okf": { "package": "oats.okf", "capability": "oats.okf" },
-    "oas.aweb": { "package": "oats.aweb", "capability": "oats.aweb" },
-    "oas.jira": { "package": "oats.jira", "capability": "oats.jira" },
-    "oas.linear": { "package": "oats.linear", "capability": "oats.linear" },
-    "oas.authoring": { "package": "oats.authoring", "capability": "oats.authoring" },
-    "oas.dev": { "package": "oats.dev", "capability": "oats.dev" },
-    "oas.review": { "package": "oats.dev", "capability": "oats.review" }
+    "oas.okf": {
+      "package": "oats.okf",
+      "capability": "oats.okf"
+    },
+    "oas.aweb": {
+      "package": "oats.aweb",
+      "capability": "oats.aweb"
+    },
+    "oas.jira": {
+      "package": "oats.jira",
+      "capability": "oats.jira"
+    },
+    "oas.linear": {
+      "package": "oats.linear",
+      "capability": "oats.linear"
+    },
+    "oas.authoring": {
+      "package": "oats.authoring",
+      "capability": "oats.authoring"
+    },
+    "oas.dev": {
+      "package": "oats.dev",
+      "capability": "oats.dev"
+    },
+    "oas.review": {
+      "package": "oats.dev",
+      "capability": "oats.review"
+    }
   }
 }

package/package.json

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