@awebai/oats 0.42.0 → 0.43.0

package/lib/triggers.mjs

@@ -30,7 +30,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 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 { MODEL_RE, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf, validateDescription } from "./automations.mjs";
 import { lockedPackageRef } from "./packages.mjs";
 
 export const TRIGGER_API = 1;
@@ -91,11 +91,13 @@ function checkTemplate(text, field) {
  *  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"], "");
+  onlyKeys(def, ["id", "enabled", "kind", "description", "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");
   if (def.kind !== "trigger") throw invalid("kind", "must be \"trigger\"");
   const enabled = def.enabled === undefined ? true : def.enabled;
   if (typeof enabled !== "boolean") throw invalid("enabled", "boolean");
+  // A label for people (list, show, the Desktop), never templated or read by a poll or a spawn.
+  if (def.description !== undefined) validateDescription(def.description, "E_TRIGGER_INVALID");
   const on = def.on;
   if (!isObject(on)) throw invalid("on", "{ source, repo, events, labels?, base?, poll? }");
   onlyKeys(on, ["source", "repo", "events", "labels", "base", "poll"], "on.");
@@ -133,7 +135,7 @@ export function validateTrigger(def, { backendSource = "the trigger's spawn.back
   for (const [k, v] of [["max", max], ["perKey", perKey]]) if (!Number.isInteger(v) || v < 1 || v > 100) throw invalid(`concurrency.${k}`, "a whole number from 1 to 100");
   if (def.template !== undefined && !isObject(def.template)) throw invalid("template", "the package template this trigger was made from");
   return {
-    id: def.id, enabled, kind: "trigger",
+    id: def.id, enabled, kind: "trigger", ...(def.description !== undefined ? { description: def.description } : {}),
     on: { source: on.source, repo: repo.key, events: [...on.events], labels: [...labels], ...(on.base !== undefined ? { base: on.base.trim() } : {}), poll },
     spawn: { soul: sp.soul, purpose, task: sp.task, teams: [...teams], ...(sp.launchConfig ? { launchConfig: sp.launchConfig } : {}), ...(sp.harness ? { harness: sp.harness } : {}), ...(sp.model ? { model: sp.model } : {}), ...(sp.yolo !== undefined ? { yolo: sp.yolo } : {}), ...(sp.backend ? { backend: sp.backend } : {}) },
     concurrency: { max, perKey },
@@ -601,6 +603,23 @@ export function setTriggerEnabled(ws, id, enabled, ctx = null) {
     return describeTrigger(ws, e.id, ctx);
   });
 }
+/** Change only a LOCAL trigger's description (`oats trigger update <id> --description=<text>`):
+ *  `""` or null removes it. Its fired and pending state is untouched; a workspace trigger is
+ *  changed in Git. */
+export function updateTriggerDescription(ws, id, description, ctx = null) {
+  const e = requireTrigger(ws, id, ctx);
+  refuseWorkspace(e, "change");
+  const clear = description === "" || description === null || description === undefined;
+  if (!clear) validateDescription(description, "E_TRIGGER_INVALID");
+  return withScopeLock(ws, () => {
+    const defs = readDefinitions(ws);
+    if (defs.jobs[e.name]?.kind !== "trigger") throw triggerError("E_TRIGGER_UNKNOWN", `no trigger ${JSON.stringify(id)} in ${ws}`, { details: { id: e.id } });
+    const { description: _d, ...rest } = defs.jobs[e.name]; void _d;
+    defs.jobs[e.name] = { ...rest, ...(clear ? {} : { description }), updatedAt: new Date().toISOString() };
+    writeDefinitions(ws, defs);
+    return describeTrigger(ws, e.id, ctx);
+  });
+}
 /** Remove the definition and its state. Live instances it spawned are untouched. */
 export function removeTrigger(ws, id, ctx = null) {
   const e = requireTrigger(ws, id, ctx);

package/package.json

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