@meffecta/agent 1.0.0 → 1.0.1

package/README.md

@@ -29,9 +29,18 @@ npx @meffecta/agent deploy                # roll out the engine
 npx @meffecta/agent setup-scheduler       # give it its triggers
 ```
 
+Giving it access to something — Gmail, GA4, Grafana, PostHog, Cloudflare, an inbox
+trigger — is ongoing work rather than set-up, and each has a walkthrough:
+
+```bash
+npx @meffecta/agent connect              # what can be connected
+npx @meffecta/agent connect gmail        # what to do, in order, with the commands
+```
+
 Then, day to day:
 
 ```bash
+npx @meffecta/agent doctor                # is anything quietly broken?
 npx @meffecta/agent status                # revision, shape, triggers, queue
 npx @meffecta/agent jobs                  # what is registered, and what triggers it
 npx @meffecta/agent env                   # every setting (secret values never printed)
@@ -42,6 +51,15 @@ npx @meffecta/agent run morning-brief
 npx @meffecta/agent ask "how did search do last week"
 ```
 
+`doctor` is the one to run when something feels wrong. It judges rather than describes,
+and it is aimed at the failures that produce no error anywhere: a scaled-to-zero service
+with no triggers runs nothing while looking perfectly healthy, an always-on one with
+triggers runs every cron twice, a sweep whose cadence no longer matches the inbox poll
+interval checks mail on yesterday's schedule for ever, and a registry that expired the
+image your revision pins will fail at the next cold start rather than the next deploy.
+Every finding carries the command that fixes it, and it exits non-zero on a real problem
+so CI can run it.
+
 ## Two things worth knowing
 
 **The version you install is the engine you deploy.** Each release records the engine build
@@ -55,10 +73,22 @@ value from a pipe, a file, or a hidden prompt — never from your shell history.
 
 ## Requirements
 
-`gcloud` (authenticated), `docker` (to mirror engine images into your registry), `git`,
-and Node 20+. macOS or Linux.
+`gcloud` (authenticated), `docker` (to mirror engine images into your registry), `git`, and
+Node 20+ — Node 24+ if you also run the `claude` CLI to mint the token. macOS or Linux.
+
+## Developing it
+
+From a checkout of the engine repo:
+
+```bash
+cd cli && npm link      # `meffecta-agent` now runs the working tree
+```
+
+The scripts and docs are vendored into this package only at pack time, so a linked
+checkout falls back to the engine repo's own copies — edit either half and the next command
+picks it up. `npm rm -g @meffecta/agent` undoes it.
 
 ## Documentation
 
-`IMPLEMENTATION.md` and `ARCHITECTURE.md` ship inside this package — the full set-up, and
-how the pieces fit.
+`npx @meffecta/agent help` lists every command; `npx @meffecta/agent steps` is the whole
+set-up in order, with the command for each step. Every command takes `--help`.

package/bin/meffecta-agent.js

@@ -14,18 +14,32 @@ import { loadDeployment, UserError } from "../lib/config.js";
  * a tool that holds someone's cloud credentials is a poor place for a supply chain.
  */
 
+// Tools first: every command below needs gcloud, and the very first one already does. The
+// claude CLI is the odd one out — it is used once, to mint the token, and never again.
 const STEPS = [
-  ["create-project", "A new GCP project."],
+  [
+    "",
+    "Install gcloud, docker, node 24+ and git. Also the claude CLI — it is\n    used once, for the token two steps down, and not after that.",
+  ],
+  [
+    "create-project",
+    "A new GCP project. This and the next step are per GCP account, not\n    per deployment — skip both if you are adding a second agent to a project you\n    already have.",
+  ],
   ["link-billing", "Attach a billing account, or nothing can run."],
-  ["", "Create your content repo — jobs/, worlds/, SYSTEM.md, deployment.env."],
-  ["", "Install gcloud, docker, git, node 24+, and the claude CLI."],
-  ["mint-gmail", "Credentials: claude setup-token, then a token per mail account."],
+  [
+    "mint-gmail",
+    "Credentials: `claude setup-token`, a GitHub token that can clone your repos,\n    and — only if this agent reads or sends mail — one token per mailbox.",
+  ],
+  [
+    "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.",
+  ],
   ["setup-infra", "Provision GCP and the Cloud Run service shell."],
   ["set-secret", "AGENT_WEBHOOK_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."],
-  ["status", 'Check it. Then: jobs, run <job>, ask "…".'],
+  ["doctor", 'Check it. Then: jobs, run <job>, ask "…".'],
 ];
 
 function help() {
@@ -40,6 +54,9 @@ function help() {
     for (const [name, summary] of group.commands) {
       console.log(`  ${name.padEnd(width)}  ${summary}`);
     }
+    for (const line of group.note ?? []) {
+      console.log(`  ${line}`);
+    }
     console.log("");
   }
   console.log("  steps                 The whole set-up, in order, with the command for each");
@@ -50,7 +67,7 @@ function help() {
 }
 
 function steps() {
-  console.log("Setting up a deployment, in order. The full text is IMPLEMENTATION.md.\n");
+  console.log("Setting up a deployment, in order.\n");
   STEPS.forEach(([command, note], index) => {
     const label = `${String(index + 1).padStart(2)}.`;
     console.log(`${label} ${note}`);
@@ -59,8 +76,8 @@ function steps() {
     }
     console.log("");
   });
-  console.log("Each step is checkable: `meffecta-agent status` after the last one should show");
-  console.log("your triggers, and `meffecta-agent jobs` your jobs.");
+  console.log("Each step is checkable: `meffecta-agent doctor` after the last one should come");
+  console.log("back clean, and `meffecta-agent jobs` should list your jobs.");
 }
 
 function version() {
@@ -107,6 +124,7 @@ try {
   if (name === "deploy" && !args.includes("--tag") && !args.includes("--image")) {
     const { tag, pinned } = engineTag();
     if (pinned) {
+      console.log(`Engine ${tag}, the build this CLI was released with. --tag overrides it.\n`);
       args.push("--tag", tag);
     }
   }

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.0",
-  "builtFrom": "9bffef350f00af96654b7b9f97f2cb075b70bbad"
+  "engineTag": "1.0.1",
+  "builtFrom": "e86fcdf452f5403ce1c90805c904048dacc0c6ae"
 }

package/lib/commands.js

@@ -2,7 +2,10 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { requireDeployment, UserError } from "./config.js";
+import { runDoctor } from "./doctor.js";
+import { parseFlags } from "./flags.js";
 import { api, requireCommand, stream } from "./gcloud.js";
+import { connect } from "./integrations.js";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -28,8 +31,15 @@ export function engineTag() {
     return { tag: "latest", pinned: false };
   }
   try {
-    const { engineTag: tag } = JSON.parse(readFileSync(file, "utf8"));
-    return tag ? { tag, pinned: true } : { tag: "latest", pinned: false };
+    const { engineTag: tag, builtFrom } = JSON.parse(readFileSync(file, "utf8"));
+    // Only a release is pinned. `npm pack` run by hand writes this file into the working
+    // tree with builtFrom "local", where it would otherwise survive and pin `deploy` to a
+    // version that was never published — the image is not there and the mirror fails with
+    // nothing to say why that tag was chosen.
+    if (!tag || builtFrom === "local" || existsSync(resolve(packageRoot, "..", "src", "index.ts"))) {
+      return { tag: "latest", pinned: false };
+    }
+    return { tag, pinned: true };
   } catch {
     return { tag: "latest", pinned: false };
   }
@@ -137,11 +147,20 @@ async function status() {
   return 0;
 }
 
+/**
+ * What the *service* has registered — not the files here, and not Cloud Scheduler.
+ *
+ * The engine reads jobs/ from a clone taken at its boot, so this is the boot-time picture.
+ * A job pushed since is not in it until the service restarts, and a Cloud Scheduler trigger
+ * can outlive the job that created it. `doctor` compares all three and is the place to look
+ * when they disagree.
+ */
 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.");
+    console.log("No jobs registered. The content repo's jobs/ directory is empty, GIT_REPO_URL is");
+    console.log("wrong, or GITHUB_TOKEN cannot clone it.");
     return 0;
   }
   const width = Math.max(...list.map((j) => j.name.length));
@@ -149,22 +168,27 @@ async function jobs() {
     const triggers = [
       job.cron && `cron ${job.cron}`,
       job.webhook && `webhook /${job.webhook}`,
-      job.inbox && `inbox ${job.inbox}`,
+      job.inbox && `inbox ${job.inbox} (from ${job.allowFrom ?? "NOBODY — no allowFrom:"})`,
     ]
       .filter(Boolean)
       .join(", ");
     console.log(`${job.name.padEnd(width)}  ${triggers || "manual only"}${job.disabled ? "   [disabled]" : ""}`);
   }
+  console.log(
+    `\n${list.length} registered by ${d.SERVICE}, from the content repo as it stood at that service's` +
+      "\nlast boot — not the files here. `meffecta-agent doctor` checks them against both.",
+  );
   return 0;
 }
 
 async function runJob(args) {
-  const name = args[0];
+  const { flags, positional } = parseFlags(args, { in: { type: "int", min: 1, max: 3600 } });
+  const name = positional[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 delay = flags.in ?? 0;
   const query = delay > 0 ? `?delaySeconds=${delay}` : "";
   const body = JSON.parse(await api(d, `/jobs/${encodeURIComponent(name)}/run${query}`, { method: "POST" }));
   console.log(
@@ -176,18 +200,22 @@ async function runJob(args) {
 }
 
 async function ask(args) {
-  const prompt = args.filter((a) => !a.startsWith("--")).join(" ");
+  // model and effort are deliberately not validated here. The engine owns that list, this
+  // CLI may be deploying an engine older or newer than itself, and /test already answers
+  // with the valid values — so the authority stays in one place and the error stays good.
+  const { flags, positional } = parseFlags(args, {
+    model: {},
+    effort: {},
+    timeoutSeconds: { type: "int", min: 1, max: 3600 },
+  });
+  const prompt = positional.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);
-    }
+  for (const [name, value] of Object.entries(flags)) {
+    params.set(name, String(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" }));
@@ -321,8 +349,9 @@ async function triggers() {
 /** Recent service logs, without making anyone remember the filter syntax. */
 async function logs(args) {
   requireCommand("gcloud", "logs come from Cloud Logging");
+  const { flags } = parseFlags(args, { limit: { type: "int", min: 1, max: 1000 } });
   const d = requireDeployment();
-  const limit = args.includes("--limit") ? args[args.indexOf("--limit") + 1] : "40";
+  const limit = String(flags.limit ?? 40);
   const { code } = await stream("gcloud", [
     "logging",
     "read",
@@ -360,28 +389,58 @@ async function init(args) {
 
 export const GROUPS = [
   {
-    title: "Set up a deployment, in order",
+    // The only two commands that run before a deployment exists: no deployment.env, nothing
+    // to stand in, and once done you never touch them again. Everything in the next group
+    // acts on *a* deployment and reads deployment.env to know which one you mean.
+    title: "Before you have a deployment (once per GCP account)",
+    commands: [
+      ["create-project", "Create the GCP project a deployment will live in", script("create-project.sh")],
+      ["link-billing", "Attach a billing account — nothing runs without one", script("link-billing.sh")],
+    ],
+  },
+  {
+    // The shortest path to a running agent, and nothing else. Three secrets and one
+    // setting are all the engine actually needs to boot; everything optional lives in the
+    // next group so a first deployment is not a shopping list.
+    title: "Stand one up (once, 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")],
+      ["set-secret", "AGENT_WEBHOOK_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")],
+    ],
+  },
+  {
+    // What an agent can do is credentials plus jobs, and both are added for as long as the
+    // deployment lives. Worth its own group so it does not read like set-up you skipped.
+    title: "Give it more to do (any time after)",
+    commands: [
+      ["connect", "How to wire up gmail, ga4, grafana, posthog … — `connect` lists them", connect],
+      [
+        "mint-gmail",
+        "A Gmail/Calendar refresh token, per account it should read or send as",
+        script("mint-gmail-token.mjs"),
+      ],
+      ["mint-graph", "A Microsoft Graph refresh token, per mailbox", script("mint-graph-token.mjs")],
       ["artifact-cleanup", "Expire mirrored images in the deployment's registry", script("set-artifact-cleanup.sh")],
     ],
+    note: [
+      "A new credential is `set-secret` again, plus `set-env` for whatever names the",
+      "project it points at. A new job is a push to your content repo — there is no",
+      "command for it, and its prompt is live on the next run. Only its *trigger* needs",
+      "`deploy`, which restarts the service so the new cron: is registered.",
+    ],
   },
   {
     title: "Look at what is there",
     commands: [
+      ["doctor", "Check the deployment for the things that silently break it", runDoctor],
       ["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],