@meffecta/agent 1.0.15 → 1.0.16

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.15",
-  "builtFrom": "6b2db5d04d06db2612112659dd526e6f23a3e8c3"
+  "engineTag": "1.0.16",
+  "builtFrom": "95496c7dce1df80834700c5db4696c39f4b3a804"
 }

package/lib/doctor.js

@@ -76,12 +76,62 @@ export function readLocalJobs(dir) {
       cron: meta.cron,
       webhook: meta.webhook,
       inbox: meta.inbox,
+      systems: meta.systems,
       disabled: meta.disabled === "true",
     });
   }
   return jobs;
 }
 
+/**
+ * The deployment's register, parsed the way src/systems.ts parses it — one entry per
+ * `systems/<name>.md`, keyed by filename, with the variables from `requires` and
+ * `selectors`. The two parsers have to agree, because this is what tells an operator that a
+ * job's `systems:` names something real before a run finds out the hard way.
+ */
+export function readLocalSystems(dir) {
+  if (!existsSync(dir)) {
+    return undefined;
+  }
+  const list = (value) =>
+    (value ?? "")
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean);
+  // Leading token of each comma-separated segment, and only when it is shaped like an
+  // environment variable: `requires: none — domain-wide delegation, keyless on Cloud Run`
+  // is a real entry, and must contribute nothing.
+  const vars = (value) =>
+    list(value)
+      .map((segment) => segment.match(/^([A-Z][A-Z0-9_]*)(?=$|[\s(])/)?.[1])
+      .filter(Boolean);
+  const entries = [];
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md")) {
+    const match = readFileSync(`${dir}/${file}`, "utf8").match(/^---\n([\s\S]*?)\n---\n/);
+    const meta = {};
+    for (const line of (match?.[1] ?? "").split("\n")) {
+      const at = line.indexOf(": ");
+      if (at > 0) {
+        meta[line.slice(0, at).trim()] = line.slice(at + 2).trim();
+      }
+    }
+    entries.push({
+      name: file.slice(0, -3),
+      groups: list(meta.group),
+      variables: [...new Set([...vars(meta.requires), ...vars(meta.selectors)])],
+    });
+  }
+  return entries;
+}
+
+/**
+ * Variables the engine declares itself and hands to every run whatever its scope. A stale
+ * entry here costs a spurious line in one report; it can never strip a variable from a run,
+ * because the engine derives its own copy from the schema in src/env.ts.
+ */
+const ENGINE_OWN =
+  /^(PORT|NODE_ENV|TIMEZONE|TIMEOUT_MS|MAX_CONCURRENT_RUNS|MEMORY_DIR|AUDIT_BUCKET|GIT_|GITHUB_TOKEN|AGENT_|ANTHROPIC_|CLAUDE_|CONTEXT_DEPLOYMENTS_)/;
+
 export function expectedSweepSchedule(pollSeconds) {
   // Unset means the engine's own default; 0 must clamp to one minute rather than fall
   // back to it, which is what sync-triggers.sh does and what doctor has to agree with.
@@ -201,21 +251,7 @@ export async function doctor() {
       .filter(Boolean)
       .map((n) => n.split("/").pop()),
   );
-  // AGENT_WEBHOOK_SECRET is the old name for AGENT_API_SECRET and the engine still reads
-  // it, so a deployment on the old one is working, not broken — check the pair, not the
-  // preferred name, or doctor fails a healthy service.
-  const apiSecretName = env.AGENT_API_SECRET
-    ? "AGENT_API_SECRET"
-    : env.AGENT_WEBHOOK_SECRET
-      ? "AGENT_WEBHOOK_SECRET"
-      : "AGENT_API_SECRET";
-  if (apiSecretName === "AGENT_WEBHOOK_SECRET") {
-    r.warn(
-      "AGENT_WEBHOOK_SECRET is the old name",
-      "It guards the whole API, not just webhooks, and is now AGENT_API_SECRET. The engine reads both.",
-      "meffecta-agent set-secret AGENT_API_SECRET   (paste the same value, deploy, then delete the old one)",
-    );
-  }
+  const apiSecretName = "AGENT_API_SECRET";
   // Either variable pays for runs, and the API key wins when both are set. Naming the one
   // in effect matters more than naming a missing variable: a deployment that switched to a
   // Console key and left the old token behind is still billing the key, not the subscription.
@@ -295,6 +331,56 @@ export async function doctor() {
       } else {
         r.ok("Content repo", `${local.length} job(s) on disk, all registered`);
       }
+
+      // --- what each job may reach ------------------------------------------------
+      const register = readLocalSystems(`${process.cwd()}/systems`);
+      if (register) {
+        const names = new Set(register.map((e) => e.name));
+        const groups = new Set(register.flatMap((e) => e.groups));
+        const clashing = [...groups].filter((g) => names.has(g));
+        if (clashing.length) {
+          r.fail(
+            "A group is named the same as a system",
+            `${clashing.join(", ")} — a job naming one resolves to neither, and the engine refuses to boot on it.`,
+            "Rename the group, or the systems/ file it collides with",
+          );
+        }
+        const scoped = local.filter((j) => j.systems && j.systems !== "*");
+        const broken = scoped
+          .map((j) => ({
+            job: j.name,
+            unknown: j.systems
+              .split(",")
+              .map((n) => n.trim())
+              .filter((n) => n && !names.has(n) && !groups.has(n)),
+          }))
+          .filter((x) => x.unknown.length);
+        if (broken.length) {
+          r.fail(
+            "A job is scoped to systems that do not exist",
+            broken.map((x) => `${x.job}: ${x.unknown.join(", ")}`).join("; ") +
+              ". Those names grant nothing, so the job runs without those credentials and reports every system unavailable.",
+            "Fix the name in the job's systems: line, or add the systems/ entry",
+          );
+        } else if (scoped.length) {
+          r.ok("Job scopes", `${scoped.length} of ${local.length} job(s) scoped, all naming systems that exist`);
+        }
+
+        // The register is what a scoped job can be granted, so a credential no entry
+        // declares is one no scoped job can ever reach. Harmless while nothing is scoped,
+        // which is exactly why it is worth saying before something is.
+        const declared = new Set(register.flatMap((e) => e.variables));
+        const undeclared = Object.keys(env)
+          .filter((name) => !ENGINE_OWN.test(name) && !declared.has(name))
+          .sort();
+        if (undeclared.length && scoped.length) {
+          r.warn(
+            `${undeclared.length} credential(s) no system declares`,
+            `${undeclared.join(", ")} — no scoped job can be granted these, because nothing in systems/ says which system they belong to.`,
+            "Add a systems/<name>.md entry naming each in its requires: or selectors: line",
+          );
+        }
+      }
     }
 
     const scheduler = capture(

package/lib/gcloud.js

@@ -96,23 +96,19 @@ export function serviceUrl(deployment) {
 /**
  * The deployment's API secret, straight from Secret Manager into memory. It is never
  * printed, never passed as a process argument, and only ever leaves here as a header.
- *
- * AGENT_WEBHOOK_SECRET is the old name — it guarded webhooks once, then everything else —
- * and the engine still reads it, so this tries both rather than telling a deployment that
- * works fine that its secret is missing.
  */
 export function apiSecret(deployment) {
-  for (const name of ["AGENT_API_SECRET", "AGENT_WEBHOOK_SECRET"]) {
-    try {
-      return capture("gcloud", gcloudArgs(deployment, ["secrets", "versions", "access", "latest", `--secret=${name}`]));
-    } catch {
-      // Try the other name before deciding there is no secret at all.
-    }
+  try {
+    return capture(
+      "gcloud",
+      gcloudArgs(deployment, ["secrets", "versions", "access", "latest", "--secret=AGENT_API_SECRET"]),
+    );
+  } catch {
+    throw new UserError(
+      "Could not read AGENT_API_SECRET from Secret Manager.\n" +
+        "Create it first: meffecta-agent set-secret AGENT_API_SECRET --random",
+    );
   }
-  throw new UserError(
-    "Could not read AGENT_API_SECRET from Secret Manager (nor the old AGENT_WEBHOOK_SECRET).\n" +
-      "Create it first: meffecta-agent set-secret AGENT_API_SECRET --random",
-  );
 }
 
 /** An authenticated request to the deployment's own API. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meffecta/agent",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {

package/scripts/sync-triggers.sh

@@ -120,20 +120,15 @@ fi
 
 # The triggers authenticate with the same bearer token as everything else on this API, so
 # the secret has to be resolved — it is normally a Secret Manager reference on the service.
-# AGENT_WEBHOOK_SECRET is the old name, still read by the engine and still looked for here,
-# so a deployment part-way through the rename gets working triggers either way.
 API_SECRET=""
-for SECRET_VAR in AGENT_API_SECRET AGENT_WEBHOOK_SECRET; do
-  IFS=$'\t' read -r SECRET_KIND SECRET_A SECRET_B <<<"$(printf '%s' "${SERVICE_JSON}" | svc_field "${SECRET_VAR}")"
-  if [ "${SECRET_KIND}" = "value" ]; then
-    API_SECRET="${SECRET_A}"
-  elif [ "${SECRET_KIND}" = "secret" ] && [ -n "${SECRET_A}" ]; then
-    API_SECRET=$(${GC} secrets versions access "${SECRET_B}" --secret="${SECRET_A}")
-  fi
-  [ -n "${API_SECRET}" ] && break
-done
+IFS=$'\t' read -r SECRET_KIND SECRET_A SECRET_B <<<"$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_API_SECRET)"
+if [ "${SECRET_KIND}" = "value" ]; then
+  API_SECRET="${SECRET_A}"
+elif [ "${SECRET_KIND}" = "secret" ] && [ -n "${SECRET_A}" ]; then
+  API_SECRET=$(${GC} secrets versions access "${SECRET_B}" --secret="${SECRET_A}")
+fi
 if [ -z "${API_SECRET}" ]; then
-  echo "Could not resolve AGENT_API_SECRET (or the old AGENT_WEBHOOK_SECRET) from ${SERVICE}." >&2
+  echo "Could not resolve AGENT_API_SECRET from ${SERVICE}." >&2
   echo "  $(cmd set-secret) AGENT_API_SECRET --random" >&2
   echo "Refusing to create triggers that would 401 on every firing." >&2
   exit 1

package/scripts/verify-credentials.mjs

@@ -666,11 +666,10 @@ function checkPresence() {
   } else {
     skip("Claude credential", "neither ANTHROPIC_API_KEY nor CLAUDE_CODE_OAUTH_TOKEN is set");
   }
-  // Either name satisfies the engine; say which one is actually in play.
   if (env.AGENT_API_SECRET) {
     ok("AGENT_API_SECRET", "present (not remotely testable)");
-  } else if (env.AGENT_WEBHOOK_SECRET) {
-    ok("AGENT_API_SECRET", "present under the old name AGENT_WEBHOOK_SECRET");
+  } else if (env.AGENT_SPAWN_TOKEN) {
+    ok("AGENT_API_SECRET", "withheld from runs by design — a run holds only its own spawn token");
   } else {
     skip("AGENT_API_SECRET", "unset");
   }