@meffecta/agent 1.0.3 → 1.0.7

package/lib/resources.js

@@ -0,0 +1,300 @@
+// What the set-up built in Google Cloud, in the terms of someone who did not build it.
+//
+// `status` answers "is it working", `doctor` answers "what is broken". Neither answers the
+// question someone asks first, which is what all this stuff in my Google Cloud console
+// even is — a dozen resources across seven products, most of them named after each other,
+// none of them explaining themselves. Handing someone a `gcloud` command per product is
+// not an answer either: they would have to know which products to ask about.
+//
+// So this walks the whole footprint in one pass, says what each thing is FOR, and links
+// into the console for anyone who would rather click. Everything found that the set-up did
+// not create is listed too, unexplained but visible — an inventory that quietly omitted
+// what it did not recognise would be worse than none.
+
+import { requireDeployment } from "./config.js";
+import { gcloudArgs, probe, requireCommand } from "./gcloud.js";
+
+/**
+ * Every Google API `setup-infra` switches on, and why.
+ *
+ * `engine` is the deployment itself and its absence breaks everything. `capability` is one
+ * integration — a deployment that never touches Google Ads does not need that one on, and
+ * saying so is the difference between a real finding and a scary red line. `ci` is only
+ * for a deployment that builds images in its own GCP project.
+ *
+ * Kept in step with scripts/setup-infrastructure.sh by a test, since the two drifting
+ * apart would make this quietly wrong in the one direction that matters.
+ */
+export const APIS = [
+  { id: "run.googleapis.com", need: "engine", what: "runs the agent" },
+  { id: "artifactregistry.googleapis.com", need: "engine", what: "serves the engine image to it" },
+  { id: "secretmanager.googleapis.com", need: "engine", what: "holds its credentials" },
+  { id: "storage.googleapis.com", need: "engine", what: "its memory and audit buckets" },
+  { id: "cloudscheduler.googleapis.com", need: "engine", what: "the clock behind every cron" },
+  { id: "cloudtasks.googleapis.com", need: "engine", what: "webhooks, manual runs, follow-ups" },
+  { id: "iam.googleapis.com", need: "engine", what: "the login it acts as" },
+  { id: "iamcredentials.googleapis.com", need: "engine", what: "lets it mint its own access tokens" },
+  { id: "gmail.googleapis.com", need: "capability", what: "sending mail, reading a watched inbox" },
+  { id: "calendar-json.googleapis.com", need: "capability", what: "calendars" },
+  { id: "drive.googleapis.com", need: "capability", what: "Drive files" },
+  { id: "sheets.googleapis.com", need: "capability", what: "spreadsheets" },
+  { id: "docs.googleapis.com", need: "capability", what: "documents" },
+  { id: "slides.googleapis.com", need: "capability", what: "presentations" },
+  { id: "googleads.googleapis.com", need: "capability", what: "Google Ads" },
+  { id: "searchconsole.googleapis.com", need: "capability", what: "Search Console" },
+  { id: "analyticsdata.googleapis.com", need: "capability", what: "Google Analytics" },
+];
+
+const CONSOLE = "https://console.cloud.google.com";
+
+/** The bits of gcloud's naming that nobody needs to see: projects/x/locations/y/things/NAME. */
+const leaf = (value) => (value ?? "").split("/").pop();
+
+function section(title, link) {
+  console.log(`\n${title}`);
+  if (link) {
+    console.log(`  ↗ ${link}`);
+  }
+}
+
+function row(mark, name, note, width) {
+  console.log(`  ${mark} ${name.padEnd(width)}  ${note}`);
+}
+
+/** Seconds → the unit a person would have said it in. */
+function duration(seconds) {
+  const n = Number(seconds);
+  if (!n) {
+    return "";
+  }
+  const days = Math.round(n / 86400);
+  return days >= 365 ? `${Math.round(days / 365)} year${days >= 730 ? "s" : ""}` : `${days} days`;
+}
+
+export async function resources() {
+  requireCommand("gcloud", "everything here lives in your Google Cloud project");
+  const d = requireDeployment();
+  const g = (args) => probe("gcloud", gcloudArgs(d, args));
+  const repo = d.ARTIFACT_REPO ?? `${d.SERVICE}-images`;
+  const runtimeSa = `agent-runtime@${d.PROJECT}.iam.gserviceaccount.com`;
+
+  console.log(`▶ What the set-up built in Google Cloud`);
+  console.log(`   project ${d.PROJECT}   region ${d.REGION}`);
+  console.log(`   Reading it now — a dozen questions to Google, so give it a moment.`);
+
+  // All at once: a dozen serial gcloud calls is half a minute of nothing happening, and
+  // none of these reads depends on another.
+  const [service, buckets, registry, accounts, roles, secrets, boundSecrets, schedules, queue, apis, pool] =
+    await Promise.all([
+      g(["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+      g(["storage", "buckets", "list", "--format=value[separator='\t'](name,retention_policy.retention_period)"]),
+      g(["artifacts", "repositories", "describe", repo, `--location=${d.REGION}`, "--format=json"]),
+      g(["iam", "service-accounts", "list", "--format=value[separator='\t'](email,displayName)"]),
+      g([
+        "projects",
+        "get-iam-policy",
+        d.PROJECT,
+        "--flatten=bindings[].members",
+        `--filter=bindings.members:serviceAccount:${runtimeSa}`,
+        "--format=value(bindings.role)",
+      ]),
+      g(["secrets", "list", "--format=value(name)"]),
+      g([
+        "run",
+        "services",
+        "describe",
+        d.SERVICE,
+        `--region=${d.REGION}`,
+        "--format=value(spec.template.spec.containers[0].env)",
+      ]),
+      g(["scheduler", "jobs", "list", `--location=${d.REGION}`, "--format=value(ID)"]),
+      g(["tasks", "queues", "describe", `${d.SERVICE}-runs`, `--location=${d.REGION}`, "--format=value(state)"]),
+      g(["services", "list", "--enabled", "--format=value(config.name)"]),
+      g(["iam", "workload-identity-pools", "describe", "github-pool", "--location=global", "--format=value(state)"]),
+    ]);
+
+  const missing = [];
+
+  // --- The service itself ---
+  section("THE AGENT", `${CONSOLE}/run/detail/${d.REGION}/${d.SERVICE}?project=${d.PROJECT}`);
+  if (service) {
+    const svc = JSON.parse(service);
+    const tpl = svc.spec.template;
+    const ann = tpl.metadata.annotations ?? {};
+    const sleeps = (ann["autoscaling.knative.dev/minScale"] ?? "0") === "0";
+    const width = d.SERVICE.length;
+    const tag = tpl.spec.containers[0].image.split(":").pop();
+    row("✔", d.SERVICE, "a Cloud Run service — this is the agent", width);
+    console.log(`      ${svc.status?.url ?? "(no url yet)"}`);
+    console.log(`      running engine ${tag}${tag === "latest" ? " — the newest published build" : ""}`);
+    console.log(
+      `      ${sleeps ? "asleep between jobs, so it costs nothing while idle" : "awake all the time, driving its own clock"}`,
+    );
+  } else {
+    missing.push("the Cloud Run service — meffecta-agent setup-infra");
+    row("✖", d.SERVICE, "NOT THERE — nothing is deployed yet", d.SERVICE.length);
+  }
+
+  // --- Buckets ---
+  const bucketRows = (buckets ?? "")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => line.split("\t"));
+  const known = {
+    [`${d.PROJECT}-memory`]: "what it remembers between runs — mounted into it as /memory",
+    [`${d.PROJECT}-audit`]: "an unerasable record of what it did",
+  };
+  section("WHERE IT KEEPS THINGS", `${CONSOLE}/storage/browser?project=${d.PROJECT}`);
+  const bucketWidth = Math.max(...Object.keys(known).map((n) => n.length), ...bucketRows.map(([n]) => leaf(n).length));
+  for (const name of [`${d.PROJECT}-memory`, `${d.PROJECT}-audit`]) {
+    const found = bucketRows.find(([n]) => leaf(n) === name);
+    if (found) {
+      const kept = duration(found[1]);
+      row("✔", name, `${known[name]}${kept ? `, kept ${kept}` : ""}`, bucketWidth);
+    } else {
+      missing.push(`the ${name.endsWith("-audit") ? "audit" : "memory"} bucket — meffecta-agent setup-infra`);
+      row("✖", name, "NOT THERE — it has nowhere to remember or record", bucketWidth);
+    }
+  }
+  for (const [name] of bucketRows) {
+    const short = leaf(name);
+    if (!short.startsWith(`${d.PROJECT}-memory`) && !short.startsWith(`${d.PROJECT}-audit`)) {
+      row("·", short, known[short] ?? "not part of the agent set-up", bucketWidth);
+    }
+  }
+
+  // --- Registry ---
+  section(
+    "WHERE THE ENGINE COMES FROM",
+    `${CONSOLE}/artifacts/docker/${d.PROJECT}/${d.REGION}/${repo}?project=${d.PROJECT}`,
+  );
+  if (registry) {
+    const ar = JSON.parse(registry);
+    const proxy = ar.mode === "REMOTE_REPOSITORY";
+    const upstream = ar.remoteRepositoryConfig?.commonRepository?.uri ?? "ghcr.io";
+    row(
+      "✔",
+      repo,
+      proxy
+        ? `a window onto ${upstream} — the engine is fetched on demand, never copied by you`
+        : "your own copy of each engine version, pushed from your machine",
+      repo.length,
+    );
+    console.log(
+      proxy
+        ? "      Cached copies expire on their own; the real archive is public and elsewhere."
+        : "      Old versions expire on their own — see meffecta-agent artifact-cleanup.",
+    );
+  } else {
+    missing.push(`the image registry ${repo} — meffecta-agent setup-infra`);
+    row("✖", repo, "NOT THERE — Cloud Run has nothing to pull", repo.length);
+  }
+
+  // --- Identities ---
+  const saRows = (accounts ?? "")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => line.split("\t"));
+  section("WHO IT ACTS AS", `${CONSOLE}/iam-admin/serviceaccounts?project=${d.PROJECT}`);
+  const saWidth = Math.max(...saRows.map(([email]) => email.split("@")[0].length), runtimeSa.split("@")[0].length);
+  const explain = {
+    "agent-runtime": "the agent's own login — every job runs as this",
+    "github-deployer": "used by a GitHub action to deploy, if you set one up",
+  };
+  if (!saRows.some(([email]) => email === runtimeSa)) {
+    missing.push("the agent-runtime service account — meffecta-agent setup-infra");
+    row("✖", "agent-runtime", "NOT THERE — the agent has no identity", saWidth);
+  }
+  for (const [email, display] of saRows.sort()) {
+    const name = email.split("@")[0];
+    const note = explain[name] ?? `${display || "no description"} — not part of the agent set-up`;
+    row(email === runtimeSa ? "✔" : explain[name] ? "✔" : "·", name, note, saWidth);
+  }
+  const held = (roles ?? "").split("\n").filter(Boolean);
+  if (held.length) {
+    console.log(`      agent-runtime may, across the whole project: ${held.map((r) => leaf(r)).join(", ")}`);
+    console.log(`      and read/write its two buckets. Nothing else.`);
+  }
+
+  // --- Secrets ---
+  const secretNames = (secrets ?? "").split("\n").filter(Boolean).map(leaf);
+  const boundCount = new Set((boundSecrets ?? "").match(/'([^']+)'/g) ?? []).size;
+  section("ITS CREDENTIALS", `${CONSOLE}/security/secret-manager?project=${d.PROJECT}`);
+  if (secretNames.length) {
+    console.log(`  ✔ ${secretNames.length} secret(s) stored, encrypted, never printed by this CLI.`);
+    console.log(`      Which ones the agent actually reads: meffecta-agent secrets`);
+  } else {
+    missing.push("every credential — meffecta-agent set-secret AGENT_API_SECRET --random");
+    console.log("  ✖ Nothing stored. The service cannot start without AGENT_API_SECRET.");
+  }
+  if (boundCount === 0 && secretNames.length) {
+    console.log("      ⚠ none of them is wired to the service — meffecta-agent secrets");
+  }
+
+  // --- Triggers ---
+  const jobs = (schedules ?? "").split("\n").filter(Boolean);
+  const crons = jobs.filter((name) => name.startsWith(`${d.SERVICE}-job-`));
+  section("WHAT SETS IT OFF", `${CONSOLE}/cloudscheduler?project=${d.PROJECT}`);
+  if (jobs.length) {
+    console.log(
+      `  ✔ ${crons.length} scheduled job(s)${jobs.includes(`${d.SERVICE}-sweep`) ? ", plus the housekeeping sweep" : ""}`,
+    );
+    console.log(`      When each one runs: meffecta-agent triggers`);
+  } else {
+    missing.push("every trigger — meffecta-agent sync-triggers");
+    console.log("  ✖ Nothing scheduled. A sleeping service with no triggers runs nothing at all.");
+  }
+  console.log(
+    `  ${queue ? "✔" : "✖"} ${d.SERVICE}-runs — the queue that carries webhooks, manual runs and follow-ups` +
+      `${queue ? "" : " (NOT THERE)"}`,
+  );
+
+  // --- APIs ---
+  const enabled = new Set((apis ?? "").split("\n").filter(Boolean));
+  section("GOOGLE SERVICES SWITCHED ON", `${CONSOLE}/apis/dashboard?project=${d.PROJECT}`);
+  const apiWidth = Math.max(...APIS.map((a) => a.id.replace(".googleapis.com", "").length));
+  for (const group of ["engine", "capability"]) {
+    const mine = APIS.filter((a) => a.need === group);
+    const off = mine.filter((a) => !enabled.has(a.id));
+    console.log("");
+    console.log(
+      `  ${group === "engine" ? "Needed by the agent itself" : "Needed only for what you use"} — ${mine.length - off.length}/${mine.length} on`,
+    );
+    for (const api of mine) {
+      const on = enabled.has(api.id);
+      // A capability API that is off is a choice, not a fault: nothing breaks until a job
+      // reaches for it, and then it says so.
+      row(on ? "✔" : group === "engine" ? "✖" : "·", api.id.replace(".googleapis.com", ""), api.what, apiWidth);
+    }
+    if (off.length && group === "engine") {
+      missing.push(`${off.length} Google API(s) the agent needs — meffecta-agent setup-infra`);
+    }
+  }
+  const extra = enabled.size - APIS.filter((a) => enabled.has(a.id)).length;
+  if (extra > 0) {
+    console.log(`  · and ${extra} more that Google switches on for every project — nothing to do with the agent`);
+  }
+
+  // --- Optional CI path ---
+  if (pool) {
+    section("DEPLOYING FROM GITHUB", `${CONSOLE}/iam-admin/workload-identity-pools?project=${d.PROJECT}`);
+    console.log("  ✔ github-pool — lets a GitHub action deploy without you storing a key anywhere");
+  }
+
+  // --- What any of it costs ---
+  console.log("\nWHAT COSTS ANYTHING");
+  console.log("  The service (only while a job is running), the stored images, the two buckets,");
+  console.log("  each stored secret, and each scheduled job. Idle, this is small change.");
+  console.log(`  ↗ ${CONSOLE}/billing/linkedaccount?project=${d.PROJECT}`);
+
+  if (missing.length) {
+    console.log(`\n⚠ ${missing.length} thing(s) are not there yet:`);
+    for (const item of missing) {
+      console.log(`   • ${item}`);
+    }
+  } else {
+    console.log("\n✔ Everything the set-up creates is there.");
+  }
+  console.log("  Whether it all WORKS is a different question: meffecta-agent doctor");
+  return 0;
+}

package/lib/verify-credentials.js

@@ -0,0 +1,129 @@
+// The credential check, in two halves — because only one of them can be a script.
+//
+// The engine's own script tests what the engine knows the mechanics of: its essentials,
+// and the integrations that ship with it. It cannot test a system that belongs to one
+// deployment. `ACME_CRM_TOKEN` means nothing to an image that ships to everyone: testing a
+// credential means knowing its endpoint, its auth header, and what a good answer looks
+// like, and none of that can be in a shipped file.
+//
+// One thing in the deployment does know: its register — `systems/`, a file per system
+// saying which skill reaches it, which variables carry the credential, what access is
+// allowed, and the cheapest read that proves it works. Reading that, choosing a skill,
+// making the call and judging the answer is not script work — but it is exactly what the
+// agent does, and this check already runs as an agent. It was simply being used to relay
+// `cat` output.
+//
+// So the run does both: the script verbatim, then the register, system by system.
+//
+// The safety line is READ ONLY, and it is stated rather than implied. A register entry's
+// `access:` says things like "read + send" and "read + write" — that describes what a JOB
+// may do, not what a health check may do. A check that emailed someone to prove the mail
+// credential works would be a check that emails someone.
+
+import { UserError } from "./config.js";
+import { parseFlags } from "./flags.js";
+
+/** The absolute path is right: a run's cwd is the content clone, the script is in the image. */
+const SCRIPT = "node /app/scripts/verify-credentials.mjs";
+
+const PROMPT = `Check this deployment's credentials. Two parts, in order.
+
+PART 1 — the engine's own check.
+
+Run: ${SCRIPT}
+
+Reproduce its output verbatim and in full, inside a fenced block. Do not summarise it,
+reformat it, re-order it or correct it. It is the deterministic half and its exact wording
+is the point. Add nothing of your own to it.
+
+PART 2 — this deployment's own systems.
+
+Part 1 tests what the ENGINE knows how to test. It cannot test a system belonging to this
+deployment specifically. The register of those is \`systems/\` in your working directory —
+one file per system — or, in a deployment that has not moved to that yet, a single
+ENVIRONMENT.md table. Read whichever is present.
+
+Each file's frontmatter says what to do:
+  system:     what it is
+  skill:      the skill that reaches it, or "none" plus how it is reached instead
+  requires:   exact variable names, ALL of which must be set
+  selectors:  optional per-project pointers — an unset one means that project is not
+              wired up, which is not a fault
+  access:     what a JOB may do. It is NOT permission for this check.
+  probe:      the cheapest read that proves the credential works, in plain English
+
+For every system:
+
+- If Part 1 already tested it, say so and move on. Never test the same thing twice.
+- Otherwise carry out its \`probe:\` using the named skill. Exactly that, once. If there is
+  no probe:, make the smallest read-only call the skill supports — cheapest endpoint, no
+  pagination, no date ranges, no bulk export.
+- READ ONLY, always, whatever \`access:\` says — that field describes what a job may do, not
+  what a health check may do. Never write, send, create, update, upload or delete. If a
+  system has no read path, report it untestable rather than testing it with a write.
+- Never print a credential value, in whole or in part, and never put one in a command you
+  show. Names only.
+- If a variable under \`requires:\` is unset, that is a finding, not a skip: the register is
+  promising a system this deployment cannot reach.
+
+Then reconcile the other way. Part 1 ends with any credentials that are set but that it
+does not know how to test. If one of those has no file in \`systems/\`, that is a finding
+too — a skill only learns a system exists by reading the register, so a credential missing
+from it will never be used by any job, however valid it is.
+
+REPORT exactly like this, and nothing else:
+
+<Part 1's output, verbatim, in a fenced block>
+
+This deployment's own systems (systems/)
+  ✅ <system>  <the evidence — "6 zones", "responded 200", "3 rows">
+  ❌ <system>  <the error, one line>
+  ⏭️  <system>  <why it could not be tested>
+
+Register vs reality
+  <each mismatch on one line, or "nothing to report">
+
+Rules for the report: under 60 lines total. This is a status report, not an
+investigation — if something fails, state the failure and move on. Do not debug it, do not
+retry it, do not suggest fixes unless the fix is one short clause. If a skill is missing or
+a register file is unreadable, say so plainly rather than guessing at what it meant.`;
+
+export function buildVerifyPrompt() {
+  return PROMPT;
+}
+
+/**
+ * The credential doctor. It runs in the deployment, because that is the only place the
+ * credentials are — and because only something with the register in front of it can test
+ * the systems that are this deployment's own.
+ *
+ * There was a local mode, and it was a trap: a deployment's credentials live in Secret
+ * Manager bound to the service, so run from a content repo it reported "0 ok, 0 failed,
+ * everything skipped" — zero failures having tested nothing, which reads exactly like a
+ * pass. The engine repo keeps `pnpm creds` for whoever has a .env; that is a maintainer's
+ * tool and does not belong in a client's CLI.
+ */
+export function verifyCredentials(ask) {
+  return async (args) => {
+    const { flags, positional } = parseFlags(args, {
+      quick: { type: "boolean" },
+      model: {},
+      effort: {},
+      timeoutSeconds: { type: "int", min: 1, max: 3600 },
+    });
+    if (positional.length) {
+      throw new UserError(`verify-credentials takes no arguments (got "${positional.join(" ")}").`);
+    }
+    const passthrough = Object.entries(flags)
+      .filter(([name]) => name !== "quick")
+      .flatMap(([name, value]) => [`--${name}`, String(value)]);
+
+    if (flags.quick) {
+      console.error("Running the engine's own check on the deployment.");
+      return ask([...passthrough, `Run ${SCRIPT} and return its output verbatim, with nothing added.`]);
+    }
+    console.error("Checking on the deployment: the engine's own credentials, then every system in");
+    console.error("your register. Takes a couple of minutes — --quick does the first half only.");
+    return ask([...passthrough, PROMPT]);
+  };
+}

package/lib/version.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Version facts, in their own module because both commands.js and doctor.js need them and
+// commands.js already imports doctor.js — putting them in either would make a cycle.
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function cliVersion() {
+  try {
+    return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Where this CLI was installed from, so an upgrade prints a line that actually works. The
+ * alternative — shelling out to `npm i -g` — guesses wrong for anyone not on npm, needs
+ * sudo under a root-owned prefix, and has the process replace its own package while it is
+ * running. Printing the right command is honest, and one keystroke away.
+ */
+export function installMethod() {
+  const here = packageRoot.replaceAll("\\", "/");
+  if (here.includes("/_npx/")) {
+    return {
+      kind: "npx",
+      upgrade: "npx @meffecta/agent@latest <command>",
+      note: "npx fetches on demand — pin a version there rather than installing one",
+    };
+  }
+  if (here.includes("/pnpm/")) {
+    return { kind: "pnpm", upgrade: "pnpm add -g @meffecta/agent@latest" };
+  }
+  if (here.includes("/.bun/")) {
+    return { kind: "bun", upgrade: "bun add -g @meffecta/agent@latest" };
+  }
+  if (here.includes("/.volta/")) {
+    return { kind: "volta", upgrade: "volta install @meffecta/agent@latest" };
+  }
+  if (existsSync(resolve(packageRoot, "..", "src", "index.ts"))) {
+    return { kind: "checkout", upgrade: "git pull", note: "this is the engine checkout, not an installed package" };
+  }
+  return { kind: "npm", upgrade: "npm i -g @meffecta/agent@latest" };
+}
+
+/** The newest published version, or undefined when the registry cannot be reached. */
+export async function latestPublished() {
+  try {
+    const res = await fetch("https://registry.npmjs.org/@meffecta/agent/latest", {
+      signal: AbortSignal.timeout(5000),
+      headers: { accept: "application/vnd.npm.install-v1+json, application/json" },
+    });
+    return res.ok ? ((await res.json())?.version ?? undefined) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * true when `a` is strictly newer than `b`. Deliberately strict about the shape: anything
+ * that is not a plain x.y.z on both sides answers false, so a prerelease or a garbled
+ * version never produces a confident "you are out of date".
+ */
+export function isNewer(a, b) {
+  const parse = (v) => (/^\d+\.\d+\.\d+$/.test(v ?? "") ? v.split(".").map(Number) : undefined);
+  const [x, y] = [parse(a), parse(b)];
+  if (!x || !y) {
+    return false;
+  }
+  for (let i = 0; i < 3; i++) {
+    if (x[i] !== y[i]) {
+      return x[i] > y[i];
+    }
+  }
+  return false;
+}
+
+/**
+ * What an operator would type to reach this CLI again. The scripts print each other's
+ * names in their closing instructions, and the honest name depends on how you got here:
+ * a global install answers to `meffecta-agent`, an npx run to nothing at all once it
+ * exits. It is exported to every script as MEFFECTA_CLI, which is also the signal that a
+ * CLI exists — a deployment that lifted scripts/ out of the image has none, and there the
+ * scripts name each other by filename instead.
+ */
+export function invocation() {
+  return installMethod().kind === "npx" ? "npx @meffecta/agent" : "meffecta-agent";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meffecta/agent",
-  "version": "1.0.3",
+  "version": "1.0.7",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "directory": "cli"
   },
   "scripts": {
-    "prepack": "node prepack.mjs"
+    "prepack": "node prepack.mjs",
+    "postpack": "node prepack.mjs --clean"
   }
 }

package/scripts/create-project.sh

@@ -16,6 +16,8 @@ set -euo pipefail
 #   scripts/create-project.sh --name "Acme Agent" --id acme-agent
 #   ORGANIZATION=123456789 scripts/create-project.sh     # or FOLDER=...
 
+. "$(dirname "${BASH_SOURCE[0]}")/lib/cli-names.sh"
+
 NAME=""
 PROJECT_ID=""
 
@@ -100,7 +102,7 @@ echo ""
 echo "✔ Created ${PROJECT_ID}"
 echo ""
 echo "Next: link a billing account (nothing else works without it) —"
-echo "    $(dirname "$0")/link-billing.sh --project ${PROJECT_ID}"
+echo "    $(cmd link-billing) --project ${PROJECT_ID}"
 echo ""
 echo "And in step 3, this goes in your content repo's deployment.env:"
 echo "    PROJECT=${PROJECT_ID}"

package/scripts/deploy.sh

@@ -5,7 +5,7 @@ set -euo pipefail
 #
 # The engine's CI publishes images to GHCR and stops there: choosing when to move to a
 # new engine version is the deployment's call, not the engine repo's. This script is
-# that call, and it is the same script for Marcus's instance and for a client's.
+# that call, and it is the same script for the vendor's own instance and for a client's.
 #
 # Cloud Run can only pull from Artifact Registry, never from GHCR directly, so an image
 # has to reach the deployment's own AR first. Two ways:
@@ -34,7 +34,7 @@ set -euo pipefail
 # bucket name or a service account breaks a deployment far worse than drift does.
 #
 # A deployment driven by Cloud Scheduler also gets its triggers re-synced afterwards
-# (scripts/setup-scheduler.sh): a deploy restarts the service, which is when new or renamed
+# (scripts/sync-triggers.sh): a deploy restarts the service, which is when new or renamed
 # `cron:` registrations from the content repo take effect, so it is also when the Scheduler
 # jobs mirroring them have to be brought up to date. An always-on deployment drives itself
 # and is left alone.
@@ -71,14 +71,25 @@ require_gcloud
 resolve_deployment
 announce_target "Deploying ${SERVICE}"
 
-# --tag mirrors GHCR → this deployment's Artifact Registry; --image is taken as-is
-# (already in AR, or reachable through an AR remote repository).
-if [ -z "${IMAGE}" ]; then
+# --image is taken as-is. Otherwise --tag resolves against this deployment's registry, and
+# how it gets there depends on REGISTRY_MODE: `proxy` names the image inside a remote
+# repository and lets Artifact Registry fetch it on demand; `mirror` pulls and pushes it
+# from here, which is the only path that needs docker.
+if [ -z "${IMAGE}" ] && [ "${REGISTRY_MODE}" = "proxy" ]; then
+  # A remote repository preserves the upstream path, so ghcr.io/meffecta/agent is served at
+  # <repo>/meffecta/agent. Nothing is copied and nothing is pushed: the first pull populates
+  # AR's cache, and Cloud Run's own pull is what triggers it.
+  IMAGE="${REGION}-docker.pkg.dev/${PROJECT}/${ARTIFACT_REPO}/${GHCR_PATH}:${TAG}"
+  echo "🔗 Through the registry proxy: ${IMAGE}"
+  echo "   (Artifact Registry fetches ${GHCR_IMAGE}:${TAG} on demand — no local docker)"
+elif [ -z "${IMAGE}" ]; then
   SOURCE="${GHCR_IMAGE}:${TAG}"
   IMAGE="${REGION}-docker.pkg.dev/${PROJECT}/${ARTIFACT_REPO}/${SERVICE}:${TAG}"
   command -v docker >/dev/null || {
     echo "docker is required to mirror ${SOURCE} into Artifact Registry." >&2
-    echo "Either install it, or set up an AR remote repository and pass --image." >&2
+    echo "REGISTRY_MODE=proxy in deployment.env avoids it entirely — Artifact Registry" >&2
+    echo "fetches from ghcr.io itself. After changing it, re-run:" >&2
+    echo "  $(cmd setup-infra)" >&2
     exit 1
   }
   echo "📥 Mirroring ${SOURCE} → ${IMAGE}"
@@ -118,7 +129,7 @@ EOF
   fi
 fi
 
-# scale-to-zero is the default and what setup-scheduler.sh's triggers assume: no CPU
+# scale-to-zero is the default and what sync-triggers.sh's triggers assume: no CPU
 # except while a request is open, which is only correct because nothing in the service
 # fires on its own. always-on is the other coherent pair, for a deployment that drives
 # itself with in-process timers instead.
@@ -156,7 +167,7 @@ if [ "${SYNC_SCHEDULER}" = true ] &&
   gcloud run services describe "${SERVICE}" --project "${PROJECT}" --region "${REGION}" \
     --format json 2>/dev/null | grep -q AGENT_TASKS_QUEUE; then
   echo ""
-  "$(dirname "${BASH_SOURCE[0]}")/setup-scheduler.sh" ${CONFIG_FILE:+--config "${CONFIG_FILE}"}
+  "$(dirname "${BASH_SOURCE[0]}")/sync-triggers.sh" ${CONFIG_FILE:+--config "${CONFIG_FILE}"}
 fi
 
 URL=$(gcloud run services describe "${SERVICE}" \