@meffecta/agent 1.1.0 → 1.1.2

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.1.0",
-  "builtFrom": "ce6db59f4b8be5d791d3924929484f03546b6822"
+  "engineTag": "1.1.2",
+  "builtFrom": "d7e2ae69bb32ec92bbc927d67cc0c96190d2789a"
 }

package/lib/commands.js

@@ -4,9 +4,11 @@ import { fileURLToPath } from "node:url";
 import { configPath, decideAnalytics, readConfig, resolvePosthog, writeConfig } from "./analytics.js";
 import { requireDeployment, UserError } from "./config.js";
 import { checkJobs, createJob } from "./create-job.js";
+import { checkSystems, createSystem } from "./create-system.js";
 import { runDoctor } from "./doctor.js";
 import { parseFlags } from "./flags.js";
 import { api, requireCommand, stream } from "./gcloud.js";
+import { history } from "./history.js";
 import { connect } from "./integrations.js";
 import { resources } from "./resources.js";
 import { verifyCredentials } from "./verify-credentials.js";
@@ -310,7 +312,15 @@ async function jobs() {
 }
 
 async function runJob(args) {
-  const { flags, positional } = parseFlags(args, { in: { type: "int", min: 1, max: 3600 } });
+  const { flags, positional, help } = parseFlags(
+    args,
+    { in: { type: "int", min: 1, max: 3600 } },
+    { usage: "meffecta-agent run <job> [--in <seconds>]" },
+  );
+  if (help) {
+    console.log(help);
+    return 0;
+  }
   const name = positional[0];
   if (!name) {
     throw new UserError("Which job? Try: meffecta-agent jobs");
@@ -331,11 +341,19 @@ async function ask(args) {
   // 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 { flags, positional, help } = parseFlags(
+    args,
+    {
+      model: {},
+      effort: {},
+      timeoutSeconds: { type: "int", min: 1, max: 3600 },
+    },
+    { usage: 'meffecta-agent ask "how did search do last week" [--model M] [--effort E]' },
+  );
+  if (help) {
+    console.log(help);
+    return 0;
+  }
   const prompt = positional.join(" ");
   if (!prompt) {
     throw new UserError('Ask it what? e.g. meffecta-agent ask "how did search do last week"');
@@ -538,7 +556,15 @@ 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 { flags, help } = parseFlags(
+    args,
+    { limit: { type: "int", min: 1, max: 1000 } },
+    { usage: "meffecta-agent logs [--limit N]" },
+  );
+  if (help) {
+    console.log(help);
+    return 0;
+  }
   const d = requireDeployment();
   const limit = String(flags.limit ?? 40);
   const { code } = await stream("gcloud", [
@@ -771,7 +797,9 @@ export const GROUPS = [
       ["secrets", "What is in Secret Manager, and whether the service reads it", secretsList],
       ["triggers", "The Cloud Scheduler jobs and task queue that drive it", triggers],
       ["logs", "Recent service logs (--limit N)", logs],
+      ["history", "What it has actually run: outcome, duration and cost per run (--job, --since, --failed)", history],
       ["check-jobs", "Validate the job files here — after you have edited one by hand", checkJobs],
+      ["check-systems", "Validate the register here, and every job's systems: against it", checkSystems],
       ["analytics", "What anonymous usage data is sent, and how to turn it off", analytics],
       ["resources", "Everything the set-up built in Google Cloud, and what each part is for", resources],
     ],
@@ -780,6 +808,11 @@ export const GROUPS = [
     title: "Operate it",
     commands: [
       ["create-job", 'Write a new job from a description: create-job "a report every Wednesday 2pm"', createJob],
+      [
+        "create-system",
+        'Write a systems/ register entry: create-system "our HubSpot CRM" — it finds the variables',
+        createSystem,
+      ],
       ["run", "Trigger one job now, or --in <seconds>", runJob],
       ["ask", "Ask it something as a one-off run", ask],
       ["sweep", "Run the housekeeping sweep now", sweep],

package/lib/create-job.js

@@ -215,7 +215,15 @@ function buildPrompt(description, { timezone, existing }) {
 }
 
 export async function createJob(args) {
-  const { flags, positional } = parseFlags(args, { name: {}, model: {}, "dry-run": { type: "boolean" } });
+  const { flags, positional, help } = parseFlags(
+    args,
+    { name: {}, model: {}, "dry-run": { type: "boolean" } },
+    { usage: 'meffecta-agent create-job "a report every Wednesday at 2pm" [--name <file>] [--dry-run]' },
+  );
+  if (help) {
+    console.log(help);
+    return 0;
+  }
   const description = positional.join(" ").trim();
   if (!description) {
     throw new UserError(

package/lib/create-system.js

@@ -0,0 +1,398 @@
+// `create-system "<the system>"` — a register entry written by the agent itself.
+//
+// A register entry used to be a document: prose the model read to learn which of this
+// deployment's variables reach which system. It is now load-bearing. A job's `systems:`
+// names entries, and only those entries' `requires` and `selectors` are put in that run's
+// environment — so an entry that lists too little leaves a job unable to work, one that
+// lists too much hands out more than it should, and a `group:` sharing a name with a file
+// in systems/ fails the engine's boot outright.
+//
+// WHERE THE MODEL RUNS: on the deployment, like create-job, and here the reason is sharper
+// than context. Only a run inside the deployment can see which variables are actually SET,
+// and the whole value of an entry is naming the real ones. A model on a laptop would guess
+// them from the skill's documentation and be plausibly, silently wrong.
+//
+// WHAT COMES BACK IS NOT TRUSTED. The entry is parsed the way the engine parses it and
+// checked before it is written — the name, the required fields, variables shaped like
+// variables, and both directions of the group/filename collision that would stop the
+// service booting. As with create-job, the value is the checking.
+//
+// It writes a file and stops. No commit, no push: the operator reads what their agent will
+// be told it may reach.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { requireDeployment, UserError } from "./config.js";
+import { readLocalJobs, readLocalSystems } from "./doctor.js";
+import { parseFlags } from "./flags.js";
+import { api, capture, gcloudArgs } from "./gcloud.js";
+
+/** Sentinels rather than code fences: an entry's prose may itself contain fenced blocks. */
+const BEGIN = "SYSTEM_FILE_BEGIN";
+const END = "SYSTEM_FILE_END";
+
+/** Every field the engine and the baseline prompt define for an entry. */
+const REQUIRED_FIELDS = ["system", "skill", "requires", "access", "probe"];
+
+/** The same shape src/systems.ts reads a variable name in. */
+const VARIABLE = /^[A-Z][A-Z0-9_]*$/;
+
+/** A system name is a filename, and the key a job's `systems:` names it by. */
+export function validName(name) {
+  return /^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$/.test(name ?? "");
+}
+
+/** The engine's frontmatter rules (src/jobs.ts), which the register is parsed with too. */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    return { meta: {}, body: content.trim() };
+  }
+  const meta = {};
+  for (const line of match[1].split("\n")) {
+    const [key, ...rest] = line.split(": ");
+    if (key && rest.length) {
+      meta[key.trim()] = rest.join(": ").replace(/^["']|["']$/g, "");
+    }
+  }
+  return { meta, body: match[2].trim() };
+}
+
+export function extractSystemFile(answer) {
+  const start = answer.indexOf(BEGIN);
+  const stop = answer.indexOf(END);
+  if (start < 0 || stop < 0 || stop < start) {
+    return null;
+  }
+  const named = answer.match(/SYSTEM_NAME:\s*([^\n]+)/);
+  const notes = answer.match(/SYSTEM_NOTES:\s*([^\n]+)/);
+  return {
+    name: named?.[1].trim().replace(/\.md$/, ""),
+    file: `${answer.slice(start + BEGIN.length, stop).trim()}\n`,
+    notes: notes?.[1].trim(),
+  };
+}
+
+const list = (value) =>
+  (value ?? "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+/**
+ * Everything that would make this entry grant the wrong things, or stop the service
+ * booting. `register` is the entries already on disk; `configured` is the variable names
+ * actually set on the deployment, when they could be read.
+ *
+ * Returns human problems. A `__note__` prefix marks one that is worth saying but not worth
+ * refusing over — writing the entry before minting the credential is a normal order to
+ * work in.
+ */
+export function validateSystem({ name, file, register = [], configured }) {
+  const problems = [];
+  const names = new Set(register.map((entry) => entry.name));
+  const groups = new Set(register.flatMap((entry) => entry.groups));
+
+  if (!validName(name)) {
+    problems.push(
+      `"${name}" is not usable as a system name. It becomes systems/<name>.md and the key a job's systems: names it by: lower-case letters, digits and hyphens.`,
+    );
+  }
+  if (names.has(name)) {
+    problems.push(`systems/${name}.md already exists. Pass --name to call this one something else.`);
+  }
+  // Both directions of the collision the engine refuses to boot on.
+  if (groups.has(name)) {
+    problems.push(
+      `"${name}" is already a group: on another entry. A job naming it could mean either, so the engine refuses to boot — rename this entry, or the group.`,
+    );
+  }
+
+  const { meta, body } = parseFrontmatter(file);
+  if (!file.startsWith("---\n")) {
+    problems.push("No frontmatter block — the engine would find no variables here at all.");
+  }
+  for (const field of REQUIRED_FIELDS) {
+    if (!meta[field]) {
+      problems.push(`No ${field}: line. Every entry carries ${REQUIRED_FIELDS.join(", ")}.`);
+    }
+  }
+  for (const group of list(meta.group)) {
+    if (names.has(group)) {
+      problems.push(
+        `group: ${group} is also the name of systems/${group}.md. A job naming it could mean either, so the engine refuses to boot.`,
+      );
+    }
+  }
+
+  // `requires: none — <how it is reached instead>` is a real and common entry: a system the
+  // runtime service account is invited on carries no variable at all.
+  const declared = [...list(meta.requires), ...list(meta.selectors)];
+  const claimsNone = /^none\b/i.test(meta.requires ?? "");
+  const variables = declared.map((segment) => segment.match(/^([A-Z][A-Z0-9_]*)(?=$|[\s(])/)?.[1]).filter(Boolean);
+  const prose = (claimsNone ? list(meta.selectors) : declared).filter(
+    (segment) => !VARIABLE.test(segment.split(/[\s(]/)[0]),
+  );
+  if (!claimsNone && variables.length === 0) {
+    problems.push(
+      `requires: names no variable the engine can read. Use exact names (HUBSPOT_TOKEN), or "none — <how it is reached instead>" for a system that needs no credential.`,
+    );
+  }
+  if (claimsNone && variables.length === 0 && !/—|--|:/.test(meta.requires ?? "")) {
+    problems.push("__note__requires: none — say how it IS reached, or a run has nowhere to go when it needs to.");
+  }
+  // `requires: none — domain-wide delegation, keyless on Cloud Run` is one sentence that
+  // happens to contain a comma. Once the field opens with `none` the whole line is prose,
+  // and picking through its clauses for variable names finds only phrases.
+  if (!claimsNone) {
+    for (const segment of prose) {
+      problems.push(
+        `__note__"${segment}" in requires:/selectors: is not shaped like a variable name, so the engine will not pass it to a scoped run.`,
+      );
+    }
+  }
+  if (configured) {
+    const missing = variables.filter((variable) => !configured.has(variable));
+    if (missing.length) {
+      problems.push(
+        `__note__Not set on this deployment yet: ${missing.join(", ")}. A job scoped to this system gets nothing for them — meffecta-agent set-secret <NAME>.`,
+      );
+    }
+  }
+  if (body.length < 20) {
+    problems.push(
+      "__note__No prose under the frontmatter. That half is what tells a run which portal, which database, and what not to touch.",
+    );
+  }
+  return problems;
+}
+
+function buildPrompt(description, { existing, groups }) {
+  return [
+    "You are writing ONE systems/ register entry for the Meffecta Agent deployment you are running in.",
+    "",
+    "The register is not documentation. A job's `systems:` frontmatter names entries here, and",
+    "ONLY those entries' `requires` and `selectors` variables are put in that run's environment.",
+    "An entry naming too few leaves a job unable to work; one naming too many hands out more",
+    "than it should. Write the exact set.",
+    "",
+    "Read first:",
+    "  - systems/*.md in your working directory — the house style, and what already exists",
+    "  - the skill that reaches this system, for what KIND of credential it needs (the skills",
+    "    are shared across deployments and deliberately name no deployment's variables)",
+    "  - worlds/ if present, for the per-project selectors this system might need",
+    "",
+    "The operator asked for an entry for:",
+    `  ${JSON.stringify(description)}`,
+    "",
+    "Rules:",
+    "  - Find the variable NAMES that are actually set in your environment for this system",
+    "    (`printenv | cut -d= -f1 | grep -i <something>` lists names only). Never print, quote",
+    "    or write a variable's VALUE anywhere — not in the file, not in your answer.",
+    "  - requires: the exact names that must all be set. If the system authenticates as the",
+    '    runtime service account and needs no variable, write "none — <how it is reached>".',
+    "  - selectors: optional per-project names (one per world), where an unset one means that",
+    "    project is not wired up rather than that the system is broken.",
+    "  - skill: the skill that reaches it, or `none` and say how it is reached instead.",
+    "  - access: what a JOB may do with it, written honestly — read-only, may send mail, may",
+    "    change DNS.",
+    "  - probe: the cheapest read that proves the credential works, with NO side effect —",
+    "    list domains rather than send, read quota rather than generate.",
+    "  - group: optional labels a job can name instead of listing entries. Do not reuse a name",
+    "    that is already an entry filename; the engine refuses to boot on that ambiguity.",
+    "  - Do not invent variables. If this deployment has no credential for the system, say so",
+    "    in SYSTEM_NOTES and write the entry with the names it WOULD need.",
+    "  - The prose under the frontmatter is what only this deployment knows: which portal,",
+    "    which account, what the naming means, what not to touch.",
+    existing.length ? `  - Entry names already taken: ${existing.join(", ")}` : "",
+    groups.length ? `  - Group names already in use: ${groups.join(", ")}` : "",
+    "",
+    "Answer in EXACTLY this shape and nothing else — no preamble, no code fences:",
+    "",
+    "SYSTEM_NAME: <short-kebab-case-name>",
+    `${BEGIN}`,
+    "---",
+    "<frontmatter lines>",
+    "---",
+    "<the prose>",
+    `${END}`,
+    "SYSTEM_NOTES: <one line: anything the operator must set up or decide, or 'none'>",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * Variable NAMES set on the deployment — never a value, which this has no reason to read
+ * and no way to print. Undefined when gcloud cannot answer: that costs one unsaid note, not
+ * the check, so it is never worth failing the command over.
+ */
+function configuredVariables(d) {
+  try {
+    const svc = JSON.parse(
+      capture(
+        "gcloud",
+        gcloudArgs(d, ["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+      ),
+    );
+    return new Set((svc.spec.template.spec.containers[0].env ?? []).map((e) => e.name));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function createSystem(args) {
+  const { flags, positional, help } = parseFlags(
+    args,
+    { name: {}, model: {}, "dry-run": { type: "boolean" } },
+    { usage: 'meffecta-agent create-system "our HubSpot CRM" [--name <file>] [--dry-run]' },
+  );
+  if (help) {
+    console.log(help);
+    return 0;
+  }
+  const description = positional.join(" ").trim();
+  if (!description) {
+    throw new UserError(
+      'Which system? e.g.\n\n  meffecta-agent create-system "our HubSpot CRM"\n  meffecta-agent create-system "the Postgres read replica for the product database"',
+    );
+  }
+  const d = requireDeployment();
+  const systemsDir = resolve(process.cwd(), "systems");
+  const register = readLocalSystems(systemsDir) ?? [];
+  const existing = register.map((entry) => entry.name);
+  const groups = [...new Set(register.flatMap((entry) => entry.groups))];
+
+  console.error(
+    `Asking ${d.SERVICE} to write it — only it can see which variables are actually set. This takes a minute.`,
+  );
+  const params = new URLSearchParams({ prompt: buildPrompt(description, { existing, groups }) });
+  if (flags.model) {
+    params.set("model", String(flags.model));
+  }
+  const answer = await api(d, `/test?${params}`, { accept: "text/markdown" });
+
+  const extracted = extractSystemFile(answer);
+  if (!extracted?.file) {
+    throw new UserError(
+      `The deployment did not answer in the expected shape, so nothing was written.\n\n${answer.slice(0, 600)}`,
+    );
+  }
+  const name = String(flags.name ?? extracted.name ?? "").trim();
+  const problems = validateSystem({ name, file: extracted.file, register, configured: configuredVariables(d) });
+  const notes = problems.filter((p) => p.startsWith("__note__")).map((p) => p.slice("__note__".length));
+  const errors = problems.filter((p) => !p.startsWith("__note__"));
+
+  console.log("");
+  console.log(`── systems/${name || "?"}.md ${"─".repeat(Math.max(0, 57 - name.length))}`);
+  console.log(extracted.file.trimEnd());
+  console.log("─".repeat(72));
+
+  if (extracted.notes && extracted.notes.toLowerCase() !== "none") {
+    console.log(`\nIt says: ${extracted.notes}`);
+  }
+  for (const note of notes) {
+    console.log(`\nℹ ${note}`);
+  }
+  if (errors.length) {
+    console.log("");
+    for (const problem of errors) {
+      console.log(`✖ ${problem}`);
+    }
+    throw new UserError("\nNot written. Re-run to try again, or fix it by hand from the text above.");
+  }
+
+  if (flags["dry-run"]) {
+    console.log("\n(dry run — nothing written)");
+    return 0;
+  }
+  mkdirSync(systemsDir, { recursive: true });
+  writeFileSync(resolve(systemsDir, `${name}.md`), extracted.file);
+  console.log(`\n✔ Written to systems/${name}.md — read it before you commit it. It decides what a job may reach.`);
+  console.log("");
+  console.log("  git add systems/ && git commit && git push   live on the next run");
+  console.log(`  meffecta-agent doctor                        checks the register against what is set`);
+  console.log(`  systems: ${name}${" ".repeat(Math.max(1, 36 - name.length))}name it in a job to scope that job to it`);
+  return 0;
+}
+
+/**
+ * `check-systems` — the same validation, on the entries that already exist.
+ *
+ * `create-system` writes a file and stops so the operator reads it first, which means the
+ * next thing that happens is a hand-edit. And the register only became load-bearing
+ * recently: every entry written while it was documentation has never been checked at all,
+ * on a deployment where a job's `systems:` now decides what reaches the run.
+ *
+ * It also checks the other direction — every job's `systems:` against the register — because
+ * this is the command that has both loaded. Those are the two failures that do not announce
+ * themselves: a group named like a file stops the service booting, and a name matching
+ * nothing leaves a job running with no credentials and reporting every system unavailable.
+ *
+ * No gcloud, no deployment: this runs on the files in front of you.
+ */
+export async function checkSystems() {
+  const systemsDir = resolve(process.cwd(), "systems");
+  const register = readLocalSystems(systemsDir);
+  if (!register) {
+    throw new UserError(`No systems/ directory in ${process.cwd()}. Run this from your content repo.`);
+  }
+  if (register.length === 0) {
+    console.log('No register entries yet. Write one: meffecta-agent create-system "..."');
+    return 0;
+  }
+
+  let failed = 0;
+  for (const entry of [...register].sort((a, b) => a.name.localeCompare(b.name))) {
+    const problems = validateSystem({
+      name: entry.name,
+      file: readFileSync(resolve(systemsDir, `${entry.name}.md`), "utf8"),
+      // Excluding itself, or every entry collides with its own filename.
+      register: register.filter((other) => other.name !== entry.name),
+    });
+    const errors = problems.filter((p) => !p.startsWith("__note__"));
+    const notes = problems.filter((p) => p.startsWith("__note__"));
+    if (errors.length === 0 && notes.length === 0) {
+      console.log(`✔ ${entry.name}`);
+      continue;
+    }
+    console.log(`${errors.length ? "✖" : "·"} ${entry.name}`);
+    for (const problem of [...errors, ...notes.map((n) => n.slice("__note__".length))]) {
+      console.log(`    ${problem}`);
+    }
+    failed += errors.length ? 1 : 0;
+  }
+
+  // The other direction: what the jobs ask for.
+  const names = new Set(register.map((entry) => entry.name));
+  const groups = new Set(register.flatMap((entry) => entry.groups));
+  const jobs = readLocalJobs(resolve(process.cwd(), "jobs")) ?? [];
+  const scoped = jobs.filter((job) => job.systems && job.systems !== "*");
+  const unresolved = scoped
+    .map((job) => ({
+      job: job.name,
+      missing: list(job.systems).filter((n) => !names.has(n) && !groups.has(n)),
+    }))
+    .filter((entry) => entry.missing.length);
+  console.log("");
+  if (unresolved.length) {
+    for (const { job, missing } of unresolved) {
+      console.log(`✖ jobs/${job}.md is scoped to ${missing.join(", ")} — no entry and no group of that name`);
+    }
+    console.log("    Such a job runs with the credentials of the systems it DID name, and reports the rest");
+    console.log("    unavailable. It looks healthy while doing nothing.");
+    console.log("");
+    failed += unresolved.length;
+  } else if (scoped.length) {
+    console.log(`${scoped.length} of ${jobs.length} job(s) scoped, all naming systems that exist.`);
+  } else if (jobs.length) {
+    console.log(`No job declares systems:, so every run is given every credential this deployment holds.`);
+  }
+
+  console.log(
+    failed
+      ? `${failed} problem(s). A scoped run gets exactly what its entries declare, so these decide what works.`
+      : `${register.length} register ${register.length === 1 ? "entry" : "entries"} valid. \`meffecta-agent doctor\` also checks them against what is actually set.`,
+  );
+  return failed ? 1 : 0;
+}

package/lib/doctor.js

@@ -347,7 +347,7 @@ export async function doctor() {
       if (badAuth.length) {
         r.fail(
           "An inbox job has a requireAuth: it cannot honor",
-          `${badAuth.map((j) => `${j.name}: ${j.requireAuth}`).join("; ")}. Known values are dmarc and dkim, and only on a gmail: inbox — AgentMail authenticates mail itself and reports no verdict to check. Such a job refuses every message.`,
+          `${badAuth.map((j) => `${j.name}: ${j.requireAuth}`).join("; ")}. Known values are dmarc and dkim, and only on a gmail: inbox — neither AgentMail nor Graph reports a per-message verdict this engine can check. Such a job refuses every message.`,
           "Fix the value, or remove the line",
         );
       } else if (unauthenticated.length) {
@@ -357,6 +357,15 @@ export async function doctor() {
           "Add requireAuth: dmarc to the job",
         );
       }
+      // Not a fix the operator can apply in the job file, so it is stated once rather than
+      // nagged about: on these, allowFrom: is the whole of the protection.
+      const unverifiable = inboxJobs.filter((j) => !j.inbox.startsWith("gmail:"));
+      if (unverifiable.length) {
+        r.ok(
+          `${unverifiable.length} inbox job(s) rely on allowFrom: alone`,
+          `${unverifiable.map((j) => `${j.name} (${j.inbox.split(":")[0]})`).join(", ")} — no per-message verdict to check on these systems, so the sender list is the whole of the protection`,
+        );
+      }
 
       // --- what each job may reach ------------------------------------------------
       const register = readLocalSystems(`${process.cwd()}/systems`);

package/lib/flags.js

@@ -11,11 +11,19 @@ import { UserError } from "./config.js";
  *
  * Supports `--name value`, `--name=value`, boolean flags, and `--` to end flag parsing.
  */
-export function parseFlags(argv, spec = {}) {
+export function parseFlags(argv, spec = {}, { usage } = {}) {
   const flags = {};
   const positional = [];
   let onlyPositional = false;
 
+  // `help` is answered here rather than by each command, because the spec is the only
+  // description of a command's options that exists — and the top-level help tells people
+  // this works. It comes back as a flag rather than printing and exiting, so the caller
+  // still owns its own exit code and this stays testable.
+  if (argv.includes("--help") || argv.includes("-h")) {
+    return { flags, positional, help: describeFlags(spec, usage) };
+  }
+
   for (let i = 0; i < argv.length; i += 1) {
     const token = argv[i];
 
@@ -78,5 +86,36 @@ export function parseFlags(argv, spec = {}) {
     flags[name] = raw;
   }
 
-  return { flags, positional };
+  return { flags, positional, help: undefined };
+}
+
+/** What a command takes, from the only place that knows: its own spec. */
+export function describeFlags(spec, usage) {
+  const lines = usage ? [usage, ""] : [];
+  const names = Object.keys(spec);
+  if (names.length === 0) {
+    return [...lines, "This command takes no options."].join("\n");
+  }
+  const shown = names.map((name) => {
+    const definition = spec[name];
+    if (definition.type === "boolean") {
+      return [`--${name}`, ""];
+    }
+    if (definition.type === "int") {
+      const bounds = [
+        definition.min !== undefined && `min ${definition.min}`,
+        definition.max !== undefined && `max ${definition.max}`,
+      ]
+        .filter(Boolean)
+        .join(", ");
+      return [`--${name} <n>`, bounds];
+    }
+    return [`--${name} <value>`, definition.choices ? `one of: ${definition.choices.join(", ")}` : ""];
+  });
+  const width = Math.max(...shown.map(([flag]) => flag.length));
+  return [
+    ...lines,
+    "Options:",
+    ...shown.map(([flag, note]) => `  ${flag.padEnd(width)}${note ? `  ${note}` : ""}`),
+  ].join("\n");
 }

package/lib/history.js

@@ -0,0 +1,360 @@
+import { requireDeployment, UserError } from "./config.js";
+import { parseFlags } from "./flags.js";
+import { capture, gcloudArgs, probe, requireCommand } from "./gcloud.js";
+
+/**
+ * What the deployment has actually been doing.
+ *
+ * Every other read this CLI offers is present-tense — `jobs` is the boot-time registration
+ * list, `queue` is what is pending, `status` is right now. The engine records the past
+ * faithfully, one `job-end` object per run in the audit bucket with the outcome, the
+ * duration and what the model cost, and until this there was no way to read it back short
+ * of composing a storage query by hand.
+ *
+ * **It reads the bucket, not the service.** That is deliberate on a scale-to-zero
+ * deployment: asking the engine would wake an instance and bill for it, and the records are
+ * not in the engine anyway. Looking at a year of history should not cost a cold start.
+ *
+ * The object names are what make this cheap without an index:
+ * `YYYY/MM/DD/HH-MM-SS.mmm_job-end_<job>.json` sorts lexicographically into chronological
+ * order and carries the job in the name, so the listing narrows by day and by job, and only
+ * the handful of records actually being shown are fetched.
+ */
+
+/** One run, as `job-end` records it. */
+const RECORD_KIND = "job-end";
+const DAY_MS = 86_400_000;
+
+/** A year, so a mistyped date cannot turn into a listing of the whole bucket. */
+const MAX_DAYS = 366;
+
+function utcMidnight(date) {
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+
+function parseDay(value, flag) {
+  const at = Date.parse(`${value.trim()}T00:00:00Z`);
+  if (Number.isNaN(at)) {
+    throw new UserError(`${flag} takes a date like 2026-08-01 (got "${value}").`);
+  }
+  return at;
+}
+
+/**
+ * The window to look in, as UTC midnights. `--since` is where to start — a date, or `7d` /
+ * `36h` counted back from the end — and `--until` is where to stop, so a closed range like
+ * `--since 2026-08-01 --until 2026-08-07` asks about that week and nothing outside it.
+ *
+ * Both ends are inclusive whole days, because the audit trail is partitioned by day and a
+ * half-day window would be a promise the listing cannot keep.
+ */
+export function resolveWindow({ since, until } = {}, now = new Date()) {
+  const end = until ? parseDay(until, "--until") : utcMidnight(now);
+  let start;
+  if (!since) {
+    start = end - 6 * DAY_MS;
+  } else {
+    const relative = /^(\d+)([dh])$/.exec(since.trim());
+    if (relative) {
+      const count = Number(relative[1]);
+      const days = relative[2] === "d" ? Math.max(count, 1) : Math.max(Math.ceil(count / 24), 1);
+      start = end - (days - 1) * DAY_MS;
+    } else {
+      start = parseDay(since, "--since");
+    }
+  }
+  if (start > end) {
+    throw new UserError(
+      until
+        ? `--since ${since} is after --until ${until}.`
+        : `--since ${since} is in the future — there is no history there yet.`,
+    );
+  }
+  const days = (end - start) / DAY_MS + 1;
+  if (days > MAX_DAYS) {
+    throw new UserError(`That is ${days} days. Ask for at most ${MAX_DAYS} at a time.`);
+  }
+  return { start, end, days };
+}
+
+/** The UTC day prefixes a window covers, oldest first — the audit trail's own partitioning. */
+export function dayPrefixes(window) {
+  const prefixes = [];
+  for (let at = window.start; at <= window.end; at += DAY_MS) {
+    const day = new Date(at);
+    prefixes.push(
+      `${day.getUTCFullYear()}/${String(day.getUTCMonth() + 1).padStart(2, "0")}/${String(day.getUTCDate()).padStart(2, "0")}`,
+    );
+  }
+  return prefixes;
+}
+
+/**
+ * A job name as the audit trail spells it: `recordAudit` replaces everything outside
+ * `[A-Za-z0-9._-]` with `-`, so a filter has to ask the same question the writer answered.
+ */
+export function qualifier(job) {
+  return job.replace(/[^a-zA-Z0-9._-]/g, "-");
+}
+
+/** Where this deployment writes its audit trail, read off the service. */
+function auditBucket(d) {
+  const svc = JSON.parse(
+    capture(
+      "gcloud",
+      gcloudArgs(d, ["run", "services", "describe", d.SERVICE, `--region=${d.REGION}`, "--format=json"]),
+    ),
+  );
+  const bucket = (svc.spec?.template?.spec?.containers?.[0]?.env ?? []).find((e) => e.name === "AUDIT_BUCKET")?.value;
+  if (!bucket) {
+    throw new UserError(
+      "This deployment has no AUDIT_BUCKET set, so nothing records what its runs did.\n\n" +
+        "  meffecta-agent setup-infra\n\nprovisions the bucket and sets it.",
+    );
+  }
+  return bucket;
+}
+
+/** When the run ended, in the reader's own timezone. The record carries its own UTC stamp. */
+export function localTime(record) {
+  const at = record.at ? new Date(record.at) : undefined;
+  return at && !Number.isNaN(at.getTime())
+    ? at.toLocaleString(undefined, { dateStyle: "short", timeStyle: "short" })
+    : "—";
+}
+
+export function formatDuration(ms) {
+  if (!Number.isFinite(ms)) {
+    return "—";
+  }
+  const seconds = Math.round(ms / 1000);
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+function formatCost(record) {
+  const usd = record.cli?.total_cost_usd;
+  return typeof usd === "number" ? `$${usd.toFixed(2)}` : "—";
+}
+
+export function describeTrigger(trigger) {
+  if (!trigger) {
+    return "—";
+  }
+  if (trigger.kind === "spawn") {
+    return `spawn:${trigger.label ?? "?"}`;
+  }
+  return String(trigger.kind ?? "—");
+}
+
+/** The first eight characters of a run id — what the table shows, and what `<id>` matches. */
+export function shortId(runId) {
+  return typeof runId === "string" ? runId.slice(0, 8) : "—";
+}
+
+/** Newest-first object names, already narrowed to what will be fetched. */
+export function selectRecords(names, { limit, job }) {
+  const wanted = job ? `_${RECORD_KIND}_${qualifier(job)}.json` : `_${RECORD_KIND}_`;
+  return names
+    .filter((name) => name.includes(wanted))
+    .sort()
+    .slice(-limit)
+    .reverse();
+}
+
+/** Indent a block so a multi-line result reads as one field rather than as more output. */
+function indent(text, prefix = "  ") {
+  return String(text)
+    .split("\n")
+    .map((line) => prefix + line)
+    .join("\n");
+}
+
+/**
+ * One run in full. The table answers "what has it been doing"; this answers "what happened
+ * in that one" — what it was told, what it could reach, what it produced, how it ended.
+ */
+export function renderRun(record) {
+  const lines = [];
+  const status = record.status === "error" ? "FAILED" : (record.status ?? "—");
+  lines.push(`${record.jobName ?? "—"} · ${status} · ${localTime(record)}`, "");
+
+  const field = (label, value) => {
+    if (value !== undefined && value !== null && value !== "") {
+      lines.push(`${label.padEnd(11)}${value}`);
+    }
+  };
+  field("Run id", record.runId);
+  field("Trigger", describeTrigger(record.trigger));
+  field("Duration", formatDuration(record.durationMs));
+  field("Cost", formatCost(record));
+  const settings = record.jobSettings;
+  if (settings) {
+    field(
+      "Settings",
+      [
+        settings.model && `model ${settings.model}`,
+        settings.effort && `effort ${settings.effort}`,
+        settings.timeoutMs && `timeout ${Math.round(settings.timeoutMs / 1000)}s`,
+        settings.allowedTools && `tools ${settings.allowedTools}`,
+      ]
+        .filter(Boolean)
+        .join(", "),
+    );
+  }
+  if (record.scope) {
+    const { systems, variables, unknown } = record.scope;
+    field(
+      "Systems",
+      Array.isArray(systems)
+        ? `${systems.join(", ") || "none"}${typeof variables === "number" ? ` (${variables} variables)` : ""}${unknown?.length ? ` — unmatched: ${unknown.join(", ")}` : ""}`
+        : String(systems),
+    );
+  }
+  if (record.modelFallback) {
+    field("Fell back", `${record.modelFallback.from} → ${record.modelFallback.to} (${record.modelFallback.reason})`);
+  }
+
+  if (record.prompt) {
+    lines.push("", "Prompt", indent(record.prompt));
+  }
+  if (record.result) {
+    const truncated =
+      record.resultChars > record.result.length ? ` (first part of ${record.resultChars} characters)` : "";
+    lines.push("", `Result${truncated}`, indent(record.result));
+  }
+  if (record.error) {
+    lines.push("", "Error", indent(record.error));
+  }
+  if (record.stderr) {
+    lines.push("", "stderr", indent(record.stderr));
+  }
+  return lines.join("\n");
+}
+
+export async function history(args) {
+  requireCommand("gcloud", "run records are read from the audit bucket");
+  const { flags, positional, help } = parseFlags(
+    args,
+    {
+      job: { type: "string" },
+      since: { type: "string" },
+      until: { type: "string" },
+      limit: { type: "int", min: 1, max: 200 },
+      failed: { type: "boolean" },
+      json: { type: "boolean" },
+    },
+    {
+      usage:
+        "meffecta-agent history [<run id>] [options]\n\n" +
+        "  history                                    the last week of runs\n" +
+        "  history --job morning-brief --since 30d    one job, further back\n" +
+        "  history --since 2026-08-01 --until 2026-08-07   a closed range\n" +
+        "  history --failed                           only the ones that broke\n" +
+        "  history 8b2811f7                           one run in full, by the id in column one",
+    },
+  );
+  if (help) {
+    console.log(help);
+    return 0;
+  }
+  const wantedId = positional[0];
+  const d = requireDeployment();
+  const bucket = auditBucket(d);
+  const window = resolveWindow(flags);
+  const prefixes = dayPrefixes(window);
+  const span = prefixes.length === 1 ? prefixes[0] : `${prefixes[0]} to ${prefixes.at(-1)}`;
+  // Looking for one run means reading until it is found, so the cap is a search depth rather
+  // than a page size — and a run named by id is worth looking further back for.
+  const limit = flags.limit ?? (wantedId ? 200 : 20);
+
+  // One listing per day rather than one recursive listing of the bucket: a year of audit
+  // records is a large object count, and the window is almost always a few days of it. A
+  // day with no runs simply is not there, which `probe` reports as nothing, not a failure.
+  const listings = await Promise.all(
+    prefixes.map((prefix) => probe("gcloud", gcloudArgs(d, ["storage", "ls", `gs://${bucket}/${prefix}/**`]))),
+  );
+  const names = listings
+    .flatMap((out) => (out ?? "").split("\n"))
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("gs://"));
+
+  const chosen = selectRecords(names, { limit, job: flags.job });
+  if (chosen.length === 0) {
+    console.log(
+      `No runs recorded ${span}${flags.job ? ` for ${flags.job}` : ""}.\n\n` +
+        "The audit trail starts when a run ends, so a deployment that has not run yet is empty.\n" +
+        "Widen the window with --since 30d, or ask for a range: --since 2026-08-01 --until 2026-08-07.",
+    );
+    return 0;
+  }
+
+  // Fetched only for the records being shown — the listing above is names, the cheap half,
+  // and this is the one that costs a read per run.
+  const records = [];
+  for (const name of chosen) {
+    const body = await probe("gcloud", gcloudArgs(d, ["storage", "cat", name]));
+    if (!body) {
+      continue;
+    }
+    try {
+      const record = JSON.parse(body);
+      records.push(record);
+      // Newest first, so the wanted run is usually in the first few objects. Stopping there
+      // beats fetching the rest of the window to throw it away.
+      if (wantedId && String(record.runId ?? "").startsWith(wantedId)) {
+        break;
+      }
+    } catch {
+      // A truncated or half-written object is one run missing from a listing, not a reason
+      // to fail the whole read.
+      console.error(`(skipped an unreadable record: ${name.split("/").pop()})`);
+    }
+  }
+
+  if (wantedId) {
+    const match = records.find((r) => String(r.runId ?? "").startsWith(wantedId));
+    if (!match) {
+      throw new UserError(
+        `No run whose id starts with "${wantedId}" ${span}.\n\n` +
+          "Ids are the first column of `meffecta-agent history`. Look further back with --since.",
+      );
+    }
+    console.log(flags.json ? JSON.stringify(match, null, 2) : renderRun(match));
+    return 0;
+  }
+
+  const rows = flags.failed ? records.filter((r) => r.status === "error") : records;
+  if (flags.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  if (rows.length === 0) {
+    console.log(`No failed runs ${span}.`);
+    return 0;
+  }
+
+  const cells = rows.map((r) => [
+    shortId(r.runId),
+    localTime(r),
+    r.jobName ?? "—",
+    describeTrigger(r.trigger),
+    r.status ?? "—",
+    formatDuration(r.durationMs),
+    formatCost(r),
+  ]);
+  const widths = cells[0].map((_, i) => Math.max(...cells.map((row) => row[i].length)));
+  for (const row of cells) {
+    console.log(row.map((cell, i) => (i >= 5 ? cell.padStart(widths[i]) : cell.padEnd(widths[i]))).join("  "));
+  }
+
+  const failed = records.filter((r) => r.status === "error").length;
+  const spend = records.reduce((sum, r) => sum + (r.cli?.total_cost_usd ?? 0), 0);
+  console.log(
+    `\n${rows.length} run(s), ${span}` +
+      `${failed ? `, ${failed} failed` : ""}` +
+      `${spend > 0 ? `, $${spend.toFixed(2)} of model usage` : ""}` +
+      `${records.length === limit ? ` — newest ${limit}, raise with --limit` : ""}`,
+  );
+  console.log("One run in full: meffecta-agent history <id from the first column>");
+  return 0;
+}

package/lib/integrations.js

@@ -219,8 +219,9 @@ const INTEGRATIONS = {
       "",
       "and `deploy` to register it — both fields are read when the service boots.",
       "",
-      "The system is required: `gmail:<address>`, or `agentmail:<address>` for an inbox the",
-      "agent owns. A bare address is refused rather than guessed at, because an address",
+      "The system is required: `gmail:<address>`, `outlook:<address>` for a Microsoft 365",
+      "mailbox, or `agentmail:<address>` for an inbox the agent owns. A bare address is",
+      "refused rather than guessed at, because an address",
       "polled against the wrong system finds nothing for ever and looks healthy doing it.",
       "",
       "allowFrom is required and enforced in code: mail from anyone not listed is dropped",

package/lib/verify-credentials.js

@@ -105,12 +105,20 @@ export function buildVerifyPrompt() {
  */
 export function verifyCredentials(ask) {
   return async (args) => {
-    const { flags, positional } = parseFlags(args, {
-      quick: { type: "boolean" },
-      model: {},
-      effort: {},
-      timeoutSeconds: { type: "int", min: 1, max: 3600 },
-    });
+    const { flags, positional, help } = parseFlags(
+      args,
+      {
+        quick: { type: "boolean" },
+        model: {},
+        effort: {},
+        timeoutSeconds: { type: "int", min: 1, max: 3600 },
+      },
+      { usage: "meffecta-agent verify-credentials [--quick]" },
+    );
+    if (help) {
+      console.log(help);
+      return 0;
+    }
     if (positional.length) {
       throw new UserError(`verify-credentials takes no arguments (got "${positional.join(" ")}").`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meffecta/agent",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {