@meffecta/agent 1.0.0 → 1.0.1

package/lib/integrations.js

@@ -0,0 +1,212 @@
+import { UserError } from "./config.js";
+
+/**
+ * How to give the agent one more thing it can reach.
+ *
+ * Every integration is the same three moves in a different order — get a credential, tell
+ * the deployment about it, point it at a specific account — and the differences between
+ * them are exactly the parts people get stuck on: which console page, which scope, whether
+ * the runtime service account needs inviting somewhere. That is what these walk through.
+ *
+ * Nothing here acts. It prints what to do, in the order to do it, with the commands.
+ */
+
+const INTEGRATIONS = {
+  gmail: {
+    title: "Gmail and Google Calendar",
+    gives: "send-email, query-gmail and google-calendar — reading mail, sending it, booking time",
+    needs: [
+      "An OAuth client in this GCP project: APIs & Services → OAuth consent screen (External,",
+      "and PUBLISH it, or tokens expire after 7 days), then Credentials → Create → OAuth",
+      "client ID → Desktop app. Enable the Gmail and Calendar APIs while you are there.",
+    ],
+    steps: [
+      ["meffecta-agent set-secret GMAIL_CLIENT_ID", "from the OAuth client you just made"],
+      ["meffecta-agent set-secret GMAIL_CLIENT_SECRET", ""],
+      [
+        "meffecta-agent mint-gmail --client-id <id> --client-secret <secret>",
+        "sign in as the account it should act as",
+      ],
+      ["meffecta-agent set-secret GMAIL_REFRESH_TOKEN", "paste what mint-gmail printed"],
+      ["meffecta-agent set-env GMAIL_ADDRESS=agent@yourdomain.com", "which mailbox that token is"],
+    ],
+    more: [
+      "A second account follows the GMAIL_<NAME>_* convention — GMAIL_SALES_REFRESH_TOKEN and",
+      "GMAIL_SALES_ADDRESS — minted with `mint-gmail --account SALES`, and a job reaches it",
+      "with `--account SALES`. Add `--readonly` when minting an account that should never send.",
+    ],
+  },
+
+  outlook: {
+    title: "Microsoft 365 mail and calendar",
+    gives: "query-outlook — reading a mailbox in someone else's tenant. Read-only by design; it cannot send",
+    needs: [
+      "An app registration in that tenant's Entra ID: delegated Microsoft Graph permissions",
+      "Mail.Read, Calendars.Read and offline_access, with admin consent granted.",
+    ],
+    steps: [
+      ["meffecta-agent set-secret MSGRAPH_CLIENT_ID", "the application (client) ID"],
+      ["meffecta-agent set-secret MSGRAPH_CLIENT_SECRET", ""],
+      ["meffecta-agent set-env MSGRAPH_TENANT_ID=<tenant>", ""],
+      ["meffecta-agent mint-graph --account WORK", "sign in as the mailbox owner"],
+      ["meffecta-agent set-secret MSGRAPH_WORK_REFRESH_TOKEN", "paste what mint-graph printed"],
+      ["meffecta-agent set-env MSGRAPH_WORK_ADDRESS=you@company.com", ""],
+    ],
+    more: [
+      "Every mailbox reachable this way belongs to another organisation. Name the account in",
+      "the job that may read it, and nowhere else — that is the whole boundary.",
+    ],
+  },
+
+  ga4: {
+    title: "Google Analytics 4, Search Console and Google Ads",
+    gives: "query-google-marketing — traffic, the queries that bring it, campaign spend",
+    needs: [
+      "No token at all: these authenticate as the runtime service account, which means",
+      "inviting it rather than minting anything. `meffecta-agent status` prints its address,",
+      "or look for agent-runtime@<project>.iam.gserviceaccount.com.",
+      "",
+      "Invite it as a Viewer on each property you want read: the GA4 property (Admin →",
+      "Property access management), the Search Console property (Settings → Users and",
+      "permissions), and the Google Ads account (Tools → Access and security).",
+    ],
+    steps: [
+      ["meffecta-agent set-env ACME_GA4_PROPERTY_ID=123456789", "digits only, from GA4 Admin → Property details"],
+      [
+        "meffecta-agent set-env ACME_SEARCH_CONSOLE_PROPERTY=sc-domain:acme.com",
+        "a domain property is sc-domain: plus the bare domain",
+      ],
+      ["meffecta-agent set-env ACME_GOOGLE_ADS_CUSTOMER_ID=1234567890", "digits only, no dashes"],
+      ["meffecta-agent set-secret GOOGLE_ADS_DEVELOPER_TOKEN", "Ads only — from the manager account's API Center"],
+    ],
+    more: [
+      "The ACME_ prefix is yours: name it after the project, and have that world's file in",
+      "the content repo tell jobs which selector to use. One deployment can carry several.",
+      "",
+      "These only work on Cloud Run, where the metadata server can vouch for the service",
+      "account. Off Cloud Run the skill reports itself unavailable and the job goes on.",
+    ],
+  },
+
+  grafana: {
+    title: "Grafana Cloud logs",
+    gives: "query-grafana — the server logs behind an incident, traced by id",
+    needs: ["A Grafana Cloud access policy token with the logs:read scope."],
+    steps: [
+      ["meffecta-agent set-env GRAFANA_LOGS_HOST=https://logs-prod-XXX.grafana.net", ""],
+      ["meffecta-agent set-env GRAFANA_LOGS_USERNAME=123456", "the numeric Loki user id, not an email"],
+      ["meffecta-agent set-secret GRAFANA_API_KEY", ""],
+    ],
+    more: [
+      "Which services exist and what their logs contain is a fact about your product, not",
+      "about the credential — put it in the world file your jobs name.",
+    ],
+  },
+
+  posthog: {
+    title: "PostHog product analytics",
+    gives: "query-posthog — who did what in the app, funnels, adoption",
+    needs: ["A PostHog personal API key with project read access."],
+    steps: [
+      ["meffecta-agent set-secret POSTHOG_API_KEY", ""],
+      ["meffecta-agent set-env POSTHOG_HOST=https://eu.posthog.com", "or the US host"],
+      ["meffecta-agent set-env ACME_POSTHOG_PROJECT_ID=12345", "one per project the agent watches"],
+    ],
+  },
+
+  cloudflare: {
+    title: "Cloudflare",
+    gives: "cloudflare — DNS, cache purge, Pages deployments, certificate checks",
+    needs: ["An API token scoped to the zones it should touch. Read-only unless a job explicitly changes DNS."],
+    steps: [
+      ["meffecta-agent set-secret CLOUDFLARE_API_KEY", "an API *token*, despite the name — sent as a Bearer header"],
+      ["meffecta-agent set-env CLOUDFLARE_ACCOUNT_ID=<id>", ""],
+    ],
+  },
+
+  inbox: {
+    title: "Triggering a job from incoming mail",
+    gives: "a job that wakes on new mail to an address, rather than on a clock",
+    needs: [
+      "A mailbox the agent can read. Either a Workspace mailbox via domain-wide delegation",
+      "(keyless, Cloud Run only), or any Gmail account you have already connected — see",
+      "`meffecta-agent connect gmail` first if you have not.",
+    ],
+    steps: [
+      [
+        "meffecta-agent set-env AGENT_INBOX_MAILBOX=inbox@yourdomain.com",
+        "the delegated mailbox — omit for the OAuth path",
+      ],
+      ["meffecta-agent set-env AGENT_INBOX_ACCOUNT=SALES", "OAuth path only: which GMAIL_<NAME>_* account to read"],
+      ["meffecta-agent set-env AGENT_INBOX_POLL_SECONDS=300", "how often; the sweep inherits this cadence"],
+      ["meffecta-agent setup-scheduler", "re-syncs the sweep to that interval"],
+    ],
+    more: [
+      "Then, in the job's frontmatter:",
+      "",
+      "    inbox: crm@yourdomain.com",
+      "    allowFrom: you@yourdomain.com, @yourdomain.com",
+      "",
+      "and `deploy` to register it — both fields are read when the service boots.",
+      "",
+      "allowFrom is required and enforced in code: mail from anyone not listed is dropped",
+      "before the run starts, so it never reaches the model. Leave it out and the job",
+      "refuses every message — an omission is not read as consent.",
+      "",
+      "  marcus@acme.com   one address        @acme.com    that domain (or *@acme.com)",
+      "  *@*.acme.com      any subdomain      *            anyone at all",
+      "",
+      "A subdomain rule does not cover the bare domain; list both if you want both.",
+    ],
+  },
+};
+
+export function listIntegrations() {
+  const width = Math.max(...Object.keys(INTEGRATIONS).map((k) => k.length));
+  console.log("Things the agent can be given access to. Each prints what to do, in order:\n");
+  for (const [name, entry] of Object.entries(INTEGRATIONS)) {
+    console.log(`  ${name.padEnd(width)}  ${entry.title}`);
+  }
+  console.log("\n  meffecta-agent connect <name>\n");
+  console.log("Every one of them is optional, and skipping one costs only the jobs that needed");
+  console.log("it: a skill whose settings are unset reports itself unavailable and the run goes on.");
+  return 0;
+}
+
+export function connect(args) {
+  const name = args[0];
+  if (!name) {
+    return listIntegrations();
+  }
+  const entry = INTEGRATIONS[name];
+  if (!entry) {
+    throw new UserError(`No walkthrough for "${name}".\nAvailable: ${Object.keys(INTEGRATIONS).join(", ")}`);
+  }
+
+  console.log(`${entry.title}\n`);
+  console.log(`Gives the agent: ${entry.gives}\n`);
+  if (entry.needs) {
+    console.log("Before you start:");
+    for (const line of entry.needs) {
+      console.log(line ? `  ${line}` : "");
+    }
+    console.log("");
+  }
+  console.log("Then, from your content repo:\n");
+  for (const [command, why] of entry.steps) {
+    console.log(`  ${command}`);
+    if (why) {
+      console.log(`      ${why}`);
+    }
+  }
+  console.log("");
+  if (entry.more) {
+    for (const line of entry.more) {
+      console.log(line ? `  ${line}` : "");
+    }
+    console.log("");
+  }
+  console.log("Check it landed:  meffecta-agent verify-credentials");
+  console.log("Nothing was changed by this command.");
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meffecta/agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {
@@ -12,10 +12,10 @@
   "files": [
     "bin",
     "lib",
+    "!lib/*.test.mjs",
     "scripts",
+    "!scripts/**/*.test.mjs",
     "engine.json",
-    "IMPLEMENTATION.md",
-    "ARCHITECTURE.md",
     "deployment.env.example",
     "README.md"
   ],

package/scripts/lib/read-json.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Pull single values out of the JSON that setup-scheduler.sh reads from gcloud and from the
+// running service. Shell cannot parse JSON and node is already required by the operator
+// tooling (mint-gmail-token.mjs, verify-credentials.mjs), so this replaces what used to be
+// inline python3 — one fewer thing a deployment has to have installed.
+//
+// Reads the document on stdin. Output is plain text, tab-separated where a caller needs
+// more than one value, so the shell can read it with `IFS=$'\t' read`.
+//
+//   node read-json.mjs service url|sa|scaling|<ENV_NAME>
+//   node read-json.mjs crons            # name<TAB>cron, one job per line
+//   node read-json.mjs watches-inbox    # yes | no
+import { readFileSync } from "node:fs";
+
+const [mode, argument] = process.argv.slice(2);
+const document = JSON.parse(readFileSync(0, "utf8"));
+
+function service(what) {
+  const template = document.spec.template;
+  const spec = template.spec;
+  const env = new Map((spec.containers[0].env ?? []).map((entry) => [entry.name, entry]));
+  const annotations = template.metadata.annotations ?? {};
+
+  if (what === "url") {
+    // An explicitly configured public URL wins over the one Cloud Run reports, so a
+    // deployment behind its own domain keeps addressing itself the way it was told to.
+    return env.get("AGENT_PUBLIC_URL")?.value || document.status.url;
+  }
+  if (what === "sa") {
+    return spec.serviceAccountName ?? "";
+  }
+  if (what === "scaling") {
+    return [
+      annotations["autoscaling.knative.dev/minScale"] ?? "0",
+      annotations["run.googleapis.com/cpu-throttling"] ?? "true",
+    ].join("\t");
+  }
+  // Any other name is an env var: either a plain value or a Secret Manager reference. The
+  // caller is told which, because a secret has to be fetched before it can be used.
+  const entry = env.get(what) ?? {};
+  if (entry.value) {
+    return `value\t${entry.value}`;
+  }
+  const ref = entry.valueFrom?.secretKeyRef ?? {};
+  return `secret\t${ref.name ?? ""}\t${ref.key || "latest"}`;
+}
+
+const modes = {
+  service: () => service(argument),
+  // A disabled job keeps its trigger: whether it runs is re-read from the content repo per
+  // run, which is what makes `disabled: true` push-effective rather than a redeploy.
+  crons: () =>
+    document
+      .filter((job) => job.cron)
+      .map((job) => `${job.name}\t${job.cron}`)
+      .join("\n"),
+  "watches-inbox": () => (document.some((job) => job.inbox) ? "yes" : "no"),
+};
+
+const run = modes[mode];
+if (!run) {
+  process.stderr.write(`read-json.mjs: unknown mode "${mode}"\n`);
+  process.exit(2);
+}
+const output = run();
+if (output !== "") {
+  process.stdout.write(`${output}\n`);
+}

package/scripts/setup-scheduler.sh

@@ -53,7 +53,7 @@ while [ $# -gt 0 ]; do
 done
 
 require_gcloud
-command -v python3 >/dev/null || { echo "python3 is required." >&2; exit 1; }
+command -v node >/dev/null || { echo "node is required (24+)." >&2; exit 1; }
 resolve_deployment
 announce_target "Wiring external triggers for ${SERVICE}"
 
@@ -104,29 +104,10 @@ SERVICE_JSON=$(${GC} run services describe "${SERVICE}" --region="${REGION}" --f
   exit 1
 }
 
+READ_JSON="$(dirname "${BASH_SOURCE[0]}")/lib/read-json.mjs"
+
 svc_field() {
-  python3 -c "
-import json, sys
-svc = json.loads(sys.stdin.read())
-spec = svc['spec']['template']['spec']
-env = {e['name']: e for e in spec['containers'][0].get('env', [])}
-what = sys.argv[1]
-if what == 'url':
-    print((env.get('AGENT_PUBLIC_URL', {}).get('value')) or svc['status']['url'])
-elif what == 'sa':
-    print(spec.get('serviceAccountName') or '')
-elif what == 'scaling':
-    ann = svc['spec']['template']['metadata'].get('annotations', {})
-    print('{}\t{}'.format(ann.get('autoscaling.knative.dev/minScale', '0'),
-                          ann.get('run.googleapis.com/cpu-throttling', 'true')))
-else:
-    e = env.get(what, {})
-    if e.get('value'):
-        print('value\t' + e['value'])
-    else:
-        ref = e.get('valueFrom', {}).get('secretKeyRef', {})
-        print('secret\t{}\t{}'.format(ref.get('name', ''), ref.get('key') or 'latest'))
-" "$1"
+  node "${READ_JSON}" service "$1"
 }
 
 AGENT_URL=$(printf '%s' "${SERVICE_JSON}" | svc_field url)
@@ -209,16 +190,8 @@ EOF
 # name<TAB>cron for every job that declares one. A disabled job keeps its trigger: whether
 # it runs is re-read from the content repo per run, which is what makes `disabled: true`
 # push-effective rather than a redeploy.
-CRON_JOBS=$(printf '%s' "${JOBS_JSON}" | python3 -c "
-import json, sys
-for job in json.load(sys.stdin):
-    if job.get('cron'):
-        print('{}\t{}'.format(job['name'], job['cron']))
-")
-WATCHES_INBOX=$(printf '%s' "${JOBS_JSON}" | python3 -c "
-import json, sys
-print('yes' if any(j.get('inbox') for j in json.load(sys.stdin)) else 'no')
-")
+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}"
 

package/scripts/update-tooling.sh

@@ -3,10 +3,11 @@ set -euo pipefail
 
 # Refresh this deployment's operator tooling from a published engine image.
 #
-# The engine's source repo is private; the image is not. Everything an operator needs —
-# these scripts, the set-up guide, the config template — ships inside
-# ghcr.io/meffecta/agent, so a deployment run by someone outside Meffecta gets its tooling
-# from the same public artifact it gets its engine from, and never needs the source.
+# The engine's source repo is private; the image is not. The operator tooling — these
+# scripts and the config template — ships inside ghcr.io/meffecta/agent, so a deployment run
+# by someone outside Meffecta gets its tooling from the same public artifact it gets its
+# engine from, and never needs the source. What a deployment is documented by is the CLI's
+# own help: `meffecta-agent help` and `meffecta-agent steps`.
 #
 # The tooling belongs in your content repo, committed next to jobs/ and deployment.env.
 # That is what makes a fresh clone of that repo enough to operate the deployment, and it
@@ -71,7 +72,7 @@ docker pull --quiet --platform linux/amd64 "${IMAGE}" >/dev/null || {
 CID="$(docker create --platform linux/amd64 "${IMAGE}")"
 # `docker cp` copies out as the host user, so nothing depends on the uid inside the image.
 docker cp "${CID}:/app/scripts" "${TMP}/scripts" >/dev/null
-for doc in IMPLEMENTATION.md ARCHITECTURE.md deployment.env.example; do
+for doc in deployment.env.example; do
   docker cp "${CID}:/app/${doc}" "${TMP}/scripts/${doc}" >/dev/null 2>&1 || true
 done
 docker rm "${CID}" >/dev/null

package/ARCHITECTURE.md

@@ -1,197 +0,0 @@
-# How the agent is put together
-
-Orientation for someone about to run a deployment. The set-up steps themselves are in
-[IMPLEMENTATION.md](IMPLEMENTATION.md); this is what those steps are building and why.
-
-## The shape
-
-```
-  this engine repo  ──CI──▶  ghcr.io/meffecta/agent   (the image; never company-specific)
-                                      │
-                                      │  scripts/deploy.sh
-                                      ▼
-   your content repo  ──cloned every run──▶  Cloud Run service   (your project, your creds)
-   jobs/ worlds/ SYSTEM.md                    ↑
-                                              └─ credentials in Secret Manager
-```
-
-The engine is a job runner: it wakes on a schedule (or a webhook, or new mail), clones the
-content repo, and hands one job's prompt to the `claude` CLI with a working directory, a
-system prompt, a set of skills and a memory directory. What the agent *does* is entirely
-in the content repo and the credentials; the engine knows nothing about any company.
-
-## Two rules that explain most of the design
-
-**The engine is generic; the content repo is yours.** Every run re-clones the content repo,
-so a pushed prompt is live on the next run — no build, no deploy. Only moving to a new
-*engine version* is a deploy. This is also why the engine repo's CI publishes an image and
-stops: when a deployment takes a new version is that deployment's call.
-
-**The agent's power is exactly its credentials.** There is no other lever. Give it a GCP
-project of its own, and add one credential at a time — every skill degrades gracefully
-when its variables are unset, so a half-configured agent is a working agent with fewer
-abilities, not a broken one. Reviewing what an agent can do means reviewing what its
-service account is invited to and what tokens sit in its Secret Manager.
-
-## What needs what
-
-| Change | Effect |
-| --- | --- |
-| Job prompts, run settings, `SYSTEM.md`, worlds, content-repo skills | **Push** — live on the next run |
-| Adding, renaming, or retriggering a job (`cron`/`webhook`/`inbox` frontmatter) | **Restart** — triggers register from a boot-time clone, plus `scripts/setup-scheduler.sh` on Cloud Run |
-| A new engine version | `scripts/deploy.sh` (which re-syncs the triggers too) |
-
-Renaming a job also moves its identity: memory lives at `<MEMORY_DIR>/jobs/<name>/`, so
-copy that directory across or the job wakes up amnesiac, and pending spawns for the old
-name die with it.
-
-## Operating a deployment
-
-Operating a deployment is one command-line tool, **`npx @meffecta/agent`**, published to
-npm alongside the engine image it deploys. Installing it is all the access an operator
-needs; the engine's source is not involved. Each release of the tool records the engine
-build it was published with, so upgrading the tool is how you move to a new engine —
-deliberately, rather than by surprise.
-
-It reads this deployment's identity from a `deployment.env` in your content repo, committed
-beside `jobs/`. Which GCP project a set of jobs runs as is a fact about that deployment,
-and none of it is secret.
-
-That makes the working shape: stand in the content repo and run the tool.
-
-```bash
-cd /path/to/acme-agent-home
-npx @meffecta/agent status
-npx @meffecta/agent deploy
-```
-
-Nothing is read from exported shell variables, so a command cannot silently act on the
-wrong deployment; each script prints the project and service it is about to touch, and
-refuses to run when it cannot find them (`--config <file>` overrides the lookup).
-
-`deployment.env` also holds the **runtime shape** — `SCALING`, `CPU`, `MEMORY`,
-`MAX_INSTANCES`, `REQUEST_TIMEOUT` — which `deploy.sh` re-asserts on every rollout. So the
-file, not the console, is the truth about how the service runs, and `SCALING` in particular
-has to stay honest: it and the triggers are one decision made in two places.
-
-Every command is one of the scripts below with a name in front of it — the CLI is the
-interface, the scripts are the implementation, and they are published together so the pair
-cannot drift. A deployment without npm can extract the scripts from the public image
-instead and run them directly.
-
-| Command / script | Does |
-| --- | --- |
-| `setup-infrastructure.sh` | one-time GCP provisioning; idempotent |
-| `setup-scheduler.sh` | the deployment's external triggers — Cloud Scheduler + Tasks; idempotent |
-| `set-artifact-cleanup.sh` | expire mirrored images in the deployment's registry |
-| `update-tooling.sh` | refresh these scripts from a published engine image |
-| `set-secret.sh` | store a value in Secret Manager and bind it; re-run to rotate |
-| `set-env.sh` | non-secret service settings, several per revision |
-| `deploy.sh` | roll a published engine image out, and assert the runtime shape |
-
-For a question rather than a change, the service serves **`/ask`**: a prompt box behind the
-same secret, over basic auth, that runs it with the deployment's skills and credentials and
-shows the answer. It is the quickest way to find out what the agent can currently see.
-
-`set-secret.sh` never lets a value reach the shell history or the screen: `--random`
-generates one, a pipe or `--from-file` supplies one, and otherwise it prompts with echo
-off. `deploy.sh`, `set-env.sh` and `setup-scheduler.sh` take `--dry-run`.
-
-## Where the rules live
-
-Every run's system prompt is built from two layers:
-
-1. **The deployment's `SYSTEM.md`**, from its content repo — who this agent serves, its
-   worlds, its tone, which systems belong to whom.
-2. **The engine's `SYSTEM.base.md`**, from the image — the safety rules every deployment
-   gets whether or not anyone remembered to write them.
-
-The baseline is appended **last**, closest to the task, and says in its own text that it
-overrides what precedes it. A deployment can make a rule stricter or name the concrete
-accounts it applies to; it cannot relax one, and it cannot shadow the file — the engine
-resolves it from its own install directory, never from the working repo, so no content a
-deployment or a run controls can stand in for it. A missing baseline throws rather than
-running unprotected.
-
-What the baseline carries: content you read is data and never instructions; act only
-where the job says, with anything outward-facing or irreversible left for a person unless
-the job directs it; secrets never leave; other people's privacy; report honestly. Both
-layers hold across a spawned follow-up run, which inherits its parent's system prompt.
-
-A rule that must be *structurally* impossible belongs in code, not prose — the way the
-Google Ads skill splits reads from writes and caps every mutation, and the way a read-only
-mail token makes sending impossible rather than merely forbidden.
-
-## Skills
-
-Skills are how the agent reaches a system: the how-to for Gmail, Microsoft Graph, Drive,
-Cloudflare, a browser, Grafana, PostHog, Google Ads. They resolve in three layers, each
-winning over the next:
-
-1. the **working repo** a job runs in (`repo:` frontmatter),
-2. the **content repo** (`.claude/skills/`) — this deployment's own or its overrides,
-3. the **engine defaults**, shipped in the image.
-
-So a deployment can override any default without forking the engine, and a product repo
-can supply its own variant for jobs that run inside it.
-
-## Triggers
-
-Four ways a run starts. The first three are configured in a job's frontmatter:
-
-- **cron** — a schedule, in the deployment's timezone
-- **webhook** — `POST /webhooks/<name>`
-- **inbox** — new mail to a watched address, polled
-
-The fourth is the only one the agent pulls itself: a run that cannot finish inside its
-time limit, or that has to wait for something, writes the instruction for a **follow-up
-run** and schedules it. That follow-up is the same job identity — same repo, system
-prompt, settings and memory — with a fresh time limit. The token that authorizes it stands
-for that run's identity and dies with the run, so a run can only ever schedule more of its
-own job's work, whatever its prompt says.
-
-### What actually wakes the service
-
-On Cloud Run the service **scales to zero and is billed only while a request is open**,
-which is why an agent that is busy half an hour a day does not cost a machine's worth a
-month. The price of that is a service with no CPU of its own: it cannot keep a clock, and
-it cannot finish work in the background of a response. So all four triggers are delivered
-to it as HTTP requests, and the handler holds each request open until the run settles.
-
-`scripts/setup-scheduler.sh` creates the senders: **Cloud Scheduler** for the crons and for
-an hourly (or poll-interval) housekeeping sweep, **Cloud Tasks** for everything that has to
-be acknowledged immediately — webhooks, manual runs, follow-ups due later. Both cap one
-attempt at 30 minutes, so a run that lasts longer spans several: the handler answers 503,
-and the retry re-attaches to the same run instead of starting another. Nothing about
-durability rests on this — the queue journal and the spawn spool on the memory bucket stay
-the record, and the sweep re-drives anything a delivery lost.
-
-The alternative shape is a machine that is always awake — a Mac mini, or a service pinned
-to `min-instances=1`. There the process keeps its own timers and needs none of the above;
-leaving `AGENT_TASKS_QUEUE` unset is what selects it. Do not do half of each: a
-scaled-to-zero service without Scheduler jobs looks healthy and runs nothing, and an
-always-on service with them fires every cron twice.
-
-## Memory and audit
-
-Each job has a memory directory it reads at the start of a run and updates at the end —
-working state, not bulk content. It lives on a mounted bucket, so it survives restarts and
-deploys.
-
-Separately, every run writes to an **audit bucket** that is never mounted and never
-readable by the agent: the prompt, the trigger, the result, and the full transcript of
-every tool call. That is where you look when a run surprises you, and it is deliberately
-out of the agent's own reach.
-
-## Where it runs
-
-Cloud Run is the default and the only place where service-account authentication works for
-the metadata-server surfaces (domain-wide delegation, GA4, Search Console, Ads, deployment
-listing). The same image runs anywhere docker does, and the service also runs natively on
-a Mac or Linux box with Node 24+, `MEMORY_DIR` pointed at a real directory and
-`NODE_ENV=production` to enable crons — keep it alive with launchd or systemd. Off Cloud
-Run, the metadata-server surfaces degrade to their fallbacks.
-
-**Run it in exactly one place at a time.** Two instances mean every cron fires twice and
-both send email — and on Cloud Run, scaling to zero is what makes the second copy tempting,
-so check that the first one is actually stopped rather than merely idle.