@letterstory/cli 0.25.4 → 0.25.6

package/lib/cli.mjs

@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.25.4";
+export const VERSION = "0.25.6";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -455,12 +455,22 @@ Seers (event-driven signals -> drafts):
   seers list                                           List seers with recent activity
   seers get <seer-id>                                  One seer's full config + poll state
   seers providers                                      Provider catalog: config fields + behavior keys
-  seers create --name <n> --collection <uuid> --provider <p>
+  seers create --name <n> --provider <p> [--collection <uuid>]
                [--mode suggest|auto] [--interval <min>] [--config '<json>'|--config-file <path>]
-  seers update <seer-id> [--name] [--collection] [--mode] [--enabled true|false]
-               [--interval <min>] [--config '<json>'|--config-file <path>]
+                                                      --collection is optional: omit it for a
+                                                      detect-only seer (scans + judges, never
+                                                      produces). --mode auto requires one.
+  seers update <seer-id> [--name] [--collection <uuid> | --clear-collection] [--mode]
+               [--enabled true|false] [--interval <min>] [--config '<json>'|--config-file <path>]
   seers delete <seer-id> --yes
-  seers run <seer-id>                                  Poll + produce now (can take minutes; spends AI budget)
+  seers run <seer-id> [--dry-run] [--no-produce] [--async]
+                                                       Run now — THE DOOR (one seer run from the balance).
+                                                       --dry-run: scan + judge, persist nothing, print signals
+                                                       --no-produce: detect + record events only
+                                                       --async: queue for the heartbeat, print a run id
+  seers run-status <run-id>                            One run: status, counts, constraints, verification
+  seers runs [--seer <seer-id>] [--limit <n>]          Recent runs (origin, caller, verification)
+  seers balance                                        Seer runs granted / used / available
   seers events <seer-id> [--limit <n>] [--offset <n>]  Detected signals w/ dedup + relevance
   seers dismiss <seer-id> <event-id>                   Dismiss a signal (feeds the relevance judge)
   seers headlines [--collection <uuid>]                Seer-sourced suggestion feed

package/lib/commands/seers.mjs

@@ -7,12 +7,24 @@
 // Connections are both headless: `seers connect github --token` (a PAT) and
 // `seers connect notion --token` (a Notion internal-integration secret; run
 // `seers connect notion` with no token for how to mint one and which pages to share).
-// One thing to know: `seers run` executes synchronously server-side (news/regulation
-// web scans can take minutes) and spends model budget — it is usage-gated per org.
+// `seers run` is THE DOOR (lib/seers/run.ts): a direct, metered run (`seers balance`).
+// Synchronous by default — news/regulation web scans can take minutes; pass --async to
+// queue it and poll with `seers run-status`, --dry-run to see what it would record
+// without recording anything, --no-produce to detect and record events only.
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { CliError } from "../client.mjs";
-import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok, argsFromFlags } from "./shared.mjs";
+import { flagStr, flagBool, requirePositional, printResult, ok, argsFromFlags } from "./shared.mjs";
+
+// A single-value flag the API clears with an explicit `null` (same idiom as
+// strategy.mjs's clearableList): `--clear-collection` sends null, `--collection <uuid>`
+// sends it, neither sends nothing (no change).
+const clearableValue = (flag, clearFlag) => ({
+	value: (flags) => {
+		if (flags[clearFlag]) return null;
+		return flagStr(flags[flag]);
+	},
+});
 
 /**
  * How the ratcheted commands in this file source their tool inputs — see `argsFromFlags` in
@@ -20,11 +32,93 @@ import { flagStr, flagNum, flagBool, requirePositional, printResult, compact, ok
  * ratchet and stays in UNMAPPED_TOOLS; that list only shrinks.
  */
 export const ARGS = {
+	// THE DOOR. `seers run <id>` — a direct, metered run. `--dry-run` scans + judges and
+	// persists nothing (returns the signals it would have recorded, with verdicts);
+	// `--no-produce` detects and records events only; `--async` queues it and prints a
+	// run id to poll with `seers run-status`.
 	run_seer: {
 		seer_id: { positional: 0, label: "seer-id", required: true },
+		dry_run: { flag: "dry-run", type: "bool" },
+		produce: { value: (flags) => (flags["no-produce"] === true ? false : undefined) },
+		async: { flag: "async", type: "bool" },
+	},
+	get_seer_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	list_seer_runs: {
+		seer_id: { flag: "seer" },
+		limit: { flag: "limit", type: "num" },
+	},
+	get_seer_run_balance: {},
+	list_seers: {},
+	get_seer: {
+		seer_id: { positional: 0, label: "seer-id", required: true },
+	},
+	create_seer: {
+		name: { flag: "name", required: true },
+		// Optional (2026-09-18): omit it for a detect-only seer — it can scan and judge
+		// forever but never produce (auto mode is rejected without one).
+		collection_id: { flag: "collection" },
+		provider: { flag: "provider", required: true },
+		mode: { flag: "mode", enum: ["suggest", "auto"] },
+		poll_interval_minutes: { flag: "interval", type: "num" },
+		// The whole config document — provider source params plus the behavior keys
+		// (auto_draft_scope, template_key, mention_degree, kernel_family, relevance{…}).
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") ?? {} },
+	},
+	update_seer: {
+		seer_id: { positional: 0, label: "seer-id", required: true },
+		name: { flag: "name" },
+		// --collection <uuid> sets it, --clear-collection sends null (the seer becomes
+		// detect-only — rejected if it's mode "auto"), neither leaves it unchanged.
+		collection_id: clearableValue("collection", "clear-collection"),
+		mode: { flag: "mode", enum: ["suggest", "auto"] },
+		enabled: { value: (flags) => readEnabledFlag(flags) },
+		poll_interval_minutes: { flag: "interval", type: "num" },
+		config: { value: (flags) => readJsonObjectFlag(flags, "config") },
+	},
+	delete_seer: {
+		seer_id: { positional: 0, label: "seer-id", required: true },
+	},
+	list_seer_events: {
+		seer_id: { positional: 0, label: "seer-id", required: true },
+		limit: { flag: "limit", type: "num" },
+		offset: { flag: "offset", type: "num" },
+	},
+	dismiss_seer_event: {
+		seer_id: { positional: 0, label: "seer-id", required: true },
+		event_id: { positional: 1, label: "event-id", required: true },
+	},
+	list_seer_headlines: {
+		collection_id: { flag: "collection" },
+		limit: { flag: "limit", type: "num" },
+		offset: { flag: "offset", type: "num" },
+	},
+	list_held_drafts: {
+		collection_id: { flag: "collection" },
+	},
+	resolve_held_draft: {
+		article_id: { positional: 0, label: "article-id", required: true },
+		// `seers release <id>` / `seers discard <id>` — the subcommand IS the action.
+		action: { value: (_flags, _positionals, extra) => extra.action },
+	},
+	list_seer_providers: {},
+	get_seer_connections: {},
+	set_github_connection: {
+		access_token: { flag: "token", required: true },
+	},
+	set_notion_connection: {
+		access_token: { flag: "token", required: true },
 	},
 };
 
+function readEnabledFlag(flags) {
+	const enabledRaw = flagStr(flags.enabled);
+	if (enabledRaw === undefined) return undefined;
+	if (enabledRaw !== "true" && enabledRaw !== "false") throw new CliError('--enabled must be "true" or "false"');
+	return enabledRaw === "true";
+}
+
 export async function cmdSeers(ctx) {
 	const sub = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
@@ -45,6 +139,13 @@ export async function cmdSeers(ctx) {
 			return seersDelete(rest);
 		case "run":
 			return seersRun(rest);
+		case "run-status":
+		case "run-get":
+			return seersRunStatus(rest);
+		case "runs":
+			return seersRuns(rest);
+		case "balance":
+			return seersBalance(rest);
 		case "events":
 			return seersEvents(rest);
 		case "dismiss":
@@ -69,7 +170,7 @@ export async function cmdSeers(ctx) {
 			return seersApply(rest);
 		default:
 			throw new CliError(
-				`Unknown seers subcommand: ${sub ?? "(none)"}. Try: list, get, create, update, delete, run, events, dismiss, headlines, held, release, discard, providers, connections, connect, export, apply`
+				`Unknown seers subcommand: ${sub ?? "(none)"}. Try: list, get, create, update, delete, run, run-status, runs, balance, events, dismiss, headlines, held, release, discard, providers, connections, connect, export, apply`
 			);
 	}
 }
@@ -113,7 +214,7 @@ function formatSeerLine(s) {
 
 async function seersList(ctx) {
 	const { client, flags, io } = ctx;
-	const result = await client.callTool("list_seers", {});
+	const result = await client.callTool("list_seers", argsFromFlags(ARGS.list_seers, flags));
 	printResult(io, flags, result, (r) => {
 		const lines = (r.seers ?? []).map(formatSeerLine);
 		if (!lines.length) lines.push("No seers yet. Create one with `seers create` (see `seers providers`).");
@@ -128,36 +229,15 @@ async function seersList(ctx) {
 
 async function seersGet(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const seerId = requirePositional(positionals, 0, "seer-id");
-	const result = await client.callTool("get_seer", { seer_id: seerId });
+	const result = await client.callTool("get_seer", argsFromFlags(ARGS.get_seer, flags, positionals));
 	printResult(io, flags, result);
 	return 0;
 }
 
-function seerWriteArgsFromFlags(flags) {
-	const enabledRaw = flagStr(flags.enabled);
-	if (enabledRaw !== undefined && enabledRaw !== "true" && enabledRaw !== "false") {
-		throw new CliError('--enabled must be "true" or "false"');
-	}
-	return compact({
-		name: flagStr(flags.name),
-		collection_id: flagStr(flags.collection),
-		mode: flagStr(flags.mode),
-		poll_interval_minutes: flagNum(flags.interval),
-		enabled: enabledRaw === undefined ? undefined : enabledRaw === "true",
-		config: readJsonObjectFlag(flags, "config"),
-	});
-}
-
 async function seersCreate(ctx) {
 	const { client, flags, io } = ctx;
-	const args = seerWriteArgsFromFlags(flags);
-	if (!args.name) throw new CliError("Missing required --name");
-	if (!args.collection_id) throw new CliError("Missing required --collection <uuid>");
-	const provider = flagStr(flags.provider);
-	if (!provider) throw new CliError("Missing required --provider (run `seers providers` for the catalog)");
-	delete args.enabled; // create has no enabled field; new seers start enabled
-	const result = await client.callTool("create_seer", { ...args, provider, config: args.config ?? {} });
+	const args = argsFromFlags(ARGS.create_seer, flags);
+	const result = await client.callTool("create_seer", args);
 	ok(ctx, "Seer created.");
 	printResult(io, flags, result, (r) => formatSeerLine(r.seer));
 	return 0;
@@ -165,12 +245,11 @@ async function seersCreate(ctx) {
 
 async function seersUpdate(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const seerId = requirePositional(positionals, 0, "seer-id");
-	const args = seerWriteArgsFromFlags(flags);
-	if (Object.keys(args).length === 0) {
+	const args = argsFromFlags(ARGS.update_seer, flags, positionals);
+	if (Object.keys(args).length <= 1) {
 		throw new CliError("Nothing to update — pass --name/--collection/--mode/--enabled/--interval/--config");
 	}
-	const result = await client.callTool("update_seer", { seer_id: seerId, ...args });
+	const result = await client.callTool("update_seer", args);
 	ok(ctx, "Seer updated.");
 	printResult(io, flags, result, (r) => formatSeerLine(r.seer));
 	return 0;
@@ -178,26 +257,84 @@ async function seersUpdate(ctx) {
 
 async function seersDelete(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const seerId = requirePositional(positionals, 0, "seer-id");
 	if (!flagBool(flags.yes)) throw new CliError("Deleting a seer removes its detected events. Re-run with --yes.");
-	const result = await client.callTool("delete_seer", { seer_id: seerId });
+	const result = await client.callTool("delete_seer", argsFromFlags(ARGS.delete_seer, flags, positionals));
 	ok(ctx, "Seer deleted.");
 	printResult(io, flags, result);
 	return 0;
 }
 
+function describeRun(r) {
+	const run = r.run ?? r;
+	const counts = `Detected ${r.detected ?? run.detected ?? 0}, produced ${r.produced ?? run.produced ?? 0} (auto-drafted ${
+		r.auto_drafted ?? run.auto_drafted ?? 0
+	}, suggested-only ${r.suggested_only ?? run.suggested_only ?? 0}, dismissed ${r.dismissed ?? run.dismissed ?? 0}).`;
+	const lines = [counts];
+	if (run.run_id)
+		lines.push(
+			`Run ${run.run_id} [${run.status}] origin=${run.origin} dry_run=${run.dry_run} produce=${run.produce}`
+		);
+	if (run.verification?.checks?.length) {
+		lines.push(
+			"Verification: " +
+				run.verification.checks.map((c) => `${c.id}=${c.verdict}${c.detail ? ` (${c.detail})` : ""}`).join("; ")
+		);
+	}
+	if (Array.isArray(run.signals) && run.signals.length) {
+		lines.push("", "Signals (dry run — nothing recorded):");
+		for (const sig of run.signals) {
+			lines.push(
+				`  [${sig.relevance?.decision ?? "?"} ${
+					typeof sig.relevance?.score === "number" ? sig.relevance.score.toFixed(2) : "-"
+				}] ${sig.title}${sig.url ? `  ${sig.url}` : ""}`
+			);
+		}
+	}
+	return lines.join("\n");
+}
+
 async function seersRun(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const args = argsFromFlags(ARGS.run_seer, flags, positionals);
-	ok(ctx, "Polling now — web-scan providers can take a few minutes…");
+	if (!args.async)
+		ok(ctx, `${args.dry_run ? "Dry run" : "Polling now"} — web-scan providers can take a few minutes…`);
 	const result = await client.callTool("run_seer", args);
-	printResult(
-		io,
-		flags,
-		result,
-		(r) =>
-			`Detected ${r.detected}, produced ${r.produced} (auto-drafted ${r.auto_drafted}, suggested-only ${r.suggested_only}, dismissed ${r.dismissed}).`
-	);
+	if (result?.status === "queued" && result?.run_id) {
+		ok(ctx, `Run queued as ${result.run_id}. Poll it with: ${ctx.bin} seers run-status ${result.run_id}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	printResult(io, flags, result, describeRun);
+	return 0;
+}
+
+async function seersRunStatus(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const result = await client.callTool("get_seer_run", argsFromFlags(ARGS.get_seer_run, flags, positionals));
+	printResult(io, flags, result, describeRun);
+	return 0;
+}
+
+async function seersRuns(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_seer_runs", argsFromFlags(ARGS.list_seer_runs, flags));
+	printResult(io, flags, result, (r) => {
+		const lines = (r.runs ?? []).map(
+			(run) =>
+				`${run.run_id}  [${run.status}] ${run.created_at}  ${run.seer_name ?? run.seer_id ?? "?"}  origin=${run.origin}${
+					run.dry_run ? " dry" : ""
+				}  detected=${run.detected ?? "-"} produced=${run.produced ?? "-"}`
+		);
+		if (!lines.length) lines.push("No seer runs yet.");
+		return lines.join("\n");
+	});
+	return 0;
+}
+
+async function seersBalance(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_seer_run_balance", argsFromFlags(ARGS.get_seer_run_balance, flags));
+	printResult(io, flags, result, (r) => `Seer runs: ${r.available} available (${r.used} of ${r.granted} used).`);
 	return 0;
 }
 
@@ -205,8 +342,7 @@ async function seersRun(ctx) {
 
 async function seersEvents(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const seerId = requirePositional(positionals, 0, "seer-id");
-	const args = compact({ seer_id: seerId, limit: flagNum(flags.limit), offset: flagNum(flags.offset) });
+	const args = argsFromFlags(ARGS.list_seer_events, flags, positionals);
 	const result = await client.callTool("list_seer_events", args);
 	printResult(io, flags, result, (r) => {
 		const lines = (r.events ?? []).map((e) => {
@@ -223,9 +359,10 @@ async function seersEvents(ctx) {
 
 async function seersDismiss(ctx) {
 	const { client, positionals, flags, io } = ctx;
-	const seerId = requirePositional(positionals, 0, "seer-id");
-	const eventId = requirePositional(positionals, 1, "event-id");
-	const result = await client.callTool("dismiss_seer_event", { seer_id: seerId, event_id: eventId });
+	const result = await client.callTool(
+		"dismiss_seer_event",
+		argsFromFlags(ARGS.dismiss_seer_event, flags, positionals)
+	);
 	ok(ctx, "Event dismissed.");
 	printResult(io, flags, result);
 	return 0;
@@ -233,12 +370,7 @@ async function seersDismiss(ctx) {
 
 async function seersHeadlines(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({
-		collection_id: flagStr(flags.collection),
-		limit: flagNum(flags.limit),
-		offset: flagNum(flags.offset),
-	});
-	const result = await client.callTool("list_seer_headlines", args);
+	const result = await client.callTool("list_seer_headlines", argsFromFlags(ARGS.list_seer_headlines, flags));
 	printResult(io, flags, result, (r) => {
 		const lines = (r.headlines ?? []).map(
 			(h) => `${h.id}  [${h.status}]  ${h.title ?? h.headline ?? "(untitled)"}`
@@ -251,8 +383,7 @@ async function seersHeadlines(ctx) {
 
 async function seersHeld(ctx) {
 	const { client, flags, io } = ctx;
-	const args = compact({ collection_id: flagStr(flags.collection) });
-	const result = await client.callTool("list_held_drafts", args);
+	const result = await client.callTool("list_held_drafts", argsFromFlags(ARGS.list_held_drafts, flags));
 	printResult(io, flags, result, (r) => {
 		const lines = (r.drafts ?? []).map(
 			(d) => `${d.articleId}  [${d.kind}] ${d.title} — ${d.reason} (dropped ${d.dropped}, unsure ${d.unsure})`
@@ -266,8 +397,10 @@ async function seersHeld(ctx) {
 
 async function seersResolveHeld(ctx, action) {
 	const { client, positionals, flags, io } = ctx;
-	const articleId = requirePositional(positionals, 0, "article-id");
-	const result = await client.callTool("resolve_held_draft", { article_id: articleId, action });
+	const result = await client.callTool(
+		"resolve_held_draft",
+		argsFromFlags(ARGS.resolve_held_draft, flags, positionals, { action })
+	);
 	ok(ctx, action === "release" ? "Draft released — it can publish through the normal path." : "Draft discarded.");
 	printResult(io, flags, result);
 	return 0;
@@ -277,7 +410,7 @@ async function seersResolveHeld(ctx, action) {
 
 async function seersProviders(ctx) {
 	const { client, flags, io } = ctx;
-	const result = await client.callTool("list_seer_providers", {});
+	const result = await client.callTool("list_seer_providers", argsFromFlags(ARGS.list_seer_providers, flags));
 	printResult(io, flags, result, (r) => {
 		const blocks = (r.providers ?? []).map((p) => {
 			const fields = p.fields
@@ -296,7 +429,7 @@ async function seersProviders(ctx) {
 
 async function seersConnections(ctx) {
 	const { client, flags, io } = ctx;
-	const result = await client.callTool("get_seer_connections", {});
+	const result = await client.callTool("get_seer_connections", argsFromFlags(ARGS.get_seer_connections, flags));
 	printResult(io, flags, result, (r) => {
 		const gh = r.github.connected
 			? `GitHub: connected as ${r.github.account_login} (${r.github.connected_at})`
@@ -313,9 +446,11 @@ async function seersConnect(ctx) {
 	const which = ctx.positionals[0];
 	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
 	if (which === "github") {
-		const token = flagStr(rest.flags.token);
-		if (!token) throw new CliError("Missing required --token <github-pat> (repo read access)");
-		const result = await rest.client.callTool("set_github_connection", { access_token: token });
+		if (!flagStr(rest.flags.token)) throw new CliError("Missing required --token <github-pat> (repo read access)");
+		const result = await rest.client.callTool(
+			"set_github_connection",
+			argsFromFlags(ARGS.set_github_connection, rest.flags)
+		);
 		ok(rest, "GitHub connected.");
 		printResult(rest.io, rest.flags, result);
 		return 0;
@@ -340,7 +475,10 @@ async function seersConnect(ctx) {
 			);
 			return 0;
 		}
-		const result = await rest.client.callTool("set_notion_connection", { access_token: token });
+		const result = await rest.client.callTool(
+			"set_notion_connection",
+			argsFromFlags(ARGS.set_notion_connection, rest.flags)
+		);
 		ok(rest, `Notion connected${result.workspace_name ? ` to ${result.workspace_name}` : ""}.`);
 		ok(rest, "Reminder: the integration only watches pages you've shared with it in Notion.");
 		printResult(rest.io, rest.flags, result);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.25.4",
+	"version": "0.25.6",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",