@letterstory/cli 0.51.0 → 0.52.0

package/README.md

@@ -352,6 +352,13 @@ long-running agent can watch the fleet on a schedule without a browser.
 export LETTERSTORY_STAFF_API_KEY=<your staff key with tuning:experiment>
 
 letterstory admin tuning-context --q "colons"          # what the agent knows (JSON)
+letterstory admin tuning kernels                       # every catalog kernel: live version, writer, candidates
+letterstory admin tuning kernel <service-kernel-id> --version live   # one version's kernel file (JSON)
+letterstory admin tuning candidate <service-kernel-id> --file hazel.json --note "Echo as the writer"
+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 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"
 letterstory admin experiments update <id> --plan-file plan.json --budget 120

package/lib/cli.mjs

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

@@ -7,6 +7,7 @@
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
+//   admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|promote …   (tuning:experiment)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin crm import|capture|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin create-org --domain acme.com [--name "Acme"] [--test] [--no-key] [--key-name N]
@@ -412,6 +413,144 @@ async function cmdAdminTuningContext(ctx) {
 	);
 }
 
+/* ------------------------------------------------------------ the tuning console's Write area */
+
+/**
+ * `admin tuning …` — kernel versions as files, comparisons of a candidate against live, blind picks
+ * and promotion from the ledger (docs/architecture/tuning-foundation.md): the headless half of the
+ * tuning console's Write › Kernels and Compare tabs. Needs `tuning:experiment` on the key.
+ *
+ *   admin tuning kernels                                       every catalog kernel, live version, writer, candidates
+ *   admin tuning kernel <service-kernel-id> [--version N|live]  one version's file (JSON)
+ *   admin tuning candidate <service-kernel-id> --file f.json [--note "…"]   save a file as a candidate version
+ *   admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]   start a comparison
+ *   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 promote <experiment-id> --versions <service-kernel-id>:<version>,…   promote from a "ship" decision
+ */
+async function cmdAdminTuning(ctx) {
+	const [sub, id] = ctx.positionals;
+	const { flags, io } = ctx;
+	const json = flagBool(flags.json);
+	const T = "/api/superadmin/tuning";
+	switch (sub) {
+		case "kernels": {
+			const r = await staffRequest(ctx, "GET", `${T}/kernel-files`);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				r.kernels
+					.map((k) => {
+						const c = k.versions
+							.filter((v) => v.status === "candidate")
+							.map((v) => `v${v.version} ${v.writer}`);
+						return `${k.kernel.padEnd(12)} live v${k.live}  ${k.writer}  ${k.serviceKernelId}${c.length ? `\n    candidates: ${c.join(", ")}` : ""}`;
+					})
+					.join("\n") || "(no kernels)"
+			);
+		}
+		case "kernel": {
+			if (!id) throw new CliError("Usage: admin tuning kernel <service-kernel-id> [--version N|live]");
+			const version = flagStr(flags.version) ?? "live";
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/kernel-files/${id}/versions/${version}`)
+			);
+		}
+		case "candidate": {
+			const path = flagStr(flags.file);
+			let file;
+			if (path) {
+				try {
+					file = JSON.parse(readFileSync(path, "utf8"));
+				} catch (err) {
+					throw new CliError(`--file ${path}: ${err.message}`);
+				}
+			}
+			if (!id || !file)
+				throw new CliError('Usage: admin tuning candidate <service-kernel-id> --file kernel.json [--note "…"]');
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/kernel-files/${id}/versions`,
+				compact({ file, note: flagStr(flags.note) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`saved candidate v${r.version}`);
+		}
+		case "compare": {
+			const title = flagStr(flags.title);
+			const list = flagList(flags.candidates);
+			if (!title || !list?.length)
+				throw new CliError(
+					'Usage: admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]'
+				);
+			const candidates = list.map((item) => {
+				const at = item.lastIndexOf(":");
+				const version = Number(item.slice(at + 1));
+				if (at < 1 || !Number.isInteger(version))
+					throw new CliError(`--candidates items are kernel:version, got "${item}"`);
+				return { kernel: item.slice(0, at), candidate_version: version };
+			});
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/comparisons`,
+				compact({ title, candidates, experiment_id: flagStr(flags.experiment) })
+			);
+			return json ? printResult(io, flags, r) : io.log(`comparison ${r.comparison?.id ?? r.id ?? ""} started`);
+		}
+		case "comparisons":
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/comparisons`));
+		case "comparison":
+			if (!id) throw new CliError("Usage: admin tuning comparison <id>");
+			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/comparisons/${id}`));
+		case "picks":
+			if (!id) throw new CliError("Usage: admin tuning picks <comparison-id>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/picks`)
+			);
+		case "pick": {
+			const cell = flagStr(flags.cell);
+			const pick = flagStr(flags.pick);
+			if (!id || !cell || !["left", "right", "tie"].includes(pick ?? ""))
+				throw new CliError("Usage: admin tuning pick <comparison-id> --cell <key> --pick left|right|tie");
+			return printResult(
+				io,
+				flags,
+				await staffRequest(ctx, "POST", `${T}/comparisons/${id}/picks`, { cell_key: cell, outcome: pick })
+			);
+		}
+		case "promote": {
+			const list = flagList(flags.versions);
+			if (!id || !list?.length)
+				throw new CliError(
+					"Usage: admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…"
+				);
+			const versions = list.map((item) => {
+				const at = item.lastIndexOf(":");
+				return { service_kernel_id: item.slice(0, at), version: Number(item.slice(at + 1)) };
+			});
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(
+					ctx,
+					"POST",
+					`${EXPERIMENTS}/${id}/promote`,
+					compact({ versions, actor: actorFrom(flags) })
+				)
+			);
+		}
+		default:
+			throw new CliError(
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|promote (see --help)"
+			);
+	}
+}
+
 /* ------------------------------------------------------------ the staff CRM */
 
 const CRM = "/api/superadmin/crm";
@@ -1078,8 +1217,9 @@ export async function cmdAdmin(ctx) {
 	if (sub === "experiments") return cmdAdminExperiments({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-context") return cmdAdminTuningContext({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "tuning-import") return cmdAdminTuningImport({ ...ctx, positionals: ctx.positionals.slice(1) });
+	if (sub === "tuning") return cmdAdminTuning({ ...ctx, positionals: ctx.positionals.slice(1) });
 	if (sub === "evals") return cmdAdminEvals({ ...ctx, positionals: ctx.positionals.slice(1) });
 	throw new CliError(
-		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin evals … | admin tuning-context (see --help)'
+		'Usage: admin create-org --domain <bare-domain> [--onboard] … | admin ask "<question>" | admin experiments … | admin crm … | admin evals … | admin tuning … | admin tuning-context (see --help)'
 	);
 }

package/package.json

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