@meffecta/agent 1.1.1 → 1.1.2

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.1.1",
-  "builtFrom": "ab3338abfafb491dc74fc4480d5ecbd6421fb827"
+  "engineTag": "1.1.2",
+  "builtFrom": "d7e2ae69bb32ec92bbc927d67cc0c96190d2789a"
 }

package/lib/commands.js

@@ -8,6 +8,7 @@ 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";
@@ -311,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");
@@ -332,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"');
@@ -539,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", [
@@ -772,6 +797,7 @@ 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],

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

@@ -242,7 +242,15 @@ function configuredVariables(d) {
 }
 
 export async function createSystem(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-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(

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.1",
+  "version": "1.1.2",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {