@meffecta/agent 1.0.14 → 1.0.16

package/deployment.env.example

@@ -52,5 +52,5 @@ REGION=europe-west1
 # SCALING=scale-to-zero
 # CPU=2
 # MEMORY=4Gi
-# MAX_INSTANCES=1        # >1 breaks the serial run queue — raise only with reason
+# MAX_INSTANCES=1        # the run pool is per process — >1 breaks it, so raise only with reason
 # REQUEST_TIMEOUT=3600   # seconds one held request may last; the ceiling on a single run

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.14",
-  "builtFrom": "788fc7fd22968bd3e14bf4c19e850b2c13c7eb8c"
+  "engineTag": "1.0.16",
+  "builtFrom": "95496c7dce1df80834700c5db4696c39f4b3a804"
 }

package/lib/commands.js

@@ -730,7 +730,7 @@ export const GROUPS = [
         "Provision GCP: registry, buckets, service account, run queue, service shell",
         script("setup-infrastructure.sh"),
       ],
-      ["set-secret", "AGENT_API_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN", script("set-secret.sh")],
+      ["set-secret", "AGENT_API_SECRET --random, ANTHROPIC_API_KEY, GITHUB_TOKEN", script("set-secret.sh")],
       ["set-env", "GIT_REPO_URL — the one setting the service will not boot without", script("set-env.sh")],
       ["deploy", "Roll out an engine image and assert the runtime shape", script("deploy.sh")],
       [

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,22 +251,30 @@ 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.
+  const claudeAuth = env.ANTHROPIC_API_KEY ? "ANTHROPIC_API_KEY" : "CLAUDE_CODE_OAUTH_TOKEN";
+  if (!env.ANTHROPIC_API_KEY && !env.CLAUDE_CODE_OAUTH_TOKEN) {
+    r.fail(
+      "No way to pay for runs",
+      "The engine needs ANTHROPIC_API_KEY (a Claude Console key — what a product or service should use) or CLAUDE_CODE_OAUTH_TOKEN (billed to a personal subscription).",
+      "meffecta-agent set-secret ANTHROPIC_API_KEY",
     );
+  } else {
+    r.ok("Claude credential", `runs bill to ${claudeAuth}`);
+    if (env.ANTHROPIC_API_KEY && env.CLAUDE_CODE_OAUTH_TOKEN) {
+      r.warn(
+        "Both Claude credentials are set",
+        "ANTHROPIC_API_KEY outranks CLAUDE_CODE_OAUTH_TOKEN, so the subscription token is unused.",
+        // Both are secret-backed, so --remove-env-vars (what `set-env --unset` does) will not
+        // touch them. Removing one is --remove-secrets, which the CLI has no command for.
+        `Drop whichever you did not mean to bill: gcloud run services update ${d.SERVICE} --region=${d.REGION} --remove-secrets CLAUDE_CODE_OAUTH_TOKEN`,
+      );
+    }
   }
-  for (const name of [apiSecretName, "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN"]) {
+  for (const name of [apiSecretName, claudeAuth, "GITHUB_TOKEN"]) {
     const ref = env[name]?.valueFrom?.secretKeyRef?.name;
     if (!env[name]) {
       r.fail(`${name} not set`, "Required by the engine.", `meffecta-agent set-secret ${name}`);
@@ -273,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.14",
+  "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/create-project.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Step 1 of IMPLEMENTATION.md: create the GCP project this deployment will live in.
+# Step 1 of the set-up (https://agent.meffecta.com/install): create the GCP project this
+# deployment will live in.
 #
 # Give the agent a project of its own, separate from any product project it will read:
 # its service account gets project-wide secret access, and the mail tokens stored here

package/scripts/deploy.sh

@@ -32,9 +32,9 @@ set -euo pipefail
 # and is left alone.
 #
 # Usage:
-#   scripts/deploy.sh                     # the newest published engine (--tag latest)
-#   scripts/deploy.sh --tag sha-556ca72   # a specific build, e.g. to roll back
-#   scripts/deploy.sh --image europe-west1-docker.pkg.dev/PROJECT/REPO/agent:sha-556ca72
+#   scripts/deploy.sh                     # the newest release (--tag latest)
+#   scripts/deploy.sh --tag 1.0.13        # a specific version, e.g. to roll back
+#   scripts/deploy.sh --image europe-west1-docker.pkg.dev/PROJECT/REPO/agent:1.0.13
 #   scripts/deploy.sh --dry-run           # print the target, image and shape; change nothing
 #   scripts/deploy.sh --no-scheduler      # roll out without re-syncing the triggers
 #

package/scripts/link-billing.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Step 2 of IMPLEMENTATION.md: link a billing account to the project.
+# Step 2 of the set-up (https://agent.meffecta.com/install): link a billing account.
 #
 # Nothing else works without this — provisioning starts by enabling APIs, which fails on
 # an unbilled project, and the failure does not mention billing.

package/scripts/setup-infrastructure.sh

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 # One-time GCP provisioning for a deployment of the agent. Idempotent — safe to re-run.
-# See IMPLEMENTATION.md for the whole set-up, of which this is step 6.
+# See https://agent.meffecta.com/install for the whole set-up, of which this is step 5.
 #
 # Give the agent a GCP project of its OWN, separate from any product project it reads:
 # this project's service account holds project-wide secret access, and the mail refresh
@@ -325,7 +325,8 @@ echo "   Next, from this directory:"
 echo ""
 echo "     $(cmd set-env) GIT_REPO_URL=https://github.com/<owner>/<content-repo>.git"
 echo "     $(cmd set-secret) AGENT_API_SECRET --random"
-echo "     $(cmd set-secret) CLAUDE_CODE_OAUTH_TOKEN     # from: claude setup-token"
+echo "     $(cmd set-secret) ANTHROPIC_API_KEY           # a Claude Console key — for a service"
+echo "         ...or CLAUDE_CODE_OAUTH_TOKEN            # from: claude setup-token — individual use"
 echo "     $(cmd set-secret) GITHUB_TOKEN                # must be able to clone the repo above"
 echo "     $(cmd deploy)                              # rolls out the engine, then creates its triggers"
 if has_cli; then

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/update-tooling.sh

@@ -23,7 +23,7 @@ set -euo pipefail
 # That is this script's job, done by hand once. Afterwards:
 #
 #   scripts/update-tooling.sh                  # match the newest published engine
-#   scripts/update-tooling.sh --tag sha-558a144  # match a specific one, e.g. what you run
+#   scripts/update-tooling.sh --tag 1.0.13     # match a specific one, e.g. what you run
 #   scripts/update-tooling.sh --dry-run        # show what would change, touch nothing
 #
 # Needs docker, and is the only thing here that does: the files are lifted out of the

package/scripts/verify-credentials.mjs

@@ -619,7 +619,13 @@ async function checkDeploymentsContext() {
  * These are also the ones a shipped script CAN test properly, because they are the
  * engine's own and mean the same thing in every deployment.
  */
-const ESSENTIAL = new Set(["AGENT_API_SECRET", "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN", "GIT_REPO_URL"]);
+const ESSENTIAL = new Set([
+  "AGENT_API_SECRET",
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "GITHUB_TOKEN",
+  "GIT_REPO_URL",
+]);
 
 /**
  * Inside a run, three of the four are proven by the fact that this output exists at all —
@@ -645,18 +651,25 @@ function checkPresence() {
   // started it, which is exactly right, and means "unset" here would be a lie: the run
   // doing the reporting is itself the proof it is set. AGENT_SPAWN_TOKEN is how we know we
   // are inside a run; the engine sets that one, so `claude` has no reason to strip it.
-  if (env.CLAUDE_CODE_OAUTH_TOKEN) {
-    ok("CLAUDE_CODE_OAUTH_TOKEN", "present (not remotely testable)");
+  //
+  // Either variable pays for runs, and the API key wins when both are set — so report which
+  // one is actually in play rather than just that something is.
+  if (env.ANTHROPIC_API_KEY) {
+    ok("ANTHROPIC_API_KEY", "present — runs bill to this Console key (not remotely testable)");
+    if (env.CLAUDE_CODE_OAUTH_TOKEN) {
+      ok("CLAUDE_CODE_OAUTH_TOKEN", "present but unused — the API key outranks it");
+    }
+  } else if (env.CLAUDE_CODE_OAUTH_TOKEN) {
+    ok("CLAUDE_CODE_OAUTH_TOKEN", "present — runs bill to this subscription (not remotely testable)");
   } else if (env.AGENT_SPAWN_TOKEN) {
-    ok("CLAUDE_CODE_OAUTH_TOKEN", "in use by this very run — a run cannot read it, by design");
+    ok("Claude credential", "in use by this very run — a run cannot read it, by design");
   } else {
-    skip("CLAUDE_CODE_OAUTH_TOKEN", "unset");
+    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");
   }