@meffecta/agent 1.1.0 → 1.1.1

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.1.0",
-  "builtFrom": "ce6db59f4b8be5d791d3924929484f03546b6822"
+  "engineTag": "1.1.1",
+  "builtFrom": "ab3338abfafb491dc74fc4480d5ecbd6421fb827"
 }

package/lib/commands.js

@@ -4,6 +4,7 @@ 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";
@@ -772,6 +773,7 @@ export const GROUPS = [
       ["triggers", "The Cloud Scheduler jobs and task queue that drive it", triggers],
       ["logs", "Recent service logs (--limit N)", logs],
       ["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 +782,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-system.js

@@ -0,0 +1,390 @@
+// `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 } = parseFlags(args, { name: {}, model: {}, "dry-run": { type: "boolean" } });
+  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/package.json

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