@meffecta/agent 1.0.3 → 1.0.8

package/README.md

@@ -1,94 +1,109 @@
-# @meffecta/agent
+# Meffecta Agent
 
-Set up and operate a **Meffecta Agent** deployment — a self-hosted Claude Code job runner
-that wakes on a schedule, a webhook, or new mail, and runs a job against a fresh clone of
-your own content repo.
+An AI colleague that runs in **your own Google Cloud**, on **your own jobs**, against your
+own systems. It wakes on a schedule, a webhook, or an email, does a piece of real work, and
+reports back — then goes back to sleep costing nothing.
 
-The agent itself is a container image (`ghcr.io/meffecta/agent`). This package is the tool
-that stands one up and runs it, and it is all you need: the engine's source is private,
-and nothing here depends on it.
+Work arrives finished, rather than waiting in a chat window for you to open it — though
+you can also just ask it something when you want to.
 
-```bash
-npx @meffecta/agent steps      # the whole set-up, in order
-npx @meffecta/agent help       # every command
-```
+### → [agent.meffecta.com](https://agent.meffecta.com)
 
-## What it does
+What it is, what you need, and the whole set-up in order. This package (`@meffecta/agent`)
+is the tool that stands one up and operates it.
 
-Run it from your **content repo** — the directory holding `deployment.env`, `jobs/`,
-`worlds/` and `SYSTEM.md`. That file says which GCP project and Cloud Run service this
-deployment is, so a command can never quietly act on the wrong one.
+## What people run it for
 
-```bash
-npx @meffecta/agent create-project        # a GCP project
-npx @meffecta/agent link-billing          # attach billing
-npx @meffecta/agent setup-infra           # registry, buckets, service account, service
-npx @meffecta/agent set-secret AGENT_API_SECRET --random
-npx @meffecta/agent set-env GIT_REPO_URL=https://github.com/you/your-content-repo.git
-npx @meffecta/agent deploy                # roll out the engine
-npx @meffecta/agent setup-scheduler       # give it its triggers
-```
+A job is a page of plain-language instructions, so this is a sample rather than a menu —
+the agent does what your jobs say.
 
-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:
+**Sales** — find prospects and check them against your CRM, research each company and its
+decision-maker, leave outreach drafts in the seller's own mailbox for them to send, and put
+a next step on every priority account.
 
-```bash
-npx @meffecta/agent connect              # what can be connected
-npx @meffecta/agent connect gmail        # what to do, in order, with the commands
-```
+**Marketing** — one weekly read across traffic, search, ads and campaigns. Website and
+search audits with fixes proposed. Ad reviews, where changes happen only on request. Watches
+form leads, contacts, and competitors' rankings.
 
-Then, day to day:
+**Customer care** — a support inbox that answers or hands over with the findings attached,
+learns from the conversations, and keeps help pages current as things change.
 
-```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)
-npx @meffecta/agent secrets               # what is stored, and what the service reads
-npx @meffecta/agent triggers              # the Cloud Scheduler jobs and task queue
-npx @meffecta/agent logs --limit 100
-npx @meffecta/agent run morning-brief
-npx @meffecta/agent ask "how did search do last week"
-```
+**Compliance** — review an ISO 27001 document set against the standard, find what is overdue
+or contradicts itself, and draft revisions for a person to approve — sized to your business
+rather than to a template's idea of one. It never records that a control is in place: that
+claim is what an audit tests.
 
-`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.
+**Engineering** — overnight error triage with fixes proposed as pull requests, a verdict on
+every proposed change, alerts traced to a likely cause, and weekly upkeep.
 
-## Two things worth knowing
+**Leadership** — a morning brief tailored to each person's role, daily status on what is
+live and in use, and weekly reviews that stay honest about flat weeks.
 
-**The version you install is the engine you deploy.** Each release records the engine build
-published alongside it, and `deploy` defaults to that image. Tooling and engine move
-together, so a script can never provision the wrong shape for the engine it is aimed at.
-`meffecta-agent version` tells you which pair you have.
+**Assistant** — email it anything: a lookup, a draft, a booking, a question. One calendar
+across Google and Microsoft 365. Inbox digests and the week ahead.
+
+## What it can reach
 
-**Secret values are never printed.** `secrets` lists what exists and whether the service
-reads it; `env` names secret-backed settings without resolving them. Setting one takes the
-value from a pipe, a file, or a hidden prompt — never from your shell history.
+Shipped with the engine, pointed at your accounts by your jobs:
 
-## Requirements
+| | Reached out of the box |
+|---|---|
+| **Mail & calendar** | Gmail, Microsoft 365, Google Calendar |
+| **Documents** | Drive, Sheets, Docs, Slides |
+| **Your numbers** | GA4, Search Console, Google Ads, PostHog, Ahrefs |
+| **Your data** | BigQuery, Elasticsearch, MongoDB — and logs from Grafana or Coralogix |
+| **The market** | Google's live search results — real rankings, not a web search |
+| **CRM** | HubSpot, reading and writing as separate abilities |
+| **Work & content** | Linear issues and cycles; Webflow pages and CMS, staged before anything goes public |
+| **Slack** | Posts, threads and reactions — and answers when someone @-mentions it |
+| **Infrastructure** | Cloudflare, and a real headless browser for anything without an API |
+| **Your code** | any Git repo as the working directory, with pull requests as the output |
 
-`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.
+Anything else is a skill you add to your own repo — the engine never needs to know about it.
 
-## Developing it
+## How it works
 
-From a checkout of the engine repo:
+Your **content repo** holds the jobs, the facts about your business, and the register of
+which systems this deployment may touch. Every run clones it fresh. Push a changed prompt
+and the next run uses it; there is nothing to build and nothing to deploy.
+
+Jobs are triggered by a **schedule**, a **webhook**, or **an email to an address you name**
+— and a job that runs out of time can hand the rest to a follow-up run of itself. Each job
+keeps its own memory across runs, and every prompt, result and transcript lands in a
+write-once audit bucket.
+
+## Built to be trusted with the keys
+
+It runs in **your** GCP project, on **your** credentials, billed to **your** Claude
+subscription. Nothing routes through Meffecta.
+
+A job reaches only the systems your register lists, and reading and changing are separate
+abilities — a reporting job loads the reader and never the writer.
+
+One shipped skill exists to change a paid account, Google Ads, and it is the most
+constrained thing here: every change is validated against the live account first and only
+applied on a second, explicit run; budgets can only go *down*; a campaign can be paused but
+never deleted; and the limits live in the script, not in the instructions, so no wording can
+talk its way past them.
+
+A job reachable by email must say who may reach it, or it refuses everyone — an omission is
+not consent. Secret values are never printed, by any command.
+
+## Operating it
 
 ```bash
-cd cli && npm link      # `meffecta-agent` now runs the working tree
+npx @meffecta/agent steps      # the set-up, in order
+npx @meffecta/agent help       # every command — each also takes --help
+npx @meffecta/agent doctor     # the one to run when something feels wrong
 ```
 
-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.
+Run commands from your content repo — the directory holding `deployment.env`, which says
+which project and service this deployment is, so a command can never act on the wrong one.
+
+**The version you install is the engine you deploy.** Each release records the engine build
+published alongside it, and `deploy` defaults to that image, so tooling and engine cannot
+drift apart. `meffecta-agent version` tells you which pair you have.
 
-## Documentation
+## Licence
 
-`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`.
+UNLICENSED — for use by Meffecta deployments.

package/bin/meffecta-agent.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { open as openAnalytics } from "../lib/analytics.js";
 import { COMMANDS, cliVersion, engineTag, GROUPS } from "../lib/commands.js";
 import { loadDeployment, UserError } from "../lib/config.js";
+import { installMethod } from "../lib/version.js";
 
 /**
  * One entry point for everything an operator does to a Meffecta Agent deployment.
@@ -32,13 +34,15 @@ const STEPS = [
   ],
   [
     "init",
-    "Create your content repo — jobs/, worlds/, SYSTEM.md, ENVIRONMENT.md — and a deployment.env\n    in it. Run everything from there; it is what says which deployment you mean.",
+    "Create your content repo — jobs/, SYSTEM.md, systems/, 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."],
+  ["setup-infra", "Provision GCP, the run queue, and the Cloud Run service shell.\n    --dry-run shows it first."],
   ["set-secret", "AGENT_API_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN."],
   ["set-env", "GIT_REPO_URL=… — the service will not boot without it."],
-  ["deploy", "Roll out the engine image."],
-  ["setup-scheduler", "Give it its triggers. Scaled to zero, it fires nothing without them."],
+  [
+    "deploy",
+    "Roll out the engine image, then create its triggers — scaled to zero it fires\n    nothing without them, and only the running engine knows which jobs exist.",
+  ],
   ["doctor", 'Check it. Then: jobs, run <job>, ask "…".'],
 ];
 
@@ -60,9 +64,10 @@ function help() {
     console.log("");
   }
   console.log("  steps                 The whole set-up, in order, with the command for each");
-  console.log("  version               This CLI and the engine build it deploys\n");
-  console.log("Every command takes --help, and passes its options through to the underlying");
-  console.log("script — so `meffecta-agent deploy --dry-run` and `--tag <sha>` work as documented.\n");
+  console.log("  version               This CLI and the engine build it deploys");
+  console.log("  upgrade               Whether a newer one is out, and what to run\n");
+  console.log("Every command takes --help, and every option it documents — so");
+  console.log("`meffecta-agent deploy --dry-run` and `--tag <sha>` work as described there.\n");
   console.log(`Engine: ghcr.io/meffecta/agent:${tag}${pinned ? " (pinned to this release)" : ""}`);
 }
 
@@ -94,17 +99,60 @@ function version() {
 
 const [name, ...args] = process.argv.slice(2);
 
+const { analytics, firstRun } = openAnalytics({ version: cliVersion() });
+
+// The name is matched against the known commands before it is ever recorded. Whatever an
+// operator actually typed is theirs — a mistyped command could be anything, including
+// something they would not want leaving the machine.
+const BUILT_IN = new Set(["help", "steps", "version"]);
+function recorded(candidate) {
+  if (!candidate) {
+    return "help";
+  }
+  return COMMANDS.has(candidate) || BUILT_IN.has(candidate) ? candidate : "unknown";
+}
+
+const started = Date.now();
+
+/** Record the run, flush, and leave. The only exit in this file. */
+async function finish(code, outcome, extra = {}) {
+  analytics.capture("cli_command", {
+    command: recorded(name),
+    outcome,
+    exit_code: code,
+    duration_ms: Date.now() - started,
+    cli_version: cliVersion(),
+    engine_tag: engineTag().tag,
+    install: installMethod().kind,
+    node_version: process.versions.node,
+    platform: process.platform,
+    arch: process.arch,
+    has_deployment: Boolean(loadDeployment().PROJECT),
+    ...extra,
+  });
+  await analytics.flush();
+  process.exit(code);
+}
+
+// Said once, on the run that mints the id, and never again. A tool that phones home should
+// say so on the machine it phones home from — not only in documentation the operator would
+// have to go looking for. stderr, so it cannot corrupt anything reading stdout.
+if (firstRun) {
+  console.error("(Anonymous usage analytics are on: which commands run, and whether they worked.");
+  console.error(" No project names, arguments or secrets. `meffecta-agent analytics` to see or stop it.)\n");
+}
+
 if (!name || name === "help" || name === "--help" || name === "-h") {
   help();
-  process.exit(0);
+  await finish(0, "ok");
 }
 if (name === "steps") {
   steps();
-  process.exit(0);
+  await finish(0, "ok");
 }
 if (name === "version" || name === "--version" || name === "-v") {
   version();
-  process.exit(0);
+  await finish(0, "ok");
 }
 
 const command = COMMANDS.get(name);
@@ -115,7 +163,7 @@ if (!command) {
     console.error(`Did you mean: ${near.join(", ")}?`);
   }
   console.error("Run `meffecta-agent help` for the list.");
-  process.exit(2);
+  await finish(2, "unknown-command");
 }
 
 try {
@@ -128,11 +176,15 @@ try {
       args.push("--tag", tag);
     }
   }
-  process.exit((await command.handler(args)) ?? 0);
+  const code = (await command.handler(args)) ?? 0;
+  await finish(code, code === 0 ? "ok" : "failed");
 } catch (err) {
   if (err instanceof UserError) {
     console.error(err.message);
-    process.exit(1);
+    await finish(1, "user-error");
   }
+  // The CLASS, never the message: messages quote project ids, paths and gcloud output.
+  analytics.capture("cli_crash", { command: recorded(name), error_kind: err?.constructor?.name ?? "Error" });
+  await analytics.flush();
   throw err;
 }

package/deployment.env.example

@@ -5,13 +5,13 @@
 # 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
+# Start one there:
+#   cd /path/to/your-content-repo && meffecta-agent init
 #
-# 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_API_SECRET --random
-#   /path/to/agent/scripts/deploy.sh
+# Then run everything from that directory — each command reads this file to know which
+# deployment you mean:
+#   meffecta-agent set-secret AGENT_API_SECRET --random
+#   meffecta-agent deploy
 
 # 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.
@@ -23,6 +23,17 @@ SERVICE=acme-agent
 # Docker repo in that project, holding images mirrored from GHCR.
 ARTIFACT_REPO=acme-agent-images
 
+# How the engine image reaches Cloud Run, which can only pull from Artifact Registry.
+#   proxy  (default) ARTIFACT_REPO is a remote repository in front of ghcr.io. AR fetches
+#          the public engine image on demand — nothing is copied, and no docker is needed
+#          on your machine at any point.
+#   mirror the older path: pull from ghcr.io here, retag, push. Needs docker running and
+#          `gcloud auth configure-docker <region>-docker.pkg.dev`, and pushes several GB
+#          per engine version. Use it only if your policy forbids AR reaching the internet.
+# A repository's mode is fixed when it is created, so changing this means a new
+# ARTIFACT_REPO name and another setup-infrastructure run.
+REGISTRY_MODE=proxy
+
 REGION=europe-west1
 
 # Optional. Unset = whichever account gcloud is logged in as. Set it when you work across
@@ -35,14 +46,16 @@ REGION=europe-west1
 # 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
+# Optional. The runtime shape asserted 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.
+# what `meffecta-agent setup-infra` 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.
+#   scale-to-zero  min-instances=0 + CPU billed per request. Costs nothing between jobs.
+#                  The service has no CPU of its own to run a timer with, so everything
+#                  arrives as a request: `setup-infra` creates the queue those arrive on,
+#                  and `deploy` creates the schedules that send them.
 #   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

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.3",
-  "builtFrom": "f784051bc092c57aa37b4e9c44e06ee8f368f8f7"
+  "engineTag": "1.0.8",
+  "builtFrom": "09dbb9d808cafb8b06c0282602f1ca20914e3e6d"
 }

package/lib/analytics.js

@@ -0,0 +1,262 @@
+// Anonymous usage analytics, so the set-up can be improved by evidence rather than guess.
+//
+// This CLI runs on other people's machines, in their cloud accounts, holding their
+// credentials. That earns a stricter standard than a web app's:
+//
+//   - it never blocks     — one bounded POST at exit, and the command's own work is done
+//   - it never throws     — every path swallows its errors; analytics cannot fail a deploy
+//   - it never fires off  — disabled, in CI, or with no key, capture() is a no-op
+//   - it never carries content — see WHAT IS SENT below; the list is exhaustive on purpose
+//
+// Dependency-free by necessity and by choice: the package has no runtime dependencies, and
+// a tool holding someone's cloud credentials is a poor place for a supply chain. That means
+// speaking PostHog's capture API directly rather than pulling in posthog-node.
+//
+// WHAT IS SENT, in full:
+//   which command ran (from the fixed list — never a word the operator typed), whether it
+//   succeeded, how long it took, this CLI's version and the engine tag it deploys, Node
+//   version, OS and architecture, how the CLI was installed, and whether a deployment.env
+//   was found. Plus a random id, minted here, so repeat runs group as one install.
+//
+// WHAT IS NEVER SENT:
+//   the GCP project or service name, the region, repo URLs, email or account names, file
+//   paths, command arguments, secret names or values, job names, prompts, or any error
+//   MESSAGE — only the error's class. Messages are the leak: they routinely quote a
+//   project id, a path, or a line of gcloud output.
+//
+// Not even a hashed project id. It would be genuinely useful — it would let one deployment
+// be followed across machines — but a hash of a short, guessable string is pseudonymous at
+// best, and the anonymous install id already answers most of the same questions. If that
+// correlation is ever wanted it should be a deliberate decision, disclosed on its own, not
+// something that arrived quietly inside a telemetry patch.
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * PostHog *project* key — write-only, designed to ship inside a client, and public by
+ * nature: this package is on npm, so treat it as published. It grants event ingestion and
+ * nothing else. Empty means nothing is ever sent.
+ */
+const DEFAULT_KEY = "phc_pyUMjGAJSMJtStPULeiiutucEiN6qkRhuKr5RJVuEXqX";
+
+/** A project key belongs to one region; this one is EU cloud. */
+const DEFAULT_HOST = "https://eu.i.posthog.com";
+
+const LIB = "meffecta-agent-cli";
+
+/** Analytics is never worth a hang, and never worth a visible pause. */
+const FLUSH_TIMEOUT_MS = 1500;
+
+/** An env var means "on" unless it is empty, "0", or "false". */
+function truthy(value) {
+  const v = (value ?? "").trim().toLowerCase();
+  return v !== "" && v !== "0" && v !== "false";
+}
+
+/** Exported so tests can neutralise every one of them, rather than the two they remember. */
+export const CI_VARS = [
+  "CI",
+  "CONTINUOUS_INTEGRATION",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "CIRCLECI",
+  "TRAVIS",
+  "BUILDKITE",
+  "JENKINS_URL",
+  "TEAMCITY_VERSION",
+  "BITBUCKET_BUILD_NUMBER",
+];
+
+export function isCI(env = process.env) {
+  return CI_VARS.some((key) => truthy(env[key]));
+}
+
+/**
+ * Where the choice and the anonymous id live. Machine-global, NOT beside deployment.env:
+ * the opt-out is a decision by the person at the keyboard and should cover every
+ * deployment they operate, rather than being made again per content repo — and it must
+ * never end up committed to one.
+ */
+export function configDir(env = process.env) {
+  const base = env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+  return join(base, "meffecta-agent");
+}
+
+export function configPath(env = process.env) {
+  return join(configDir(env), "config.json");
+}
+
+/** Missing or corrupt reads as empty. Never throws — this is on the startup path. */
+export function readConfig(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(env), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Merge and persist atomically, so a crash mid-write cannot corrupt the choice. */
+export function writeConfig(patch, env = process.env) {
+  const path = configPath(env);
+  const next = { ...readConfig(env), ...patch };
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`);
+    renameSync(tmp, path);
+  } catch {
+    // A read-only home directory is not a reason to fail a deploy. The consequence is a
+    // fresh id next run, which is the harmless direction to fail in.
+  }
+  return next;
+}
+
+/**
+ * On or off, and why. Opt-out by default, with several ways to say no and one explicit
+ * way to say yes:
+ *
+ *   1. DO_NOT_TRACK=1                 the cross-tool standard — always wins
+ *   2. MEFFECTA_ANALYTICS_DISABLED=1  this tool's own kill switch
+ *   3. config "disabled"              `meffecta-agent analytics disable`
+ *   4. config "enabled"               explicit yes — beats CI detection
+ *   5. a CI environment               off: a pipeline is nobody's choice to make
+ *   6. otherwise                      on
+ *
+ * Pure, so every rule is testable without touching a disk or a network.
+ */
+export function decideAnalytics({ config = {}, env = process.env } = {}) {
+  if (truthy(env.DO_NOT_TRACK)) {
+    return { enabled: false, reason: "do-not-track" };
+  }
+  if (truthy(env.MEFFECTA_ANALYTICS_DISABLED)) {
+    return { enabled: false, reason: "env-disabled" };
+  }
+  if (config.analytics === "disabled") {
+    return { enabled: false, reason: "config-disabled" };
+  }
+  if (config.analytics === "enabled") {
+    return { enabled: true, reason: "config-enabled" };
+  }
+  if (isCI(env)) {
+    return { enabled: false, reason: "ci" };
+  }
+  return { enabled: true, reason: "default" };
+}
+
+/** Endpoint and key, with env overrides for anyone who wants to point it elsewhere. */
+export function resolvePosthog(env = process.env) {
+  return {
+    host: (env.MEFFECTA_POSTHOG_HOST?.trim() || DEFAULT_HOST).replace(/\/+$/, ""),
+    key: env.MEFFECTA_POSTHOG_KEY?.trim() ?? DEFAULT_KEY,
+  };
+}
+
+/** The default transport: one fetch, aborted rather than allowed to hang. */
+const defaultSender = async (url, body, timeoutMs) => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+export class Analytics {
+  #enabled;
+  #id;
+  #key;
+  #host;
+  #version;
+  #send;
+  #queue = [];
+
+  constructor({ enabled = false, anonymousId = "", key = "", host = "", version = "", send } = {}) {
+    this.#enabled = enabled;
+    this.#id = anonymousId;
+    this.#key = key;
+    this.#host = host;
+    this.#version = version;
+    this.#send = send ?? defaultSender;
+  }
+
+  /** Guaranteed to do nothing — the fallback whenever anything is unclear. */
+  static off() {
+    return new Analytics();
+  }
+
+  /** Only true when a real, sendable pipeline exists. */
+  get active() {
+    return this.#enabled && this.#key !== "" && this.#id !== "";
+  }
+
+  /** Queue an event. A no-op when off, and never throws. */
+  capture(event, properties = {}) {
+    if (!this.active) {
+      return;
+    }
+    this.#queue.push({ event, properties, timestamp: new Date().toISOString() });
+  }
+
+  /** Send what is queued. Bounded, and swallows everything. */
+  async flush() {
+    if (!this.active || this.#queue.length === 0) {
+      return;
+    }
+    const batch = this.#queue.splice(0, this.#queue.length);
+    try {
+      await this.#send(
+        `${this.#host}/batch/`,
+        {
+          api_key: this.#key,
+          batch: batch.map((e) => ({
+            event: e.event,
+            distinct_id: this.#id,
+            timestamp: e.timestamp,
+            properties: { ...e.properties, $lib: LIB, $lib_version: this.#version },
+          })),
+        },
+        FLUSH_TIMEOUT_MS,
+      );
+    } catch {
+      // Analytics must never surface an error to the operator.
+    }
+  }
+}
+
+/**
+ * Resolve everything and hand back a client ready to use.
+ *
+ * The id is minted on the first run where analytics is on, and only then: a machine that
+ * has opted out never gets an identifier written to it at all. `firstRun` is true for the
+ * run that mints it, which is the one run that says so out loud.
+ */
+export function open({ env = process.env, version = "unknown", send } = {}) {
+  const config = readConfig(env);
+  const decision = decideAnalytics({ config, env });
+  if (!decision.enabled) {
+    return { analytics: Analytics.off(), decision, config, firstRun: false };
+  }
+  const { host, key } = resolvePosthog(env);
+  let anonymousId = config.anonymousId;
+  const firstRun = !anonymousId;
+  if (firstRun) {
+    anonymousId = randomUUID();
+    writeConfig({ anonymousId }, env);
+  }
+  return {
+    analytics: new Analytics({ enabled: true, anonymousId, key, host, version, send }),
+    decision,
+    config: { ...config, anonymousId },
+    firstRun,
+  };
+}