@letterstory/cli 0.25.6 → 0.26.0

package/README.md

@@ -312,25 +312,34 @@ letterstory series create --name "Secrets, tool by tool" \
 letterstory series backfill <series-id> --collection <uuid>
 ```
 
-## Research and writing kernels
+## Arenas and writing kernels
 
-Two different steps, in this order. The **research agent** reads the live web and writes a
-sourced outline into the post; a **writing kernel** writes the draft from the brief it's
-given and does no retrieval of its own. Both take minutes, so both are start-then-poll:
+Two different steps, in this order. An **arena** — an adversarial cluster of research agents —
+reads the live web and writes a sourced, fact-checked outline (into the post when you pass
+`--article`, otherwise back on the run); a **writing kernel** writes the draft from the brief
+it's given and does no retrieval of its own. Both take minutes, so both are start-then-poll:
 
 ```bash
-# 1. Research the topic and write an outline into the post
-letterstory research start --article <uuid> --topic "payroll solutions" \
-  --url https://example.com/a --must-include "Pricing" --depth fleshed_out
-letterstory research status --article <uuid>       # phases, sources, outline
-letterstory research cancel --article <uuid>
+# 1. Research the topic — hosted on a post (outline written into it) or standalone
+letterstory arena run --article <uuid> --topic "payroll solutions" \
+  --source https://example.com/a --must-include "Pricing" --depth fleshed_out
+letterstory arena run --topic "payroll solutions" --no-wait   # standalone; prints the run id
+letterstory arena run-status <run-id>                  # phases, sources, outline, verification
+letterstory arena cancel <run-id>
+letterstory arena balance                              # arena runs left (direct runs only)
 
 # …with --gate, the run pauses for you to pick the angle:
-letterstory research start --article <uuid> --gate
-letterstory research status --article <uuid>       # status: awaiting_direction + direction_options
-letterstory research direction --article <uuid> --choice 1
-letterstory research direction --article <uuid> --custom "Lead with the hidden costs"
-letterstory research direction --article <uuid> --skip     # let the agent decide
+letterstory arena run --article <uuid> --gate
+letterstory arena run-status <run-id>                  # status: awaiting_direction + direction_options
+letterstory arena direction <run-id> --choice 1
+letterstory arena direction <run-id> --custom "Lead with the hidden costs"
+letterstory arena direction <run-id> --skip            # let the agents decide
+
+# Arenas are callable endpoints with one-file defaults (the org's default arena is "Letterstory"):
+letterstory arena list
+letterstory arena endpoint create --name "Docs research" --defaults '{"depth":"barebones"}'
+letterstory arena endpoint config <arena-id> [--file cfg.json]
+letterstory arena endpoint delete <arena-id> --yes
 
 # 2. Have a kernel write the draft
 letterstory kernel list

package/lib/cli.mjs

@@ -30,7 +30,7 @@ import {
 	cmdOnboarding,
 	cmdSeries,
 	cmdInsights,
-	cmdResearch,
+	cmdArena,
 	cmdAutoPen,
 	cmdCovers,
 	cmdKernel,
@@ -44,7 +44,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.25.6";
+export const VERSION = "0.26.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -64,7 +64,7 @@ const BOOLEAN_FLAGS = new Set([
 	"rebuild",
 	"print-key",
 	"stdin",
-	// `covers generate <id> --regenerate` and `research start --gate --article <id>`
+	// `covers generate <id> --regenerate` and `arena run --gate --article <id>`
 	// both put a value-less flag next to a value: without these entries the parser
 	// hands the following token to the flag and the real argument disappears.
 	"regenerate",
@@ -74,6 +74,7 @@ const BOOLEAN_FLAGS = new Set([
 	"no-auto-deploy",
 	"stock-only",
 	"gate",
+	"no-verify",
 	"skip",
 	// `phantom-onboard domain` / `admin create-org --onboard` switches.
 	"watch",
@@ -277,14 +278,25 @@ Strategy & onboarding:
   series create --name <n> --description <d> [--coverage a,b,c] [--collection <uuid>] [--template <key>]
   series backfill <series-id> [--collection <uuid>]    Reconstruct a series from existing posts
 
-Research agent (deep research -> outline written into the post):
-  research start --article <uuid> [--topic <text>] [--url <url> …] [--must-include <text> …]
-                 [--depth barebones|fleshed_out] [--gate]
-                                                        Start a run; takes minutes
-  research status --article <uuid>                      Phases, sources, outline
-  research direction --article <uuid> (--choice <n> | --custom <text> | --skip)
+Arenas (adversarial clusters of research agents -> a sourced, fact-checked outline):
+  arena run --topic <text> [--source <url> …] [--must-include <text> …] [--depth barebones|fleshed_out]
+            [--gate] [--no-verify] [--provider native|exa|youcom|firecrawl] [--mention off|subtle|woven]
+            [--context-file ctx.json] [--block <name> …] [--block-domain <domain> …]
+            [--arena <arena-id>] [--article <uuid>] [--no-wait]
+                                                        Start a run and follow it. --article makes
+                                                        it HOSTED (outline written into that post,
+                                                        its title is the default topic); otherwise
+                                                        everything comes back on the run.
+  arena run-status <run-id>                            Phases, sources, outline, verification
+  arena runs [--arena <id>] [--limit <n>]              Recent runs (origin, caller, verification)
+  arena direction <run-id> (--choice <n> | --custom <text> | --skip)
                                                         Answer the --gate pause
-  research cancel --article <uuid>                      Cancel a run in flight
+  arena cancel <run-id>                                Cancel a run in flight
+  arena balance                                        Arena runs left on this org
+  arena list                                           Your arenas (callable endpoints)
+  arena endpoint create --name <n> [--defaults '<json>'|--defaults-file <path>]
+  arena endpoint config <arena-id> [--file cfg.json]   Print the one-file config, or replace it
+  arena endpoint delete <arena-id> --yes
 
 Auto-Pen (research -> kernel -> Enhance, in one run — and the ONLY path that
 applies a collection's content template; kernel run does not):
@@ -594,7 +606,7 @@ const CLIENT_COMMANDS = {
 	onboarding: cmdOnboarding,
 	series: cmdSeries,
 	insights: cmdInsights,
-	research: cmdResearch,
+	arena: cmdArena,
 	autopen: cmdAutoPen,
 	covers: cmdCovers,
 	kernel: cmdKernel,

package/lib/commands/arena.mjs

@@ -0,0 +1,320 @@
+// `arena` — Arenas, adversarial clusters of research agents, on both of their doors.
+//
+// An arena turns a TOPIC into a sourced, fact-checked outline: gather agents for the topic
+// and for every named subject it finds, a reader, a direction agent proposing competing
+// theses, a synthesis gated on a ledger of sourced figures, and a verifier that argues
+// every claim against the sources and the live web. Minutes long, so `arena run` submits
+// and then follows the run unless you tell it not to (`--no-wait`); `arena run-status`
+// picks it up later. Pass `--article <id>` to make it a HOSTED run (the outline is written
+// into that post — what the post editor's Research panel does); omit it and everything
+// comes back on the run. Every direct run spends one arena run (`arena balance`).
+
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.mjs";
+import {
+	flagStr,
+	flagNum,
+	flagBool,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	toolField,
+	followJob,
+	argsFromFlags,
+} from "./shared.mjs";
+
+/** `--<flag> <path>` → the file's parsed JSON, or undefined when the flag is not set. */
+function readJsonFileFlag(flags, flag) {
+	const path = flagStr(flags[flag]);
+	if (path === undefined) return undefined;
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new CliError(
+			`Could not read --${flag} ${path}: ${error instanceof Error ? error.message : String(error)}`
+		);
+	}
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw new CliError(`--${flag} ${path} is not valid JSON.`);
+	}
+}
+
+/** `--<flag> '<json>'` inline, or `--<flag>-file <path>` → a JSON object, or undefined. */
+function readJsonObjectFlag(flags, name) {
+	const inline = flagStr(flags[name]);
+	if (inline !== undefined) {
+		let parsed;
+		try {
+			parsed = JSON.parse(inline);
+		} catch (err) {
+			throw new CliError(`--${name} is not valid JSON: ${err.message}`);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+			throw new CliError(`--${name} must be a JSON object`);
+		return parsed;
+	}
+	return readJsonFileFlag(flags, `${name}-file`);
+}
+
+/** The per-run knobs, shared by run_arena and the arena's own defaults. */
+const RUN_OPTIONS = {
+	depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
+	direction_gate: { flag: "gate", type: "bool" },
+	provider: { flag: "provider", enum: ["native", "exa", "youcom", "firecrawl"] },
+	// --no-verify turns the fact-check off; nothing sent otherwise (the default is on).
+	verify: { value: (flags) => (flags["no-verify"] === true ? false : undefined) },
+	mention_degree: { flag: "mention", enum: ["off", "subtle", "woven"] },
+	// Positioning as data — a file, not flags: `--context-file ctx.json` of
+	// {manifesto, stances[], priority_topics[], avoid_topics[], identity{is[],is_not[],one_liner}}.
+	context: { value: (flags) => readJsonObjectFlag(flags, "context") },
+	blocked_mentions: { flag: "block", type: "list" },
+	blocked_domains: { flag: "block-domain", type: "list" },
+};
+
+/**
+ * How every command in this file sources its tool inputs — see `argsFromFlags` in
+ * shared.mjs and `scripts/parity-check.ts`, which compares these keys against each tool's
+ * published input schema.
+ */
+export const ARGS = {
+	run_arena: {
+		arena_id: { flag: "arena" },
+		topic: "topic",
+		source_urls: { flag: "source", type: "list" },
+		must_include: { flag: "must-include", type: "list" },
+		shape: { value: (flags) => readJsonObjectFlag(flags, "shape") },
+		existing_content: { value: (flags) => flagStr(flags["existing-content"]) },
+		article_id: { flag: "article" },
+		...RUN_OPTIONS,
+	},
+	get_arena_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	list_arena_runs: {
+		arena_id: { flag: "arena" },
+		limit: { flag: "limit", type: "num" },
+	},
+	submit_arena_direction: {
+		run_id: { positional: 0, label: "run-id", required: true },
+		choice: { flag: "choice", type: "num" },
+		custom: "custom",
+		skip: { flag: "skip", type: "bool" },
+	},
+	cancel_arena_run: {
+		run_id: { positional: 0, label: "run-id", required: true },
+	},
+	get_arena_run_balance: {},
+	list_arenas: {},
+	create_arena: {
+		name: { flag: "name", required: true },
+		defaults: { value: (flags) => readJsonObjectFlag(flags, "defaults") },
+	},
+	delete_arena: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+	},
+	// The arena's configuration as ONE file: `arena endpoint config <id>` prints it,
+	// `arena endpoint config <id> --file cfg.json` replaces it with the file's document.
+	get_arena_config: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+	},
+	set_arena_config: {
+		arena_id: { positional: 1, label: "arena-id", required: true },
+		config: { value: (flags) => readJsonFileFlag(flags, "file") },
+	},
+};
+
+export async function cmdArena(ctx) {
+	const sub = ctx.positionals[0];
+	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case "run":
+		case "start":
+			return arenaRun(rest);
+		case "run-status":
+		case "status":
+			return arenaRunStatus(rest);
+		case "runs":
+			return arenaRuns(rest);
+		case "direction":
+			return arenaDirection(rest);
+		case "cancel":
+			return arenaCancel(rest);
+		case "balance":
+			return arenaBalance(rest);
+		case "list":
+		case "ls":
+		case "endpoints":
+			return arenaList(rest);
+		case "endpoint":
+			return arenaEndpoint(rest);
+		default:
+			throw new CliError(
+				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, direction, cancel, balance, list, endpoint`
+			);
+	}
+}
+
+/** A run takes minutes; this is about feeling alive. */
+const POLL_INTERVAL_MS = 15_000;
+/** Stop following after this; the run keeps going and `run-status` picks it up. */
+const POLL_CEILING_MS = 30 * 60 * 1000;
+
+function isActive(status) {
+	return status === "running";
+}
+
+async function arenaRun(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.run_arena, flags, ctx.positionals);
+	if (args.topic === undefined && args.article_id === undefined) {
+		throw new CliError("Provide --topic <text> (or --article <id> to research a post by its title).");
+	}
+	const result = await client.callTool("run_arena", args);
+	const runId = toolField(result, "run_id");
+	if (!runId) {
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (flags["no-wait"] === true) {
+		ok(ctx, `Run started as ${runId}. Follow it with: ${ctx.bin} arena run-status ${runId}`);
+		printResult(io, flags, result);
+		return 0;
+	}
+
+	ok(ctx, `Run started as ${runId}. Waiting — this keeps running on the server if you stop.`);
+	let lastStatus;
+	const { settled, value: polled } = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_arena_run", { run_id: runId });
+			lastStatus = toolField(r?.run ?? r, "status");
+			return { done: !!lastStatus && !isActive(lastStatus), value: r };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
+
+	if (!settled) {
+		ok(ctx, `Still running after 30 minutes. Follow it with: ${ctx.bin} arena run-status ${runId}`);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	if (lastStatus === "awaiting_direction") {
+		ok(
+			ctx,
+			`Paused for a direction. Answer with: ${ctx.bin} arena direction ${runId} (--choice <n> | --custom <text> | --skip)`
+		);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	ok(ctx, `Run ${lastStatus}.`);
+	// The operator waited for the OUTLINE; print it, not the envelope. --json gets it all.
+	printResult(io, flags, polled, (v) =>
+		typeof v?.run?.outline === "string" ? v.run.outline : JSON.stringify(v, null, 2)
+	);
+	return lastStatus === "done" ? 0 : 1;
+}
+
+async function arenaRunStatus(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.get_arena_run, flags, ctx.positionals);
+	const result = await client.callTool("get_arena_run", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaRuns(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.list_arena_runs, flags, ctx.positionals);
+	const result = await client.callTool("list_arena_runs", args);
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaDirection(ctx) {
+	const { client, flags, io } = ctx;
+	const runId = requirePositional(ctx.positionals, 0, "run-id");
+	const choice = flagNum(flags.choice);
+	const custom = flagStr(flags.custom);
+	const skip = flagBool(flags.skip);
+	const given = [choice !== undefined, custom !== undefined, skip].filter(Boolean).length;
+	if (given !== 1) {
+		throw new CliError("Provide exactly one of --choice <n>, --custom <text>, --skip");
+	}
+	const args = compact({ run_id: runId, choice, custom, skip: skip ? true : undefined });
+	const result = await client.callTool("submit_arena_direction", args);
+	ok(ctx, "Direction recorded; the run resumed into synthesis.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaCancel(ctx) {
+	const { client, flags, io } = ctx;
+	const args = argsFromFlags(ARGS.cancel_arena_run, flags, ctx.positionals);
+	const result = await client.callTool("cancel_arena_run", args);
+	ok(ctx, result?.cancelled ? "Arena run cancelled." : "No run was in flight.");
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaBalance(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_arena_run_balance", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+async function arenaList(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("list_arenas", {});
+	printResult(io, flags, result);
+	return 0;
+}
+
+/**
+ * `arena endpoint create|delete|config` — the arena's own CRUD, and its configuration as
+ * one file (the same document `get_arena_config` returns and `set_arena_config` accepts).
+ */
+async function arenaEndpoint(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "create" || action === "new") {
+		const args = argsFromFlags(ARGS.create_arena, flags, positionals);
+		const result = await client.callTool("create_arena", args);
+		ok(ctx, `Created arena "${args.name}".`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "delete" || action === "rm") {
+		const id = requirePositional(positionals, 1, "arena-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} arena endpoint delete ${id} --yes`);
+			return 1;
+		}
+		const result = await client.callTool("delete_arena", argsFromFlags(ARGS.delete_arena, flags, positionals));
+		ok(ctx, "Arena deleted.");
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "config") {
+		const id = requirePositional(positionals, 1, "arena-id");
+		if (flagStr(flags.file) === undefined) {
+			const result = await client.callTool(
+				"get_arena_config",
+				argsFromFlags(ARGS.get_arena_config, flags, positionals)
+			);
+			// The document itself, so `> cfg.json` round-trips into `--file cfg.json`.
+			printResult(io, flags, result, (r) => JSON.stringify(r?.config ?? r, null, 2));
+			return 0;
+		}
+		const args = argsFromFlags(ARGS.set_arena_config, flags, positionals);
+		const result = await client.callTool("set_arena_config", args);
+		ok(ctx, `Replaced the configuration of arena ${id}.`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	throw new CliError(`Unknown arena endpoint action: ${action ?? "(none)"}. Try: create, delete, config`);
+}

package/lib/commands.mjs

@@ -19,7 +19,7 @@ export * from "./commands/probes.mjs";
 export * from "./commands/series.mjs";
 export * from "./commands/insights.mjs";
 export * from "./commands/covers.mjs";
-export * from "./commands/research.mjs";
+export * from "./commands/arena.mjs";
 export * from "./commands/autopen.mjs";
 export * from "./commands/kernel.mjs";
 export * from "./commands/phantom-job.mjs";

package/package.json

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

package/lib/commands/research.mjs

@@ -1,87 +0,0 @@
-// `research` — the deep-research agent: read supplied URLs, search the live web, and
-// write a sourced outline into a post. Same shape as `kernel`: a run takes minutes, so
-// `start` returns as soon as the run is queued and `status` checks on demand. Writing
-// kernels do NOT research — `research start` then `kernel run` is the full pipeline.
-
-import { CliError } from "../client.mjs";
-import { flagStr, flagNum, flagBool, requireFlag, printResult, compact, ok, argsFromFlags } from "./shared.mjs";
-
-/** See `argsFromFlags` in shared.mjs; `scripts/parity-check.ts` diffs these keys against the tool. */
-export const ARGS = {
-	start_research: {
-		article_id: { flag: "article", required: true },
-		topic: "topic",
-		source_urls: { flag: "url", type: "list" },
-		must_include: { flag: "must-include", type: "list" },
-		depth: { flag: "depth", enum: ["barebones", "fleshed_out"] },
-		direction_gate: { flag: "gate", type: "bool" },
-	},
-};
-
-export async function cmdResearch(ctx) {
-	const sub = ctx.positionals[0];
-	const rest = { ...ctx, positionals: ctx.positionals.slice(1) };
-	switch (sub) {
-		case "start":
-		case "run":
-			return researchStart(rest);
-		case "status":
-			return researchStatus(rest);
-		case "direction":
-			return researchDirection(rest);
-		case "cancel":
-			return researchCancel(rest);
-		default:
-			throw new CliError(
-				`Unknown research subcommand: ${sub ?? "(none)"}. Try: start, status, direction, cancel`
-			);
-	}
-}
-
-async function researchStart(ctx) {
-	const { client, flags, io } = ctx;
-	const args = argsFromFlags(ARGS.start_research, flags, ctx.positionals);
-	const result = await client.callTool("start_research", args);
-	ok(ctx, `Research started. Check progress with: research status --article ${args.article_id}`);
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function researchStatus(ctx) {
-	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const result = await client.callTool("get_research_status", { article_id: article });
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function researchDirection(ctx) {
-	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const choice = flagNum(flags.choice);
-	const custom = flagStr(flags.custom);
-	const skip = flagBool(flags.skip);
-	const given = [choice !== undefined, custom !== undefined, skip].filter(Boolean).length;
-	if (given !== 1) {
-		throw new CliError("Provide exactly one of --choice <n>, --custom <text>, --skip");
-	}
-	const args = compact({
-		article_id: article,
-		choice,
-		custom,
-		skip: skip ? true : undefined,
-	});
-	const result = await client.callTool("submit_research_direction", args);
-	ok(ctx, "Direction recorded; the run resumed into synthesis.");
-	printResult(io, flags, result);
-	return 0;
-}
-
-async function researchCancel(ctx) {
-	const { client, flags, io } = ctx;
-	const article = requireFlag(flags, "article");
-	const result = await client.callTool("cancel_research", { article_id: article });
-	ok(ctx, result?.cancelled ? "Research run cancelled." : "No research run was in flight.");
-	printResult(io, flags, result);
-	return 0;
-}