mira-harness 0.2.5 → 0.2.7

package/README.md

@@ -100,8 +100,8 @@ a "typing…" fallback for a slow bot — replies run 5–62s) and capture, per
 |---|---|
 | `login` | One-time interactive login → prints `TG_SESSION` |
 | `doctor` | Check `.env` / session / connectivity / @mira resolution (read-only) |
-| `send [message...]` | One probe → full reply as JSON (message via arg or stdin). `--quiet --settle --timeout --no-log` |
-| `loop` | Run the catalog paced; grades `expect` probes (exit 1 on failure). `--category --max --confirm --peer --gap --settle --timeout --list --catalog --grep --no-fail --quiet` |
+| `send [message...]` | One probe → full reply as JSON (message via arg or stdin). `--quiet --settle --timeout --no-log --expect-*` |
+| `loop` | Run the catalog paced; grades `expect` probes (exit 1 on failure). `--category --max --confirm --peer --gap --settle --timeout --list --catalog --grep --only --no-fail --quiet` |
 | `catalog` | List the catalog (no sends). `--category --catalog --json` |
 | `watch` | Live-tail @mira's messages (observe-only). `--peer` |
 | `report` | Distill the run log into Markdown. `--in --out --category` |
@@ -164,8 +164,10 @@ graded probe fails — so it drops straight into CI. Add `--no-fail` to report w
 
 `assert` re-grades a **saved** run log against the catalog's `expect` (offline, no @mira) — the
 fast loop for *developing* assertions (capture once, then tune `expect` and re-grade instantly),
-and a way to gate a committed run-log fixture in CI **without a Telegram session**. Run a subset
-of probes by id with `loop --grep <regex>`; emit a catalog JSON Schema for your editor with `schema`.
+and a way to gate a committed run-log fixture in CI **without a Telegram session**. For a one-off
+check, `send` takes inline assertions: `send "What can you do?" --expect-min-links 1 --expect-max-ms 60000`
+(any `--expect-*` exits 1 on failure). Run a subset of probes by id with `loop --grep <regex>` or
+`loop --only <id1,id2>`; emit a catalog JSON Schema for your editor with `schema`.
 
 ### Drift detection
 

package/dist/catalog.d.ts

@@ -85,3 +85,6 @@ export declare function probesFor(category?: string, source?: Probe[]): Probe[];
 /** Keep probes whose `id` matches the pattern (regex, case-insensitive; falls
  *  back to substring on an invalid regex). Used by `loop --grep` to run a subset. */
 export declare function grepProbes(probes: Probe[], pattern: string): Probe[];
+/** Keep only probes whose `id` is in the comma-separated list (exact match).
+ *  Used by `loop --only` for precise selection. */
+export declare function onlyProbes(probes: Probe[], idsCsv: string): Probe[];

package/dist/cli.js

@@ -3,11 +3,6 @@
 // src/cli.ts
 import { Command } from "commander";
 
-// src/catalog.ts
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { z as z2 } from "zod";
-
 // src/assert.ts
 import { z } from "zod";
 var ExpectSchema = z.object({
@@ -77,6 +72,9 @@ function evaluate(expect, result) {
 }
 
 // src/catalog.ts
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { z as z2 } from "zod";
 var CATEGORIES = ["core", "skills", "generation", "wallet"];
 var ProbeSchema = z2.object({
   id: z2.string().min(1),
@@ -307,6 +305,10 @@ function grepProbes(probes, pattern) {
   const needle = pattern.toLowerCase();
   return probes.filter((p) => p.id.toLowerCase().includes(needle));
 }
+function onlyProbes(probes, idsCsv) {
+  const ids = new Set(idsCsv.split(",").map((s) => s.trim()).filter(Boolean));
+  return probes.filter((p) => ids.has(p.id));
+}
 
 // src/commands/assert.ts
 import { resolve as resolve4 } from "node:path";
@@ -432,6 +434,9 @@ function clearTitle() {
 // src/commands/report.ts
 import { readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { resolve as resolve3 } from "node:path";
+function isRunRecord(x) {
+  return typeof x === "object" && x !== null && Array.isArray(x.messages) && typeof x.sent === "string";
+}
 function loadRunRecords(inFile, category) {
   const path = inFile ? resolve3(process.cwd(), inFile) : RUNS_FILE;
   const raw = readFileSync2(path, "utf8");
@@ -442,7 +447,9 @@ function loadRunRecords(inFile, category) {
     if (!t)
       continue;
     try {
-      records.push(JSON.parse(t));
+      const rec = JSON.parse(t);
+      if (isRunRecord(rec))
+        records.push(rec);
     } catch {}
   }
   return category ? records.filter((r) => r.category === category) : records;
@@ -613,6 +620,8 @@ function listCatalog(opts = {}) {
   let probes = probesFor(opts.category, source);
   if (opts.grep)
     probes = grepProbes(probes, opts.grep);
+  if (opts.only)
+    probes = onlyProbes(probes, opts.only);
   if (opts.max !== undefined)
     probes = probes.slice(0, opts.max);
   if (opts.json) {
@@ -863,7 +872,14 @@ function req(name) {
   return v;
 }
 var tgEnv = {
-  apiId: () => Number(req("TG_API_ID")),
+  apiId: () => {
+    const raw = req("TG_API_ID");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`TG_API_ID must be a positive integer (got "${raw}") — see .env.example`);
+    }
+    return n;
+  },
   apiHash: () => req("TG_API_HASH"),
   session: () => process.env.TG_SESSION ?? "",
   miraPeer: process.env.MIRA_PEER ?? "mira",
@@ -1173,7 +1189,7 @@ async function loop(opts) {
     process.exit(1);
   }
   if (opts.list) {
-    listCatalog({ category: opts.category, max: opts.max, catalog: opts.catalog, grep: opts.grep });
+    listCatalog({ category: opts.category, max: opts.max, catalog: opts.catalog, grep: opts.grep, only: opts.only });
     return;
   }
   const source = opts.catalog ? loadCatalog(opts.catalog) : CATALOG;
@@ -1192,10 +1208,15 @@ async function loop(opts) {
     console.error("TG_SESSION is empty — run `mira-harness login` first, then put it in .env.");
     process.exit(1);
   }
-  const matched = opts.grep ? grepProbes(probesFor(opts.category, source), opts.grep) : probesFor(opts.category, source);
+  let matched = probesFor(opts.category, source);
+  if (opts.grep)
+    matched = grepProbes(matched, opts.grep);
+  if (opts.only)
+    matched = onlyProbes(matched, opts.only);
   const probes = matched.slice(0, opts.max);
   if (!probes.length) {
-    console.error(opts.grep ? `no probes match --grep "${opts.grep}".` : "no probes selected.");
+    const why = opts.only ? `--only "${opts.only}"` : opts.grep ? `--grep "${opts.grep}"` : undefined;
+    console.error(why ? `no probes match ${why}.` : "no probes selected.");
     process.exit(1);
   }
   const gap = opts.gap ?? DEFAULT_GAP_MS;
@@ -1313,10 +1334,13 @@ async function send(rawMessage, opts = {}) {
     collect.firstReplyTimeoutMs = opts.timeout;
   const peer = tgEnv.miraPeer;
   const client = await connect(session);
+  let verdict;
   try {
     const result = await withProgress(`@${peer}`, () => sendAndCollect(client, peer, message, collect), opts.quiet);
+    if (opts.expect)
+      verdict = evaluate(opts.expect, result);
     if (!opts.noLog)
-      await appendRun(result);
+      await appendRun(result, verdict ? { assert: verdict } : {});
     if (!opts.quiet) {
       note(result.timedOut ? c.yellow("no reply (timed out)") : c.green(`${result.messages.length} message(s) · first reply ${((result.firstReplyMs ?? 0) / 1000).toFixed(1)}s`));
     }
@@ -1324,6 +1348,16 @@ async function send(rawMessage, opts = {}) {
   } finally {
     await client.disconnect();
   }
+  if (verdict) {
+    if (!opts.quiet) {
+      note(verdict.ok ? c.green("✓ assertions passed") : c.red("✗ assertions failed"));
+      if (!verdict.ok)
+        for (const ch of verdict.checks.filter((x) => !x.ok))
+          note(c.dim(`  ✗ ${ch.name}: ${ch.detail}`));
+    }
+    if (!verdict.ok)
+      process.exit(1);
+  }
 }
 
 // src/commands/stats.ts
@@ -1501,6 +1535,41 @@ function posInt(name, v) {
   }
   return n;
 }
+function nonNegInt(name, v) {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0) {
+    console.error(`--${name} must be a non-negative integer (got "${v}")`);
+    process.exit(1);
+  }
+  return n;
+}
+function buildSendExpect(o) {
+  const raw = {};
+  if (o.expectReply)
+    raw.replies = true;
+  if (o.expectJson)
+    raw.json = true;
+  if (o.expectText !== undefined)
+    raw.textMatches = o.expectText;
+  if (o.expectMinLinks !== undefined)
+    raw.minLinks = nonNegInt("expect-min-links", o.expectMinLinks);
+  if (o.expectMinButtons !== undefined)
+    raw.minButtons = nonNegInt("expect-min-buttons", o.expectMinButtons);
+  if (o.expectWebapp)
+    raw.hasWebApp = true;
+  if (o.expectMedia !== undefined)
+    raw.media = o.expectMedia;
+  if (o.expectMaxMs !== undefined)
+    raw.maxFirstReplyMs = ms("expect-max-ms", o.expectMaxMs);
+  if (!Object.keys(raw).length)
+    return;
+  const parsed = ExpectSchema.safeParse(raw);
+  if (!parsed.success) {
+    console.error(`invalid --expect-* value: ${parsed.error.issues[0]?.message ?? "schema error"}`);
+    process.exit(1);
+  }
+  return parsed.data;
+}
 var program = new Command;
 var version = getVersion();
 program.name("mira-harness").description("Automated probe harness for the @mira Telegram bot (GramJS userbot).").version(version, "-V, --version");
@@ -1509,15 +1578,16 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
 });
 program.command("login").description("One-time interactive login -> prints TG_SESSION for .env").action(login);
 program.command("doctor").description("Check .env, session, connectivity and @mira resolution (read-only)").action(doctor);
-program.command("send").description("Send one probe to @mira and print the full settled reply as JSON").argument("[message...]", "the message (omit to read from stdin)").option("-q, --quiet", "suppress the progress spinner / status line", false).option("--settle <ms>", "quiet window before concluding a reply").option("--timeout <ms>", "give up if no reply by this many ms").option("--no-log", "do not append the result to the run log").action(async (parts, opts) => {
+program.command("send").description("Send one probe to @mira and print the full settled reply as JSON").argument("[message...]", "the message (omit to read from stdin)").option("-q, --quiet", "suppress the progress spinner / status line", false).option("--settle <ms>", "quiet window before concluding a reply").option("--timeout <ms>", "give up if no reply by this many ms").option("--no-log", "do not append the result to the run log").option("--expect-reply", "assert a reply arrives (any --expect-* exits 1 on failure)").option("--expect-json", "assert the first reply text is valid JSON").option("--expect-text <regex>", "assert some reply text matches this regex (case-insensitive)").option("--expect-min-links <n>", "assert at least N links across the reply").option("--expect-min-buttons <n>", "assert at least N inline buttons").option("--expect-webapp", "assert a web_app/startapp Launch button is present").option("--expect-media <kind>", "assert media of this kind (photo|video|audio|document|webpage|other)").option("--expect-max-ms <ms>", "assert the first reply arrives within this many ms").action(async (parts, opts) => {
   await send(parts.join(" "), {
     quiet: opts.quiet,
     settle: ms("settle", opts.settle),
     timeout: ms("timeout", opts.timeout),
-    noLog: opts.log === false
+    noLog: opts.log === false,
+    expect: buildSendExpect(opts)
   });
 });
-program.command("loop").description("Run the experiment catalog against @mira at a human pace").option("-c, --category <category>", `only this category (${CATEGORIES.join(" | ")})`).option("-m, --max <n>", "max probes this run", "6").option("--confirm", "press a safe ✅ Confirm on generation probes (spends credits)", false).option("--peer <peer>", "'experiment'|'group' for TG_EXPERIMENT_CHAT, or a literal allowlisted peer").option("--gap <ms>", "delay between sends").option("--settle <ms>", "quiet window before concluding a reply").option("--timeout <ms>", "give up if no reply by this many ms").option("--list", "list the probes that would run, then exit (no sends)", false).option("--catalog <file>", "custom catalog JSON file (instead of the built-in catalog)").option("--grep <pattern>", "run only probes whose id matches this regex (case-insensitive)").option("--no-fail", "report failed assertions but still exit 0 (default: exit 1 on failure)").option("-q, --quiet", "suppress progress spinners", false).action(async (opts) => {
+program.command("loop").description("Run the experiment catalog against @mira at a human pace").option("-c, --category <category>", `only this category (${CATEGORIES.join(" | ")})`).option("-m, --max <n>", "max probes this run", "6").option("--confirm", "press a safe ✅ Confirm on generation probes (spends credits)", false).option("--peer <peer>", "'experiment'|'group' for TG_EXPERIMENT_CHAT, or a literal allowlisted peer").option("--gap <ms>", "delay between sends").option("--settle <ms>", "quiet window before concluding a reply").option("--timeout <ms>", "give up if no reply by this many ms").option("--list", "list the probes that would run, then exit (no sends)", false).option("--catalog <file>", "custom catalog JSON file (instead of the built-in catalog)").option("--grep <pattern>", "run only probes whose id matches this regex (case-insensitive)").option("--only <ids>", "run only probes with these comma-separated ids (exact match)").option("--no-fail", "report failed assertions but still exit 0 (default: exit 1 on failure)").option("-q, --quiet", "suppress progress spinners", false).action(async (opts) => {
   await loop({
     category: opts.category,
     max: posInt("max", opts.max),
@@ -1529,6 +1599,7 @@ program.command("loop").description("Run the experiment catalog against @mira at
     list: opts.list,
     catalog: opts.catalog,
     grep: opts.grep,
+    only: opts.only,
     noFail: opts.fail === false,
     quiet: opts.quiet
   });
@@ -1573,7 +1644,21 @@ Examples:
 `);
 if (process.argv.length <= 2) {
   banner(version);
-  program.outputHelp();
+  console.log(`  Drive @mira from your terminal — QA, learn, and assert on its behavior.
+`);
+  console.log(`  ${c.bold("Commands")}`);
+  const cmds = program.commands.filter((cmd) => cmd.name() !== "help");
+  const pad = Math.max(...cmds.map((cmd) => cmd.name().length));
+  for (const cmd of cmds) {
+    console.log(`    ${c.cyan(cmd.name().padEnd(pad))}  ${c.dim(cmd.description())}`);
+  }
+  console.log(`
+  ${c.bold("Quick start")}`);
+  for (const ex of ["login", "doctor", 'send "What can you do?"', "loop --category core"]) {
+    console.log(c.dim(`    $ mira-harness ${ex}`));
+  }
+  console.log(`
+  Run ${c.bold("mira-harness --help")} for all options + examples, or ${c.bold("mira-harness <command> --help")}.`);
   process.exit(0);
 }
 program.parseAsync(process.argv).then(() => process.exit(0)).catch((e) => {

package/dist/commands/report.d.ts

@@ -7,9 +7,9 @@ export type RunRecord = ProbeResult & {
     assert?: Verdict;
 };
 /**
- * Read the JSONL run log into records (malformed lines skipped). Throws ENOENT when
- * the file is absent — callers decide how to surface that. Shared by `report` and
- * `stats` so the two stay in lockstep on the log format.
+ * Read the JSONL run log into records (malformed/wrong-shape lines skipped). Throws
+ * ENOENT when the file is absent — callers decide how to surface that. Shared by
+ * `report` and `stats` so the two stay in lockstep on the log format.
  */
 export declare function loadRunRecords(inFile?: string, category?: string): RunRecord[];
 export declare function buildReport(records: RunRecord[]): string;

package/dist/env.d.ts

@@ -7,6 +7,8 @@
  */
 import "dotenv/config";
 export declare const tgEnv: {
+    /** Telegram api_id — a positive integer. Reject non-numeric/zero up front so
+     *  `doctor` flags a bad value instead of passing NaN into GramJS (cryptic later). */
     apiId: () => number;
     apiHash: () => string;
     /** Empty until `mira-harness login` mints it; required by send/loop. */

package/dist/index.js

@@ -393,6 +393,10 @@ function grepProbes(probes, pattern) {
   const needle = pattern.toLowerCase();
   return probes.filter((p) => p.id.toLowerCase().includes(needle));
 }
+function onlyProbes(probes, idsCsv) {
+  const ids = new Set(idsCsv.split(",").map((s) => s.trim()).filter(Boolean));
+  return probes.filter((p) => ids.has(p.id));
+}
 // src/client.ts
 import { Api, TelegramClient } from "telegram";
 import { EditedMessage } from "telegram/events/EditedMessage.js";
@@ -410,7 +414,14 @@ function req(name) {
   return v;
 }
 var tgEnv = {
-  apiId: () => Number(req("TG_API_ID")),
+  apiId: () => {
+    const raw = req("TG_API_ID");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`TG_API_ID must be a positive integer (got "${raw}") — see .env.example`);
+    }
+    return n;
+  },
   apiHash: () => req("TG_API_HASH"),
   session: () => process.env.TG_SESSION ?? "",
   miraPeer: process.env.MIRA_PEER ?? "mira",
@@ -592,6 +603,9 @@ async function appendRun(result, meta = {}) {
 }
 
 // src/commands/report.ts
+function isRunRecord(x) {
+  return typeof x === "object" && x !== null && Array.isArray(x.messages) && typeof x.sent === "string";
+}
 function loadRunRecords(inFile, category) {
   const path = inFile ? resolve3(process.cwd(), inFile) : RUNS_FILE;
   const raw = readFileSync2(path, "utf8");
@@ -602,7 +616,9 @@ function loadRunRecords(inFile, category) {
     if (!t)
       continue;
     try {
-      records.push(JSON.parse(t));
+      const rec = JSON.parse(t);
+      if (isRunRecord(rec))
+        records.push(rec);
     } catch {}
   }
   return category ? records.filter((r) => r.category === category) : records;

package/dist/mcp.js

@@ -310,6 +310,10 @@ function grepProbes(probes, pattern) {
   const needle = pattern.toLowerCase();
   return probes.filter((p) => p.id.toLowerCase().includes(needle));
 }
+function onlyProbes(probes, idsCsv) {
+  const ids = new Set(idsCsv.split(",").map((s) => s.trim()).filter(Boolean));
+  return probes.filter((p) => ids.has(p.id));
+}
 
 // src/client.ts
 import { Api, TelegramClient } from "telegram";
@@ -420,7 +424,14 @@ function req(name) {
   return v;
 }
 var tgEnv = {
-  apiId: () => Number(req("TG_API_ID")),
+  apiId: () => {
+    const raw = req("TG_API_ID");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`TG_API_ID must be a positive integer (got "${raw}") — see .env.example`);
+    }
+    return n;
+  },
   apiHash: () => req("TG_API_HASH"),
   session: () => process.env.TG_SESSION ?? "",
   miraPeer: process.env.MIRA_PEER ?? "mira",
@@ -603,6 +614,9 @@ async function appendRun(result, meta = {}) {
 }
 
 // src/commands/report.ts
+function isRunRecord(x) {
+  return typeof x === "object" && x !== null && Array.isArray(x.messages) && typeof x.sent === "string";
+}
 function loadRunRecords(inFile, category) {
   const path = inFile ? resolve3(process.cwd(), inFile) : RUNS_FILE;
   const raw = readFileSync2(path, "utf8");
@@ -613,7 +627,9 @@ function loadRunRecords(inFile, category) {
     if (!t)
       continue;
     try {
-      records.push(JSON.parse(t));
+      const rec = JSON.parse(t);
+      if (isRunRecord(rec))
+        records.push(rec);
     } catch {}
   }
   return category ? records.filter((r) => r.category === category) : records;

package/llms.txt

@@ -18,8 +18,8 @@ so the only programmatic path is a userbot (a real user account over MTProto / G
 
 ## CLI commands
 - `doctor` — env / session / connectivity / @mira resolution check (read-only). Run this first.
-- `send [message...]` — one probe → full reply as JSON. Message via arg or stdin. Flags: `--settle <ms> --timeout <ms> --quiet --no-log`.
-- `loop` — run the catalog, paced. Flags: `--category <core|skills|generation|wallet> --max <n> --peer <experiment> --gap <ms> --settle <ms> --timeout <ms> --list --catalog <file.json> --grep <regex> --no-fail --quiet`. Observe-only unless `--confirm`. Grades probes that declare `expect` (PASS/FAIL) and **exits non-zero** if any graded probe fails (`--no-fail` to report without failing) — drops straight into CI. `--grep <regex>` runs only probes whose id matches.
+- `send [message...]` — one probe → full reply as JSON. Message via arg or stdin. Flags: `--settle <ms> --timeout <ms> --quiet --no-log`. Inline assertions (any sets exit 1 on failure): `--expect-reply --expect-json --expect-text <regex> --expect-min-links <n> --expect-min-buttons <n> --expect-webapp --expect-media <kind> --expect-max-ms <ms>`.
+- `loop` — run the catalog, paced. Flags: `--category <core|skills|generation|wallet> --max <n> --peer <experiment> --gap <ms> --settle <ms> --timeout <ms> --list --catalog <file.json> --grep <regex> --no-fail --quiet`. Observe-only unless `--confirm`. Grades probes that declare `expect` (PASS/FAIL) and **exits non-zero** if any graded probe fails (`--no-fail` to report without failing) — drops straight into CI. `--grep <regex>` runs only probes whose id matches; `--only <id1,id2>` selects exact ids.
 - `catalog` — list the catalog, no network. Flags: `--category --catalog <file.json> --json`.
 - `watch` — live-tail @mira's messages, observe-only. Flag: `--peer`.
 - `report` — distill the JSONL run log into Markdown. Flags: `--in <file> --out <file> --category`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mira-harness",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "A CLI + MCP dev-tool for communicating with the @mira Telegram bot — capture its full reply (buttons/links/media) and run a self-driving experiment catalog.",
   "type": "module",
   "bin": {