@letterstory/cli 0.52.0 → 0.54.0

package/README.md

@@ -358,6 +358,7 @@ letterstory admin tuning candidate <service-kernel-id> --file hazel.json --note
 letterstory admin tuning compare --title "Echo vs live" --candidates Hazel:21,Aspen:20
 letterstory admin tuning comparison <id>               # per-measure verdicts (better / worse / within noise / refused)
 letterstory admin tuning picks <id>                    # the blind queue; then: admin tuning pick <id> --cell <key> --pick left|right|tie
+letterstory admin tuning reading-list <id> --n 10      # your next blind pairs as links (Text A / Text B), to read off the screen; pick in the console
 letterstory admin tuning promote <experiment-id> --versions <service-kernel-id>:21   # from a concluded "ship" decision
 letterstory admin experiments list --q colons          # what we've tried
 letterstory admin experiments new "We use too many colons" --as "claude-code"
@@ -519,6 +520,14 @@ letterstory arena endpoint config <arena-id> [--file cfg.json]
 letterstory arena endpoint update <arena-id> --name "Docs research v2"   # creator or org admin only
 letterstory arena endpoint delete <arena-id> --yes
 
+# The research agent as ONE versioned file (like a kernel file; schema at /api/schema/arena):
+letterstory arena file <arena-id> > arena.json            # the file the arena runs now
+letterstory arena file <arena-id> --patch '{"rules":{"context-figures":"measure"}}' --note "try it"
+letterstory arena file <arena-id> --file arena.json        # save a whole file as the next version
+letterstory arena versions <arena-id>                      # your copy's versions and our releases
+letterstory arena pin <arena-id> <version-id|none>         # pin one of our releases, or follow live
+letterstory arena offer <arena-id> [--accept]              # our newer version, over your own changes
+
 # Ledes: a prospect's context in, ready-to-send opening lines out (chosen from a
 # hand-approved library, never generated; the top choice is flagged). Synchronous.
 letterstory lede create --name "Clay outbound table"

package/lib/cli.mjs

@@ -54,7 +54,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.52.0";
+export const VERSION = "0.54.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.

package/lib/commands/admin.mjs

@@ -427,8 +427,31 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning comparisons | comparison <id>                list / read one (per-measure verdicts)
  *   admin tuning picks <comparison-id>                         the blind queue (next pairs)
  *   admin tuning pick <comparison-id> --cell <key> --pick left|right|tie   record a blind pick
+ *   admin tuning reading-list <comparison-id> [--n 10]          your next blind pairs as links, to read off the screen
  *   admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…   promote from a "ship" decision
+ *
+ * Research (Phase 3): our arena's versions as files, research comparisons, the deploy split.
+ *   admin tuning arenas | arena <version-id>                   our arena's versions / one version's file and diff
+ *   admin tuning arena-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
+ *   admin tuning research-compare --title "…" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys …]
+ *   admin tuning research-inputs [--set v1]                    research's fixed inputs
+ *   admin tuning research-split [--since-hours 72] [--at <iso>,…]   what each deploy did to research in production
+ *   admin tuning research-standing                             live's level on the fixed inputs, week by week
+ *   admin tuning promote-arena <experiment-id> --version <arena-version-id>   promote our arena from a "ship" decision
  */
+/** `--flag '<json>'` → the parsed object, or undefined when the flag is absent. */
+function jsonFlag(raw, name) {
+	const text = flagStr(raw);
+	if (text === undefined) return undefined;
+	try {
+		const v = JSON.parse(text);
+		if (!v || typeof v !== "object" || Array.isArray(v)) throw new Error("not an object");
+		return v;
+	} catch (err) {
+		throw new CliError(`${name} is not a JSON object: ${err.message}`);
+	}
+}
+
 async function cmdAdminTuning(ctx) {
 	const [sub, id] = ctx.positionals;
 	const { flags, io } = ctx;
@@ -523,6 +546,110 @@ async function cmdAdminTuning(ctx) {
 				await staffRequest(ctx, "POST", `${T}/comparisons/${id}/picks`, { cell_key: cell, outcome: pick })
 			);
 		}
+		case "reading-list": {
+			if (!id) throw new CliError("Usage: admin tuning reading-list <comparison-id> [--n 10]");
+			const n = flagStr(flags.n);
+			const r = await staffRequest(
+				ctx,
+				"GET",
+				`${T}/comparisons/${id}/reading-list${n ? `?${new URLSearchParams({ n })}` : ""}`
+			);
+			return json ? printResult(io, flags, r) : io.log(r.text);
+		}
+		// --- Research: our arena's versions, research comparisons, the deploy split ---
+		case "arenas": {
+			const r = await staffRequest(ctx, "GET", `${T}/arena-files`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.versions
+					.map((v) => `${v.label.padEnd(18)} ${v.status.padEnd(9)} ${v.id}${v.note ? `  ${v.note}` : ""}`)
+					.join("\n") || "(no versions)"
+			);
+		}
+		case "arena": {
+			if (!id) throw new CliError("Usage: admin tuning arena <version-id>");
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/arena-files/${id}`));
+		}
+		case "arena-candidate": {
+			const patch = jsonFlag(flags.patch, "--patch");
+			const file = jsonFile({ "arena-file": flags.file }, "arena");
+			if ((patch === undefined) === (file === undefined))
+				throw new CliError(
+					'Usage: admin tuning arena-candidate --patch \'{"rules":{"context-figures":"off"}}\' | --file arena.json [--of <version-id>] [--note "…"]'
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/arena-files`,
+				compact({ patch, file, patch_of: flagStr(flags.of), note: flagStr(flags.note) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`saved candidate ${r.version.label} (${r.version.id})`);
+		}
+		case "research-compare": {
+			const title = flagStr(flags.title);
+			const versionId = flagStr(flags.candidate);
+			const patch = jsonFlag(flags.patch, "--patch");
+			const nullCheck = flagBool(flags["null-check"]);
+			const named = [versionId !== undefined, patch !== undefined, nullCheck === true].filter(Boolean).length;
+			if (!title || named !== 1)
+				throw new CliError(
+					"Usage: admin tuning research-compare --title \"…\" (--candidate <version-id> | --patch '{…}' | --null-check) [--keys k1,k2] [--concurrency 6] [--experiment <id>]"
+				);
+			const candidate = versionId ? { version_id: versionId } : patch ? { patch } : { null_check: true };
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/comparisons`,
+				compact({
+					primitive: "research",
+					title,
+					candidate,
+					keys: flagList(flags.keys),
+					concurrency: flagNum(flags.concurrency),
+					experiment_id: flagStr(flags.experiment),
+				})
+			);
+			return json ? printResult(io, flags, r) : io.log(`research comparison ${r.comparison?.id ?? ""} started`);
+		}
+		case "research-inputs": {
+			const set = flagStr(flags.set);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/research/inputs${set ? `?${new URLSearchParams({ set })}` : ""}`)
+			);
+		}
+		case "research-split": {
+			const q = new URLSearchParams(
+				compact({
+					since_hours: flagStr(flags["since-hours"]),
+					window_hours: flagStr(flags["window-hours"]),
+					at: flagStr(flags.at),
+				})
+			);
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/research/deploy-split${q.size ? `?${q}` : ""}`)
+			);
+		}
+		case "research-standing":
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/research/standing`));
+		case "promote-arena": {
+			const version = flagStr(flags.version);
+			if (!id || !version)
+				throw new CliError("Usage: admin tuning promote-arena <experiment-id> --version <arena-version-id>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(
+					ctx,
+					"POST",
+					`${EXPERIMENTS}/${id}/promote`,
+					compact({ arena_version_id: version, actor: actorFrom(flags) })
+				)
+			);
+		}
 		case "promote": {
 			const list = flagList(flags.versions);
 			if (!id || !list?.length)
@@ -546,7 +673,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|promote (see --help)"
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|reading-list|promote|arenas|arena|arena-candidate|research-compare|research-inputs|research-split|research-standing|promote-arena (see --help)"
 			);
 	}
 }

package/lib/commands/arena.mjs

@@ -186,6 +186,33 @@ export const ARGS = {
 		arena_id: { positional: 1, label: "arena-id", required: true },
 		config: { value: (flags) => readJsonFileFlag(flags, "file") },
 	},
+	// The arena's research agent as a versioned file (the kernel file's twin): `arena file <id>`
+	// prints it, `--file f.json` saves a whole file, `--patch '{…}'` only the fields to change.
+	get_arena_file: {
+		arena_id: { positional: 0, label: "arena-id", required: true },
+	},
+	save_arena_file: {
+		arena_id: { positional: 0, label: "arena-id", required: true },
+		file: { value: (flags) => readJsonFileFlag(flags, "file") },
+		patch: { value: (flags) => readJsonObjectFlag(flags, "patch") },
+		note: "note",
+	},
+	list_arena_versions: {
+		arena_id: { positional: 0, label: "arena-id", required: true },
+	},
+	pin_arena_version: {
+		arena_id: { positional: 0, label: "arena-id", required: true },
+		version_id: {
+			value: (_flags, positionals) => {
+				const v = positionals[1];
+				if (v === undefined) throw new CliError("Missing required <version-id|none>");
+				return v === "none" ? null : v;
+			},
+		},
+	},
+	accept_arena_offer: {
+		arena_id: { positional: 0, label: "arena-id", required: true },
+	},
 };
 
 export async function cmdArena(ctx) {
@@ -218,9 +245,17 @@ export async function cmdArena(ctx) {
 			return arenaList(rest);
 		case "endpoint":
 			return arenaEndpoint(rest);
+		case "file":
+			return arenaFile(rest);
+		case "versions":
+			return arenaTool(rest, "list_arena_versions");
+		case "pin":
+			return arenaTool(rest, "pin_arena_version");
+		case "offer":
+			return rest.flags.accept === true ? arenaTool(rest, "accept_arena_offer") : arenaOffer(rest);
 		default:
 			throw new CliError(
-				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, latest, direction, cancel, balance, list, endpoint, roles, role`
+				`Unknown arena subcommand: ${sub ?? "(none)"}. Try: run, run-status, runs, latest, direction, cancel, balance, list, endpoint, file, versions, pin, offer, roles, role`
 			);
 	}
 }
@@ -386,6 +421,51 @@ async function arenaList(ctx) {
  * `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).
  */
+/**
+ * `arena file <arena-id>` prints the file the arena runs (the file itself, so `> f.json` round-trips);
+ * `arena file <arena-id> --file f.json | --patch '{…}' [--note …]` saves a new live version of the
+ * arena's own copy.
+ */
+async function arenaFile(ctx) {
+	const { client, flags, io } = ctx;
+	const saving =
+		flagStr(flags.file) !== undefined ||
+		flagStr(flags.patch) !== undefined ||
+		flagStr(flags["patch-file"]) !== undefined;
+	if (!saving) {
+		const result = await client.callTool(
+			"get_arena_file",
+			argsFromFlags(ARGS.get_arena_file, flags, ctx.positionals)
+		);
+		printResult(io, flags, result, (r) => JSON.stringify(r?.file ?? r, null, 2));
+		return 0;
+	}
+	const result = await client.callTool(
+		"save_arena_file",
+		argsFromFlags(ARGS.save_arena_file, flags, ctx.positionals)
+	);
+	ok(ctx, `Saved ${toolField(result, "version")?.label ?? "a new version"}; the arena runs it from now on.`);
+	printResult(io, flags, result);
+	return 0;
+}
+
+/** `arena offer <arena-id>`: what our newer version would change; `--accept` takes it. */
+async function arenaOffer(ctx) {
+	const { client, flags, io } = ctx;
+	const result = await client.callTool("get_arena_file", argsFromFlags(ARGS.get_arena_file, flags, ctx.positionals));
+	const offer = toolField(result, "offer");
+	if (!offer) ok(ctx, "No offer: your arena runs our latest version, or a copy based on it.");
+	printResult(io, flags, result, (r) => JSON.stringify(r?.offer ?? null, null, 2));
+	return 0;
+}
+
+/** One arena-file tool, its arguments from ARGS. */
+async function arenaTool(ctx, tool) {
+	const result = await ctx.client.callTool(tool, argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals));
+	printResult(ctx.io, ctx.flags, result);
+	return 0;
+}
+
 async function arenaEndpoint(ctx) {
 	const { client, positionals, flags, io } = ctx;
 	const action = positionals[0];

package/package.json

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