@meffecta/agent 1.0.3 → 1.0.7

package/README.md

@@ -26,7 +26,7 @@ npx @meffecta/agent setup-infra           # registry, buckets, service account,
 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
+npx @meffecta/agent sync-triggers       # give it its triggers
 ```
 
 Giving it access to something — Gmail, GA4, Grafana, PostHog, Cloudflare, an inbox
@@ -71,6 +71,54 @@ together, so a script can never provision the wrong shape for the engine it is a
 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.
 
+## Writing a job
+
+```bash
+meffecta-agent create-job "a marketing report every Wednesday at 2pm"
+```
+
+The model runs **on your deployment**, not on your laptop — it already holds the Claude
+token, and more importantly its run has your content repo cloned and the engine's skills
+mounted, so it can read your existing jobs for house style, your worlds, and
+`systems/` for which systems this deployment can actually reach. It writes a file to
+`jobs/<name>.md` and stops: nothing is committed, pushed or deployed, because that prompt
+is something your agent will run and you should read it first.
+
+What comes back is checked before it is written — a valid five-field cron in your
+deployment's timezone, a usable job name, no `inbox:` without `allowFrom:` (the engine
+refuses those, deliberately), an `effort:` the engine accepts, and no silent overwrite of
+an existing job. `--dry-run` prints without writing; `--name` overrides the chosen name.
+
+After you edit it by hand:
+
+```bash
+meffecta-agent check-jobs     # the same checks, on every job file here
+```
+
+## Anonymous analytics
+
+On by default, and one command to stop:
+
+```bash
+meffecta-agent analytics        # exactly what is sent, and the current state
+meffecta-agent analytics off    # or set DO_NOT_TRACK=1
+```
+
+**Sent:** which command ran — matched against the built-in list, never a word you typed —
+whether it worked, how long it took, the class of any error, this CLI's version and the
+engine tag it deploys, Node version, OS and architecture, how you installed it, and whether
+a `deployment.env` was found. Plus a random id generated on your machine, so repeat runs
+count as one install.
+
+**Never sent:** your GCP project or service name, region, repo URLs, account or email
+address, file paths, command arguments, secret names or values, job names, prompts — or any
+error *message*. Only the error's class, because messages routinely quote a project id, a
+path, or a line of `gcloud` output.
+
+Off automatically in CI. Nothing is written to your machine at all if you have opted out.
+It is one bounded request after the command's own work is finished, and a failure to send
+is silent — analytics can never delay or fail a deploy.
+
 ## Requirements
 
 `gcloud` (authenticated), `docker` (to mirror engine images into your registry), `git`, and

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.7",
+  "builtFrom": "26157a11d57ec9821672a644bf2ea5b3da3e23f5"
 }

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,
+  };
+}