@meffecta/agent 0.0.1

package/deployment.env.example

@@ -0,0 +1,54 @@
+# Which GCP project and service this deployment runs as.
+#
+# This file belongs in your CONTENT repo, committed — next to jobs/ and SYSTEM.md, not
+# in the engine repo. It describes your deployment, nothing here is secret (secrets live
+# in Secret Manager), and a fresh clone of the content repo is then everything an
+# operator needs.
+#
+# Copy it there once:
+#   cp deployment.env.example /path/to/your-content-repo/deployment.env
+#
+# 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/deploy.sh
+
+# The GCP *project ID* — check it with `gcloud projects list`, as the console may have
+# suffixed it and it need not match the project's display name.
+PROJECT=acme-agent-123456
+
+# The Cloud Run service.
+SERVICE=acme-agent
+
+# Docker repo in that project, holding images mirrored from GHCR.
+ARTIFACT_REPO=acme-agent-images
+
+REGION=europe-west1
+
+# Optional. Unset = whichever account gcloud is logged in as. Set it when you work across
+# several Google accounts and want this deployment pinned to one.
+# ACCOUNT=you@example.com
+
+# Optional. The service's TIMEZONE env var, which is what cron schedules are read in.
+# TIMEZONE=Europe/Stockholm
+
+# Optional. Where published engine images come from.
+# GHCR_IMAGE=ghcr.io/meffecta/agent
+
+# Optional. The runtime shape deploy.sh asserts on every rollout, so the deployed service
+# matches this file rather than whatever was last changed by hand. The defaults below are
+# what setup-infrastructure.sh provisions, so leaving them out is the same as setting them.
+#
+# SCALING picks one of two coherent pairs, and the choice is not cosmetic:
+#   scale-to-zero  min-instances=0 + CPU billed per request. Costs nothing between jobs,
+#                  and requires setup-scheduler.sh — the service has no CPU of its own to
+#                  run a timer with, so everything must arrive as a request.
+#   always-on      min-instances=1 + CPU always allocated, for a deployment that drives
+#                  itself with in-process timers and has no Cloud Scheduler triggers.
+# Running scale-to-zero without triggers is a service that does nothing; running always-on
+# with them fires every cron twice.
+# SCALING=scale-to-zero
+# CPU=2
+# MEMORY=4Gi
+# MAX_INSTANCES=1        # >1 breaks the serial run queue — raise only with reason
+# REQUEST_TIMEOUT=3600   # seconds one held request may last; the ceiling on a single run

package/engine.json

@@ -0,0 +1,4 @@
+{
+  "engineTag": "",
+  "builtFrom": "local"
+}

package/lib/commands.js

@@ -0,0 +1,407 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { requireDeployment, UserError } from "./config.js";
+import { api, requireCommand, stream } from "./gcloud.js";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Where the operator scripts are. In the published package they sit at its root; in a
+ * checkout of the engine repo they are one level up, beside cli/. Same files either way —
+ * the pack step copies them in, so the CLI is a front on exactly the scripts a deployment
+ * would otherwise run by hand.
+ */
+export const scriptsDir = [resolve(packageRoot, "scripts"), resolve(packageRoot, "..", "scripts")].find((candidate) =>
+  existsSync(candidate),
+);
+
+/**
+ * The engine build this CLI was published alongside. CI writes it at pack time, so
+ * `deploy` defaults to the image from the same commit as the tooling deploying it — the
+ * one property that makes a separate npm package safe to have at all. Absent in a
+ * checkout, where "latest" is the honest answer.
+ */
+export function engineTag() {
+  const file = resolve(packageRoot, "engine.json");
+  if (!existsSync(file)) {
+    return { tag: "latest", pinned: false };
+  }
+  try {
+    const { engineTag: tag } = JSON.parse(readFileSync(file, "utf8"));
+    return tag ? { tag, pinned: true } : { tag: "latest", pinned: false };
+  } catch {
+    return { tag: "latest", pinned: false };
+  }
+}
+
+export function cliVersion() {
+  try {
+    return JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+/** A command that is one of the shipped scripts, with every argument passed straight on. */
+function script(file, { interpreter } = {}) {
+  return async (args) => {
+    if (!scriptsDir) {
+      throw new UserError("The operator scripts are missing from this install — reinstall @meffecta/agent.");
+    }
+    const path = resolve(scriptsDir, file);
+    if (!existsSync(path)) {
+      throw new UserError(`Missing script: ${file}`);
+    }
+    const runner = interpreter ?? (file.endsWith(".mjs") ? "node" : "bash");
+    const { code, error } = await stream(runner, [path, ...args]);
+    if (error) {
+      throw new UserError(`Could not run ${runner}: ${error.message}`);
+    }
+    return code;
+  };
+}
+
+/** What the deployment looks like right now: revision, shape, triggers, pending work. */
+async function status() {
+  requireCommand("gcloud", "the CLI reads your deployment through it");
+  const d = requireDeployment();
+  const { capture, gcloudArgs } = await import("./gcloud.js");
+  const json = capture(
+    "gcloud",
+    gcloudArgs(d, ["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+  );
+  const svc = JSON.parse(json);
+  const tpl = svc.spec.template;
+  const ann = tpl.metadata.annotations ?? {};
+  const container = tpl.spec.containers[0];
+  const env = Object.fromEntries(
+    (container.env ?? []).map((e) => [e.name, e.value ?? (e.valueFrom ? "<secret>" : "")]),
+  );
+  const external = Boolean(env.AGENT_TASKS_QUEUE && env.AGENT_PUBLIC_URL);
+
+  console.log(`▶ ${d.SERVICE}  (${d.PROJECT} / ${d.REGION})`);
+  console.log(`   url        ${svc.status?.url ?? "?"}`);
+  console.log(`   revision   ${svc.status?.latestReadyRevisionName ?? "?"}`);
+  console.log(`   image      ${container.image}`);
+  console.log(
+    `   shape      min ${ann["autoscaling.knative.dev/minScale"] ?? "0"}, max ${
+      ann["autoscaling.knative.dev/maxScale"] ?? "?"
+    }, cpu ${container.resources?.limits?.cpu ?? "?"}, ${container.resources?.limits?.memory ?? "?"}, ` +
+      `timeout ${tpl.spec.timeoutSeconds ?? "?"}s`,
+  );
+  console.log(
+    `   billing    ${ann["run.googleapis.com/cpu-throttling"] === "false" ? "CPU always allocated" : "CPU per request"}`,
+  );
+  console.log(`   triggers   ${external ? "external (Cloud Scheduler + Tasks)" : "in-process timers"}`);
+  console.log(`   content    ${env.GIT_REPO_URL ?? "(unset — the service will not boot)"}`);
+
+  if (external) {
+    const jobs = capture(
+      "gcloud",
+      gcloudArgs(d, ["scheduler", "jobs", "list", `--location=${d.REGION}`, "--format=value(ID)"]),
+    )
+      .split("\n")
+      .filter(Boolean);
+    const crons = jobs.filter((name) => name.startsWith(`${d.SERVICE}-job-`));
+    const sweep = jobs.find((name) => name === `${d.SERVICE}-sweep`);
+    console.log(
+      `   scheduler  ${crons.length} cron trigger(s)${sweep ? " + sweep" : " — NO SWEEP (run setup-scheduler)"}`,
+    );
+    if (crons.length === 0) {
+      console.log("              ⚠ scaled to zero with no triggers: this service runs nothing.");
+    }
+  }
+
+  const repo = d.ARTIFACT_REPO ?? `${d.SERVICE}-images`;
+  try {
+    const size = capture(
+      "gcloud",
+      gcloudArgs(d, ["artifacts", "repositories", "describe", repo, `--location=${d.REGION}`]),
+    ).match(/^Repository Size: (.+)$/m);
+    if (size) {
+      console.log(`   registry   ${repo} — ${size[1]}`);
+    }
+  } catch {
+    // A deployment pulling through a remote repository has none of its own. Not a problem.
+  }
+
+  const queue = JSON.parse(await api(d, "/queue"));
+  console.log(
+    `   queue      ${queue.processing ? "running a job" : "idle"}, ${queue.pending?.length ?? 0} pending, ` +
+      `${queue.spawns?.length ?? 0} follow-up(s) scheduled`,
+  );
+  for (const spawn of queue.spawns ?? []) {
+    console.log(`              ↳ ${spawn.job} "${spawn.label}" at ${spawn.runAt}`);
+  }
+  return 0;
+}
+
+async function jobs() {
+  const d = requireDeployment();
+  const list = JSON.parse(await api(d, "/jobs"));
+  if (list.length === 0) {
+    console.log("No jobs. The content repo's jobs/ directory is empty, or GIT_REPO_URL is wrong.");
+    return 0;
+  }
+  const width = Math.max(...list.map((j) => j.name.length));
+  for (const job of list) {
+    const triggers = [
+      job.cron && `cron ${job.cron}`,
+      job.webhook && `webhook /${job.webhook}`,
+      job.inbox && `inbox ${job.inbox}`,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    console.log(`${job.name.padEnd(width)}  ${triggers || "manual only"}${job.disabled ? "   [disabled]" : ""}`);
+  }
+  return 0;
+}
+
+async function runJob(args) {
+  const name = args[0];
+  if (!name) {
+    throw new UserError("Which job? Try: meffecta-agent jobs");
+  }
+  const d = requireDeployment();
+  const delay = args.includes("--in") ? Number(args[args.indexOf("--in") + 1]) : 0;
+  const query = delay > 0 ? `?delaySeconds=${delay}` : "";
+  const body = JSON.parse(await api(d, `/jobs/${encodeURIComponent(name)}/run${query}`, { method: "POST" }));
+  console.log(
+    body.status === "scheduled"
+      ? `⏳ ${name} scheduled in ${delay}s`
+      : `▶ ${name} queued — it runs on the service, not here. Watch it with: meffecta-agent status`,
+  );
+  return 0;
+}
+
+async function ask(args) {
+  const prompt = args.filter((a) => !a.startsWith("--")).join(" ");
+  if (!prompt) {
+    throw new UserError('Ask it what? e.g. meffecta-agent ask "how did search do last week"');
+  }
+  const d = requireDeployment();
+  const flag = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+  const params = new URLSearchParams({ prompt });
+  for (const name of ["model", "effort", "timeoutSeconds"]) {
+    const value = flag(`--${name}`);
+    if (value) {
+      params.set(name, value);
+    }
+  }
+  console.error("Running on the deployment — this takes as long as the run does.");
+  process.stdout.write(await api(d, `/test?${params}`, { accept: "text/markdown" }));
+  process.stdout.write("\n");
+  return 0;
+}
+
+async function sweep() {
+  requireCommand("gcloud", "the sweep is a Cloud Scheduler job");
+  const d = requireDeployment();
+  const { capture, gcloudArgs } = await import("./gcloud.js");
+  capture("gcloud", gcloudArgs(d, ["scheduler", "jobs", "run", `${d.SERVICE}-sweep`, `--location=${d.REGION}`]));
+  console.log("▶ Sweep triggered: due follow-ups, journalled runs, and the watched inboxes.");
+  return 0;
+}
+
+/** The service's environment: plain values shown, secret-backed ones named but never read. */
+async function envList() {
+  requireCommand("gcloud", "the CLI reads your deployment through it");
+  const d = requireDeployment();
+  const { capture, gcloudArgs } = await import("./gcloud.js");
+  const svc = JSON.parse(
+    capture(
+      "gcloud",
+      gcloudArgs(d, ["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+    ),
+  );
+  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.");
+    return 0;
+  }
+  const width = Math.max(...entries.map((e) => e.name.length));
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const ref = entry.valueFrom?.secretKeyRef;
+    // A secret's value is deliberately not fetched: listing configuration should never be
+    // a way to read credentials out of a deployment.
+    console.log(
+      `${entry.name.padEnd(width)}  ${ref ? `← secret ${ref.name}:${ref.key ?? "latest"}` : (entry.value ?? "")}`,
+    );
+  }
+  console.log(`\n${entries.length} set. Change one: meffecta-agent set-env NAME=VALUE`);
+  return 0;
+}
+
+/** What is in Secret Manager, and whether the service actually reads it. */
+async function secretsList() {
+  requireCommand("gcloud", "the CLI reads your deployment through it");
+  const d = requireDeployment();
+  const { capture, gcloudArgs } = await import("./gcloud.js");
+  const secrets = capture("gcloud", gcloudArgs(d, ["secrets", "list", "--format=value(name)"]))
+    .split("\n")
+    .filter(Boolean)
+    .map((name) => name.split("/").pop());
+  const svc = JSON.parse(
+    capture(
+      "gcloud",
+      gcloudArgs(d, ["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+    ),
+  );
+  const bound = new Set(
+    (svc.spec.template.spec.containers[0].env ?? []).map((e) => e.valueFrom?.secretKeyRef?.name).filter(Boolean),
+  );
+  if (secrets.length === 0) {
+    console.log("No secrets in this project yet. Start with:");
+    console.log("  meffecta-agent set-secret AGENT_WEBHOOK_SECRET --random");
+    return 0;
+  }
+  const width = Math.max(...secrets.map((name) => name.length));
+  for (const name of secrets.sort()) {
+    console.log(`${name.padEnd(width)}  ${bound.has(name) ? "bound to the service" : "stored, NOT bound"}`);
+  }
+  const orphans = [...bound].filter((name) => !secrets.includes(name));
+  for (const name of orphans) {
+    console.log(`${name.padEnd(width)}  ⚠ referenced by the service but missing from Secret Manager`);
+  }
+  console.log(`\nValues are never printed. Set or rotate one: meffecta-agent set-secret NAME [--random]`);
+  return 0;
+}
+
+/** The things that drive a scaled-to-zero service: Cloud Scheduler jobs and the task queue. */
+async function triggers() {
+  requireCommand("gcloud", "the triggers live in Cloud Scheduler and Cloud Tasks");
+  const d = requireDeployment();
+  const { capture, gcloudArgs } = await import("./gcloud.js");
+  const rows = capture(
+    "gcloud",
+    gcloudArgs(d, [
+      "scheduler",
+      "jobs",
+      "list",
+      `--location=${d.REGION}`,
+      "--format=value[separator='\t'](ID,schedule,state,lastAttemptTime)",
+    ]),
+  )
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => line.split("\t"))
+    .filter(([id]) => id.startsWith(`${d.SERVICE}-`));
+
+  if (rows.length === 0) {
+    console.log("No triggers. If this service is scaled to zero it is running nothing:");
+    console.log("  meffecta-agent setup-scheduler");
+    return 0;
+  }
+  const width = Math.max(...rows.map(([id]) => id.length));
+  for (const [id, schedule, state, last] of rows.sort()) {
+    const flag = state === "ENABLED" ? " " : "⏸";
+    console.log(`${flag} ${id.padEnd(width)}  ${(schedule ?? "").padEnd(14)}  last ${last || "never"}`);
+  }
+
+  try {
+    const queue = capture(
+      "gcloud",
+      gcloudArgs(d, [
+        "tasks",
+        "queues",
+        "describe",
+        `${d.SERVICE}-runs`,
+        `--location=${d.REGION}`,
+        "--format=value[separator='\t'](state,stats.tasksCount)",
+      ]),
+    ).split("\t");
+    console.log(`\nTask queue ${d.SERVICE}-runs: ${queue[0] ?? "?"}, ${queue[1] || 0} task(s) waiting`);
+  } catch {
+    console.log(`\nTask queue ${d.SERVICE}-runs: not created — run setup-scheduler`);
+  }
+  return 0;
+}
+
+/** Recent service logs, without making anyone remember the filter syntax. */
+async function logs(args) {
+  requireCommand("gcloud", "logs come from Cloud Logging");
+  const d = requireDeployment();
+  const limit = args.includes("--limit") ? args[args.indexOf("--limit") + 1] : "40";
+  const { code } = await stream("gcloud", [
+    "logging",
+    "read",
+    `resource.type="cloud_run_revision" AND resource.labels.service_name="${d.SERVICE}"`,
+    `--project=${d.PROJECT}`,
+    `--limit=${limit}`,
+    "--format=value[separator='  '](timestamp,severity,textPayload,jsonPayload.msg)",
+  ]);
+  return code;
+}
+
+/** Start a deployment.env in the current directory, from the template in this package. */
+async function init(args) {
+  const { copyFileSync, existsSync: exists } = 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).`);
+    return 0;
+  }
+  const template = [
+    resolve(packageRoot, "deployment.env.example"),
+    resolve(packageRoot, "..", "deployment.env.example"),
+  ].find((candidate) => existsSync(candidate));
+  if (!template) {
+    throw new UserError("The deployment.env template is missing from this install — reinstall @meffecta/agent.");
+  }
+  copyFileSync(template, target);
+  console.log("✅ Wrote deployment.env here.\n");
+  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");
+  console.log("Next: meffecta-agent steps");
+  return 0;
+}
+
+export const GROUPS = [
+  {
+    title: "Set up a deployment, in order",
+    commands: [
+      ["init", "Start a deployment.env here, from the template", init],
+      ["create-project", "Create the GCP project this deployment lives in", script("create-project.sh")],
+      ["link-billing", "Attach a billing account to it", script("link-billing.sh")],
+      [
+        "setup-infra",
+        "Provision GCP: registry, buckets, service account, service shell",
+        script("setup-infrastructure.sh"),
+      ],
+      ["mint-gmail", "Mint a Gmail/Calendar refresh token for one account", script("mint-gmail-token.mjs")],
+      ["mint-graph", "Mint a Microsoft Graph refresh token for one mailbox", script("mint-graph-token.mjs")],
+      ["set-secret", "Store a secret and bind it to the service (--random to generate)", script("set-secret.sh")],
+      ["set-env", "Set non-secret service settings (NAME=VALUE …)", 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")],
+      ["artifact-cleanup", "Expire mirrored images in the deployment's registry", script("set-artifact-cleanup.sh")],
+    ],
+  },
+  {
+    title: "Look at what is there",
+    commands: [
+      ["status", "What the deployment looks like right now", status],
+      ["jobs", "The jobs it has registered, and what triggers them", jobs],
+      ["env", "Every setting on the service (secret values never printed)", envList],
+      ["secrets", "What is in Secret Manager, and whether the service reads it", secretsList],
+      ["triggers", "The Cloud Scheduler jobs and task queue that drive it", triggers],
+      ["logs", "Recent service logs (--limit N)", logs],
+    ],
+  },
+  {
+    title: "Operate it",
+    commands: [
+      ["run", "Trigger one job now, or --in <seconds>", runJob],
+      ["ask", "Ask it something as a one-off run", ask],
+      ["sweep", "Run the housekeeping sweep now", sweep],
+      ["verify-credentials", "Exercise every configured credential from here", script("verify-credentials.mjs")],
+      ["update-tooling", "Refresh the shipped scripts from an engine image (docker path)", script("update-tooling.sh")],
+    ],
+  },
+];
+
+export const COMMANDS = new Map(
+  GROUPS.flatMap((group) => group.commands.map(([name, summary, handler]) => [name, { name, summary, handler }])),
+);

package/lib/config.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * The deployment's settings, read the same way the shell scripts read them: plain
+ * KEY=value lines in ./deployment.env, in the content repo you are standing in. An
+ * environment variable already set wins, which is the one-off override.
+ *
+ * Kept deliberately in step with scripts/lib/deployment.sh — the CLI is a front on those
+ * scripts, so the two must agree about where a deployment's identity comes from.
+ */
+export function loadDeployment(cwd = process.cwd(), configPath) {
+  const file = configPath ?? process.env.DEPLOYMENT_CONFIG ?? resolve(cwd, "deployment.env");
+  const values = {};
+  if (existsSync(file)) {
+    for (const raw of readFileSync(file, "utf8").split("\n")) {
+      const line = raw.trim();
+      if (!line || line.startsWith("#")) {
+        continue;
+      }
+      const eq = line.indexOf("=");
+      if (eq < 1) {
+        continue;
+      }
+      const key = line.slice(0, eq).trim();
+      let value = line.slice(eq + 1).trim();
+      value = value.replace(/\s+#.*$/, "").trim();
+      value = value.replace(/^(["'])(.*)\1$/, "$2");
+      values[key] = value;
+    }
+    values.__file = file;
+  }
+  for (const key of ["PROJECT", "SERVICE", "REGION", "ACCOUNT", "ARTIFACT_REPO"]) {
+    if (process.env[key]) {
+      values[key] = process.env[key];
+    }
+  }
+  values.REGION ??= "europe-west1";
+  return values;
+}
+
+export function requireDeployment(cwd) {
+  const d = loadDeployment(cwd);
+  if (!d.PROJECT || !d.SERVICE) {
+    throw new UserError(
+      `No deployment.env found in ${cwd ?? process.cwd()}.\n\n` +
+        "That file names the GCP project and Cloud Run service this deployment is, and it\n" +
+        "lives in your content repo beside jobs/ — so either run this from there, or start\n" +
+        "one here:\n\n  meffecta-agent init",
+    );
+  }
+  return d;
+}
+
+/** An error whose message is the whole point — printed plainly, no stack. */
+export class UserError extends Error {}

package/lib/gcloud.js

@@ -0,0 +1,109 @@
+import { spawn, spawnSync } from "node:child_process";
+import { UserError } from "./config.js";
+
+/** Run a command with its output going straight to the terminal; resolve with its code. */
+export function stream(command, args, options = {}) {
+  return new Promise((resolveRun) => {
+    const child = spawn(command, args, { stdio: "inherit", ...options });
+    child.on("error", (err) => {
+      resolveRun({ code: 127, error: err });
+    });
+    child.on("close", (code) => resolveRun({ code: code ?? 0 }));
+  });
+}
+
+/**
+ * Run a command and capture stdout. Used for the reads the CLI formats itself, and for
+ * the one value that must never reach the terminal — the webhook secret.
+ */
+export function capture(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8" });
+  if (result.error) {
+    throw new UserError(`Could not run ${command}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const output = (result.stderr || result.stdout || "").trim();
+    // The most common failure by far, and gcloud's own wording buries the fix in a stack.
+    if (/[Rr]eauthentication failed|auth login|credentials.*not found|not currently active/.test(output)) {
+      throw new UserError("Your gcloud session has expired.\n\n  gcloud auth login\n\nThen run this again.");
+    }
+    if (/PERMISSION_DENIED|does not have permission|Permission.*denied/.test(output)) {
+      throw new UserError(
+        `Your account is not allowed to do that in this project.\n\n${output.split("\n").slice(0, 4).join("\n")}`,
+      );
+    }
+    const detail = output.split("\n").slice(0, 6).join("\n");
+    throw new UserError(`${command} ${args[0] ?? ""} failed:\n${detail}`);
+  }
+  return result.stdout.trim();
+}
+
+export function requireCommand(name, why) {
+  const found = spawnSync(process.platform === "win32" ? "where" : "which", [name], { encoding: "utf8" });
+  if (found.status !== 0) {
+    throw new UserError(`${name} is required — ${why}`);
+  }
+}
+
+/** The gcloud prefix every call shares: the deployment's project, and its account if pinned. */
+export function gcloudArgs(deployment, args) {
+  const prefix = [`--project=${deployment.PROJECT}`];
+  if (deployment.ACCOUNT) {
+    prefix.push(`--account=${deployment.ACCOUNT}`);
+  }
+  return [...args, ...prefix];
+}
+
+export function serviceUrl(deployment) {
+  return capture(
+    "gcloud",
+    gcloudArgs(deployment, [
+      "run",
+      "services",
+      "describe",
+      deployment.SERVICE,
+      `--region=${deployment.REGION}`,
+      "--format=value(status.url)",
+    ]),
+  );
+}
+
+/**
+ * The deployment's webhook 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.
+ */
+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",
+    );
+  }
+}
+
+/** 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)}` };
+  if (accept) {
+    headers.Accept = accept;
+  }
+  if (body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+  const res = await fetch(url, {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new UserError(`${method} ${path} → ${res.status}\n${text.slice(0, 400)}`);
+  }
+  return text;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@meffecta/agent",
+  "version": "0.0.1",
+  "description": "Set up and operate a Meffecta Agent deployment \u2014 a self-hosted Claude Code job runner.",
+  "type": "module",
+  "bin": {
+    "meffecta-agent": "bin/meffecta-agent.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "engine.json",
+    "IMPLEMENTATION.md",
+    "ARCHITECTURE.md",
+    "deployment.env.example",
+    "README.md"
+  ],
+  "keywords": [
+    "meffecta",
+    "agent",
+    "claude",
+    "cloud-run",
+    "automation"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meffecta/agent.git",
+    "directory": "cli"
+  },
+  "scripts": {
+    "prepack": "node prepack.mjs"
+  }
+}