@meffecta/agent 1.0.2 → 1.0.3

package/README.md

@@ -23,7 +23,7 @@ deployment is, so a command can never quietly act on the wrong one.
 npx @meffecta/agent create-project        # a GCP project
 npx @meffecta/agent link-billing          # attach billing
 npx @meffecta/agent setup-infra           # registry, buckets, service account, service
-npx @meffecta/agent set-secret AGENT_WEBHOOK_SECRET --random
+npx @meffecta/agent set-secret AGENT_API_SECRET --random
 npx @meffecta/agent set-env GIT_REPO_URL=https://github.com/you/your-content-repo.git
 npx @meffecta/agent deploy                # roll out the engine
 npx @meffecta/agent setup-scheduler       # give it its triggers

package/bin/meffecta-agent.js

@@ -32,10 +32,10 @@ const STEPS = [
   ],
   [
     "init",
-    "Create your content repo — jobs/, worlds/, SYSTEM.md — and a deployment.env in it.\n    Run everything from there; it is what says which deployment you mean.",
+    "Create your content repo — jobs/, worlds/, SYSTEM.md, ENVIRONMENT.md — and a deployment.env\n    in it. Run everything from there; it is what says which deployment you mean.",
   ],
   ["setup-infra", "Provision GCP and the Cloud Run service shell."],
-  ["set-secret", "AGENT_WEBHOOK_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN."],
+  ["set-secret", "AGENT_API_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN."],
   ["set-env", "GIT_REPO_URL=… — the service will not boot without it."],
   ["deploy", "Roll out the engine image."],
   ["setup-scheduler", "Give it its triggers. Scaled to zero, it fires nothing without them."],

package/deployment.env.example

@@ -10,7 +10,7 @@
 #
 # Then operate from the content repo, running the engine's scripts by path:
 #   cd /path/to/your-content-repo
-#   /path/to/agent/scripts/set-secret.sh AGENT_WEBHOOK_SECRET --random
+#   /path/to/agent/scripts/set-secret.sh AGENT_API_SECRET --random
 #   /path/to/agent/scripts/deploy.sh
 
 # The GCP *project ID* — check it with `gcloud projects list`, as the console may have

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.2",
-  "builtFrom": "6a4ebd7751d2eaeaca8f2f28d699a171d162208b"
+  "engineTag": "1.0.3",
+  "builtFrom": "f784051bc092c57aa37b4e9c44e06ee8f368f8f7"
 }

package/lib/commands.js

@@ -245,7 +245,7 @@ async function envList() {
   );
   const entries = svc.spec.template.spec.containers[0].env ?? [];
   if (entries.length === 0) {
-    console.log("Nothing set. At minimum this service needs GIT_REPO_URL and AGENT_WEBHOOK_SECRET.");
+    console.log("Nothing set. At minimum this service needs GIT_REPO_URL and AGENT_API_SECRET.");
     return 0;
   }
   const width = Math.max(...entries.map((e) => e.name.length));
@@ -281,7 +281,7 @@ async function secretsList() {
   );
   if (secrets.length === 0) {
     console.log("No secrets in this project yet. Start with:");
-    console.log("  meffecta-agent set-secret AGENT_WEBHOOK_SECRET --random");
+    console.log("  meffecta-agent set-secret AGENT_API_SECRET --random");
     return 0;
   }
   const width = Math.max(...secrets.map((name) => name.length));
@@ -364,8 +364,31 @@ async function logs(args) {
 }
 
 /** Start a deployment.env in the current directory, from the template in this package. */
+// Scaffolded by `init` into a new content repo. Deliberately short: an empty table with the
+// columns that matter is a thing an operator fills in, where a long example is a thing they
+// delete.
+const REGISTER_TEMPLATE = `# Deployment environment
+
+The register of systems this agent can reach. The agent reads this file **at run time** —
+its skills are shared across deployments and name no deployment's variables, so a skill
+says what kind of credential it needs and comes here for the name.
+
+A system that is not listed here is one the agent will report as unavailable.
+
+| System | Skill | Variables | Access |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+Fill the Access column honestly — "read-only", "may send mail", "may change DNS". It is
+what a person reads when deciding whether a job is safe to let run unattended.
+
+Set the values themselves with \`meffecta-agent set-secret <NAME>\` (credentials) or
+\`set-env <NAME>=<value>\` (ids, addresses, URLs); \`meffecta-agent connect\` lists the
+systems the engine already has skills for and walks through each.
+`;
+
 async function init(args) {
-  const { copyFileSync, existsSync: exists } = await import("node:fs");
+  const { copyFileSync, existsSync: exists, writeFileSync } = await import("node:fs");
   const target = resolve(process.cwd(), "deployment.env");
   if (exists(target) && !args.includes("--force")) {
     console.log(`deployment.env already exists here. Leaving it alone (--force to replace).`);
@@ -383,6 +406,20 @@ async function init(args) {
   console.log("Fill in PROJECT and SERVICE — those two are never guessed — then commit it.");
   console.log("It belongs in your content repo, beside jobs/, because which GCP project a");
   console.log("set of jobs runs as is a fact about the deployment and none of it is secret.\n");
+
+  // The register is read by the agent itself at run time, not just by people: the skills
+  // are shared across deployments and name no deployment's variables, so without this file
+  // a run knows how a system works and not which variable holds its credential.
+  const register = resolve(process.cwd(), "ENVIRONMENT.md");
+  if (exists(register)) {
+    console.log("ENVIRONMENT.md already exists here. Leaving it alone.\n");
+  } else {
+    writeFileSync(register, REGISTER_TEMPLATE);
+    console.log("✅ Wrote ENVIRONMENT.md here — the register of systems this agent can reach.\n");
+    console.log("Add a row per system as you connect one. The agent reads this file at run");
+    console.log("time to find out which variable holds which credential, so a system that is");
+    console.log("not listed is a system it will report as unavailable.\n");
+  }
   console.log("Next: meffecta-agent steps");
   return 0;
 }
@@ -410,7 +447,7 @@ export const GROUPS = [
         "Provision GCP: registry, buckets, service account, service shell",
         script("setup-infrastructure.sh"),
       ],
-      ["set-secret", "AGENT_WEBHOOK_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN", script("set-secret.sh")],
+      ["set-secret", "AGENT_API_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, 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")],
       ["setup-scheduler", "Create the external triggers — Cloud Scheduler + Cloud Tasks", script("setup-scheduler.sh")],

package/lib/doctor.js

@@ -188,7 +188,22 @@ export async function doctor() {
       .filter(Boolean)
       .map((n) => n.split("/").pop()),
   );
-  for (const name of ["AGENT_WEBHOOK_SECRET", "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN"]) {
+  // 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)",
+    );
+  }
+  for (const name of [apiSecretName, "CLAUDE_CODE_OAUTH_TOKEN", "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}`);

package/lib/gcloud.js

@@ -69,27 +69,31 @@ export function serviceUrl(deployment) {
 }
 
 /**
- * The deployment's webhook secret, straight from Secret Manager into memory. It is never
+ * 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 webhookSecret(deployment) {
-  try {
-    return capture(
-      "gcloud",
-      gcloudArgs(deployment, ["secrets", "versions", "access", "latest", "--secret=AGENT_WEBHOOK_SECRET"]),
-    );
-  } catch {
-    throw new UserError(
-      "Could not read AGENT_WEBHOOK_SECRET from Secret Manager.\n" +
-        "Create it first: meffecta-agent set-secret AGENT_WEBHOOK_SECRET --random",
-    );
+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.
+    }
   }
+  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. */
 export async function api(deployment, path, { method = "GET", body, accept } = {}) {
   const url = `${serviceUrl(deployment)}${path}`;
-  const headers = { Authorization: `Bearer ${webhookSecret(deployment)}` };
+  const headers = { Authorization: `Bearer ${apiSecret(deployment)}` };
   if (accept) {
     headers.Accept = accept;
   }

package/lib/integrations.js

@@ -132,6 +132,57 @@ const INTEGRATIONS = {
     ],
   },
 
+  hubspot: {
+    title: "HubSpot CRM",
+    gives: "query-hubspot — pipelines, contacts, deals, activity. manage-hubspot writes, and only when a job says to",
+    needs: [
+      "A private app in the HubSpot portal: Settings → Integrations → Private Apps → Create.",
+      "Grant only the scopes the jobs need — crm.objects.*.read for reporting; add the",
+      "matching .write scopes only if a job is meant to change records.",
+    ],
+    steps: [["meffecta-agent set-secret HUBSPOT_TOKEN", "the private app's access token"]],
+    more: [
+      "A second portal is HUBSPOT_<NAME>_TOKEN, and the job says which portal it may touch.",
+      "Reading and writing are two skills on purpose: a reporting job loads query-hubspot and",
+      "then cannot alter the CRM at all, because the ability to is not in its context.",
+      "Rotate the token from the same screen; HubSpot can expire the old one after 7 days.",
+    ],
+  },
+
+  kleer: {
+    title: "Kleer accounting and payroll",
+    gives:
+      "query-kleer — invoices out and in, payment status, vouchers, the SIE4E export, payroll runs, bank transactions. Read-only",
+    needs: [
+      "A Kleer API token, requested through your accounting consultant — Kleer issues it by",
+      "SMS, there is no self-service. It inherits the permissions of the Kleer user it is",
+      "bound to, so ask for it on a READ-ONLY user: that, not the skill, is what stops a",
+      "write. (Kleer was PE Accounting before the rebrand; the docs still say PE in places.)",
+    ],
+    steps: [["meffecta-agent set-secret KLEER_API_TOKEN", "the token Kleer sent"]],
+    more: [
+      "Company ids are discovered at run time from the token, so nothing else needs setting.",
+      "There is a test environment on the same token, mirroring production a day behind —",
+      "worth pointing a new job at first, since live books are not a place to explore.",
+    ],
+  },
+
+  mongodb: {
+    title: "A MongoDB database",
+    gives: "query-mongodb — counts, filters and aggregations over a product database. Read-only",
+    needs: [
+      "A MongoDB user with the `read` role on the database and nothing more, and a connection",
+      "URI for it. The role is the real boundary — the skill refuses to write, but a",
+      "read-only user makes a mistake impossible rather than merely forbidden.",
+    ],
+    steps: [["meffecta-agent set-secret ACME_MONGODB_URI_READONLY", "one per database, named for the project"]],
+    more: [
+      "Connection strings are per-database, so there is no single shared variable: name each",
+      "one for its project and record it in the deployment's ENVIRONMENT.md, which is where",
+      "the skill looks for the name. The driver already ships in the engine image.",
+    ],
+  },
+
   cloudflare: {
     title: "Cloudflare",
     gives: "cloudflare — DNS, cache purge, Pages deployments, certificate checks",

package/package.json

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

package/scripts/deploy.sh

@@ -165,5 +165,5 @@ URL=$(gcloud run services describe "${SERVICE}" \
 if [ -n "${URL}" ]; then
   echo "🌍 ${SERVICE} → ${URL}"
   echo "   Liveness: curl -fsS ${URL}/health"
-  echo "   Ask it:   ${URL}/ask   (any username, AGENT_WEBHOOK_SECRET as the password)"
+  echo "   Ask it:   ${URL}/ask   (any username, AGENT_API_SECRET as the password)"
 fi

package/scripts/set-secret.sh

@@ -8,7 +8,7 @@ set -euo pipefail
 # The value never appears in your shell history, in the process list, or on screen.
 #
 # Usage:
-#   scripts/set-secret.sh AGENT_WEBHOOK_SECRET --random   # generate one, 32 random bytes
+#   scripts/set-secret.sh AGENT_API_SECRET --random   # generate one, 32 random bytes
 #   scripts/set-secret.sh GITHUB_TOKEN                    # prompt (hidden), or read stdin
 #   scripts/set-secret.sh GMAIL_REFRESH_TOKEN --from-file token.txt
 #   cat token.txt | scripts/set-secret.sh GMAIL_REFRESH_TOKEN

package/scripts/setup-infrastructure.sh

@@ -233,7 +233,7 @@ echo "   3. Create + wire the secrets:"
 echo "        printf '%s' '<value>' | gcloud secrets create <NAME> --data-file=- --project ${PROJECT}"
 echo "        gcloud run services update ${SERVICE} --region ${REGION} --project ${PROJECT} \\"
 echo "          --update-secrets '<NAME>=<NAME>:latest'"
-echo "      Required: AGENT_WEBHOOK_SECRET, CLAUDE_CODE_OAUTH_TOKEN (claude setup-token), GITHUB_TOKEN"
+echo "      Required: AGENT_API_SECRET, CLAUDE_CODE_OAUTH_TOKEN (claude setup-token), GITHUB_TOKEN"
 echo "      Gmail:    GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN — and one"
 echo "                GMAIL_<NAME>_REFRESH_TOKEN per extra account (e.g. GMAIL_MEVISIO_REFRESH_TOKEN)"
 echo "      Optional: GRAFANA_LOGS_HOST/USERNAME + GRAFANA_API_KEY"

package/scripts/setup-scheduler.sh

@@ -70,8 +70,8 @@ GC="gcloud --project=${PROJECT}"
 # arguments of the calls that create them — and gcloud echoes the arguments back when it
 # rejects one. Everything this script prints goes through here first.
 redact() {
-  if [ -n "${WEBHOOK_SECRET:-}" ]; then
-    printf '%s\n' "${1//${WEBHOOK_SECRET}/<secret>}"
+  if [ -n "${API_SECRET:-}" ]; then
+    printf '%s\n' "${1//${API_SECRET}/<secret>}"
   else
     printf '%s\n' "$1"
   fi
@@ -119,18 +119,24 @@ 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.
-SECRET_REF=$(printf '%s' "${SERVICE_JSON}" | svc_field AGENT_WEBHOOK_SECRET)
-IFS=$'\t' read -r SECRET_KIND SECRET_A SECRET_B <<<"${SECRET_REF}"
-if [ "${SECRET_KIND}" = "value" ]; then
-  WEBHOOK_SECRET="${SECRET_A}"
-elif [ "${SECRET_KIND}" = "secret" ] && [ -n "${SECRET_A}" ]; then
-  WEBHOOK_SECRET=$(${GC} secrets versions access "${SECRET_B}" --secret="${SECRET_A}")
-else
-  echo "Could not resolve AGENT_WEBHOOK_SECRET from ${SERVICE} — is it set on the service?" >&2
-  echo "  scripts/set-secret.sh AGENT_WEBHOOK_SECRET --random" >&2
+# 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
+if [ -z "${API_SECRET}" ]; then
+  echo "Could not resolve AGENT_API_SECRET (or the old AGENT_WEBHOOK_SECRET) from ${SERVICE}." >&2
+  echo "  scripts/set-secret.sh AGENT_API_SECRET --random" >&2
+  echo "Refusing to create triggers that would 401 on every firing." >&2
   exit 1
 fi
-[ -n "${WEBHOOK_SECRET}" ] || { echo "AGENT_WEBHOOK_SECRET resolved empty — refusing to create triggers that would 401." >&2; exit 1; }
 
 echo "   url:     ${AGENT_URL}"
 echo "   runtime: ${RUNTIME_SA}"
@@ -171,7 +177,7 @@ if [ "${CURRENT_QUEUE}" != "${QUEUE_PATH}" ] || [ "${CURRENT_URL}" != "${AGENT_U
 fi
 
 echo "📋 Reading the job list from ${AGENT_URL}/jobs..."
-JOBS_JSON=$(curl -fsS --max-time 300 -H "Authorization: Bearer ${WEBHOOK_SECRET}" "${AGENT_URL}/jobs") || {
+JOBS_JSON=$(curl -fsS --max-time 300 -H "Authorization: Bearer ${API_SECRET}" "${AGENT_URL}/jobs") || {
   cat >&2 <<EOF
 Could not read ${AGENT_URL}/jobs.
 
@@ -193,7 +199,7 @@ EOF
 CRON_JOBS=$(printf '%s' "${JOBS_JSON}" | node "${READ_JSON}" crons)
 WATCHES_INBOX=$(printf '%s' "${JOBS_JSON}" | node "${READ_JSON}" watches-inbox)
 
-HEADERS="Content-Type=application/json,Authorization=Bearer ${WEBHOOK_SECRET}"
+HEADERS="Content-Type=application/json,Authorization=Bearer ${API_SECRET}"
 
 # `create http` takes --headers; `update http` insists on --update-headers for the same
 # thing. Everything else about the two calls is identical.

package/scripts/verify-credentials.mjs

@@ -164,6 +164,48 @@ async function checkSerper() {
   return fail("SERPER_API_KEY", json?.message ? `${json.message} (${status})` : `search → ${status}`);
 }
 
+async function checkHubspot() {
+  const token = env.HUBSPOT_TOKEN;
+  if (!token) {
+    return skip("HUBSPOT_TOKEN", "unset");
+  }
+  // limit=1 with no properties: the cheapest call that still proves the token and a scope.
+  const { status, json } = await http("https://api.hubapi.com/crm/v3/objects/contacts?limit=1", {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (status === 200) {
+    return ok("HUBSPOT_TOKEN", "CRM readable");
+  }
+  // 403 is a granted-scopes problem, not a bad token — different fix, so say which.
+  return fail(
+    "HUBSPOT_TOKEN",
+    status === 403 ? "token valid but missing CRM read scope (403)" : `contacts → ${status}`,
+  );
+}
+
+async function checkKleer() {
+  const token = env.KLEER_API_TOKEN;
+  if (!token) {
+    return skip("KLEER_API_TOKEN", "unset");
+  }
+  // The only POST in the read-only skill: it lists the companies this token can reach, and
+  // is the documented way to discover a company id. It changes nothing.
+  const { status, json } = await http("https://api.kleer.se/v1/access/authenticate", {
+    method: "POST",
+    headers: { "X-Token": token, "content-type": "application/json" },
+  });
+  if (status === 200) {
+    const companies = json?.["accessible-companies"];
+    const count = Array.isArray(companies)
+      ? companies.length
+      : Array.isArray(companies?.["accessible-companies"])
+        ? companies["accessible-companies"].length
+        : "?";
+    return ok("KLEER_API_TOKEN", `${count} companies reachable`);
+  }
+  return fail("KLEER_API_TOKEN", json?.message ? `${json.message} (${status})` : `authenticate → ${status}`);
+}
+
 async function checkCloudflare() {
   if (!env.CLOUDFLARE_API_KEY || !env.CLOUDFLARE_ACCOUNT_ID) {
     return skip("CLOUDFLARE", "CLOUDFLARE_API_KEY/ACCOUNT_ID not set");
@@ -513,9 +555,17 @@ async function checkDeploymentsContext() {
 }
 
 function checkPresence() {
-  for (const k of ["CLAUDE_CODE_OAUTH_TOKEN", "AGENT_WEBHOOK_SECRET"]) {
+  for (const k of ["CLAUDE_CODE_OAUTH_TOKEN"]) {
     env[k] ? ok(k, "present (not remotely testable)") : skip(k, "unset");
   }
+  // 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 {
+    skip("AGENT_API_SECRET", "unset");
+  }
 }
 
 // --- Run ---------------------------------------------------------------------
@@ -540,6 +590,8 @@ const CHECKS = [
   ["POSTHOG", checkPosthog],
   ["AHREFS_API_KEY", checkAhrefs],
   ["SERPER_API_KEY", checkSerper],
+  ["HUBSPOT_TOKEN", checkHubspot],
+  ["KLEER_API_TOKEN", checkKleer],
   ["CLOUDFLARE", checkCloudflare],
   ["ELEVENLABS_API_KEY", checkElevenlabs],
   ["GOOGLE_API_KEY (Places)", checkPlaces],