@letterstory/cli 0.176.96 → 0.176.98

package/lib/cli.mjs

@@ -82,11 +82,12 @@ import {
 	cmdReplicate,
 	cmdDeploy,
 	cmdRefs,
+	cmdModels,
 } from "./commands.mjs";
 import { fetchParkedSections, withoutParked } from "./parked.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.176.96";
+export const VERSION = "0.176.98";
 
 /** The exit code for a gate refusal (CARD_REQUIRED, PAYMENT_FAILED, OUT_OF_TOKENS): 1 is a plain error. */
 export const EXIT_PAYMENT_REQUIRED = 3;
@@ -130,7 +131,9 @@ export const BOOLEAN_FLAGS = new Set([
 	"start",
 	// site research-builds: run now even when the stored pass is under an hour old.
 	"fresh",
-	// admin letterpress telemetry | prs: every org, test and demo orgs included.
+	// admin letterpress tokens: today so far against yesterday and a week ago.
+	"so-far",
+	// admin letterpress telemetry | prs | tokens: every org, test and demo orgs included.
 	"all-orgs",
 	// admin letterpress prs | failures: since the first PR or build (all_time).
 	"all-time",
@@ -415,6 +418,10 @@ export const BOOLEAN_FLAGS = new Set([
 	"dry",
 	// admin billing emails --bounced
 	"bounced",
+	// models add: train once the links are added. models confirm: keep the found links not named, or don't train yet.
+	"train",
+	"keep-rest",
+	"no-train",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -2017,6 +2024,22 @@ Refs (Visual Refs: other companies' brands to design something new after, apart
                                                        Every brand's direction for it, as one file
   refs brief-show <brief-id>                           The brief, once ready
 
+Models (your own writing models, each trained on writing you give it so it writes in your voice):
+  models [list] [--archived]                           Your models: where each stands, its links, its version
+  models create "<name>" [--budget <usd>] [--description <d>]
+                                                       Budget: the most one training run may cost (default $100)
+  models show <id>                                     Its links, its training and what it cost
+  models add <id> <url>… [--train]                     Links to pieces of your writing; --train starts training
+  models find <id> "<the writing to find>" [--max <n>] Letter finds the links and proposes them
+  models confirm <id> [<link-id>…] [--keep-rest] [--no-train]
+                                                       Confirm what was found (all, or the ids) and train on it
+  models remove <id> <link-id>…                        Take links out of the next version
+  models train <id> [--retry]                          Train the next version, or try a stopped one again
+  models stop <id>                                     Stop what is training; what it spent is charged
+  models write <id> "<what to write>" [--words <n>]    Write with its trained version
+  models update <id> [--name <n>] [--budget <usd>] [--description <d>]
+  models archive <id> | models restore <id>
+
 Bench (Benches: open-source benchmarks on their own domains, kept running; @letterstory.com only):
   bench [list]                                         Your benches: stage, what each waits on, domain
   bench create (--prompt "<what it is and how it works>"|--prompt-file <path>) [--name <n>] [--domain <d>]
@@ -2157,6 +2180,7 @@ const CLIENT_COMMANDS = {
 	replicate: cmdReplicate,
 	deploy: cmdDeploy,
 	refs: cmdRefs,
+	models: cmdModels,
 	// Platform-scoped (staff key) — the only commands that act BEFORE an org exists.
 	admin: cmdAdmin,
 };

package/lib/commands/admin.mjs

@@ -5261,9 +5261,10 @@ const ENGINE = "/api/superadmin/engine-settings";
 const LETTERPRESS = "/api/superadmin/letterpress";
 const CODING_TELEMETRY = "/api/superadmin/coding-telemetry";
 const PULL_REQUESTS = "/api/superadmin/pull-requests";
+const PLATFORM_USAGE = "/api/superadmin/usage/platform";
 const BUILD_FAILURES = "/api/superadmin/build-failures";
 const ENGINE_USAGE =
-	"Usage: admin letterpress status | gaps | telemetry [--days N] [--harness h] [--all-orgs] | prs [--days N | --from YYYY-MM-DD [--to YYYY-MM-DD] | --all-time] [--day YYYY-MM-DD] [--org id] [--state merged|open|closed] [--top N] [--tz zone] [--all-orgs] | failures [--days N | --from YYYY-MM-DD [--to YYYY-MM-DD] | --all-time] [--day YYYY-MM-DD] [--org id] [--failure ours|agent|setup|undelivered] [--cause c] [--stopped-at step] [--repo owner/name] [--slow] [--tz zone] [--all-orgs] | blocked [--days N] [--org id] [--all-orgs] | unblock <org-id> <host> <subject> | decisions <org-id> [--site host] [--surface plan|fix|build|site] | undo <org-id> <host> <decision-id> | runs [--status s] [--error-code c] [--first-review-cause agent|context|setup|unknown] [--pr merged|closed|open|none] [--harness h] [--days N] | beyond [--limit N] [--before ISO] | companies | company <org-id> [--site host] | facts <org-id> [--site host] | fits [--recipe id] [--org id] [--site host] [--fits yes|no|unknown|waiting] [--limit N] | replay <run-id> | mark <run-id> <item-id> <right|weak|wrong|lead|gap|recipe|clear> [--note …] | settings | set <weights.<ask>.<reading>|lenses.<lens>.bar.<reading>|lenses.<lens>.bar|lenses.<lens>.research.turns|lenses.<lens>.research.ms|asks.<lens>.ask|asks.<lens>.guidance|dismissals.block_days|preflight.off|explore.ask|explore.research.turns|explore.research.ms|explore.every_days> <value>";
+	"Usage: admin letterpress status | gaps | telemetry [--days N] [--harness h] [--all-orgs] | tokens [--days N] [--so-far] [--all-orgs] | prs [--days N | --from YYYY-MM-DD [--to YYYY-MM-DD] | --all-time] [--day YYYY-MM-DD] [--org id] [--state merged|open|closed] [--top N] [--tz zone] [--all-orgs] | failures [--days N | --from YYYY-MM-DD [--to YYYY-MM-DD] | --all-time] [--day YYYY-MM-DD] [--org id] [--failure ours|agent|setup|undelivered] [--cause c] [--stopped-at step] [--repo owner/name] [--slow] [--tz zone] [--all-orgs] | blocked [--days N] [--org id] [--all-orgs] | unblock <org-id> <host> <subject> | decisions <org-id> [--site host] [--surface plan|fix|build|site] | undo <org-id> <host> <decision-id> | runs [--status s] [--error-code c] [--first-review-cause agent|context|setup|unknown] [--pr merged|closed|open|none] [--harness h] [--days N] | beyond [--limit N] [--before ISO] | companies | company <org-id> [--site host] | facts <org-id> [--site host] | fits [--recipe id] [--org id] [--site host] [--fits yes|no|unknown|waiting] [--limit N] | replay <run-id> | mark <run-id> <item-id> <right|weak|wrong|lead|gap|recipe|clear> [--note …] | settings | set <weights.<ask>.<reading>|lenses.<lens>.bar.<reading>|lenses.<lens>.bar|lenses.<lens>.research.turns|lenses.<lens>.research.ms|asks.<lens>.ask|asks.<lens>.guidance|dismissals.block_days|preflight.off|explore.ask|explore.research.turns|explore.research.ms|explore.every_days> <value>";
 
 /** One number of the settings from a dotted path and a value: the PUT body save_engine_settings reads. */
 function engineSettingsPatch(path, value) {
@@ -5506,6 +5507,30 @@ async function cmdAdminLetterpress(ctx) {
 			);
 			return 0;
 		}
+		case "tokens": {
+			// get_platform_usage: every customer's tokens day by day, Letterpress's on its own (Letterpress → Today).
+			const q = new URLSearchParams({ days: String(flags.days ?? 30) });
+			if (flagBool(flags["all-orgs"])) q.set("customers", "0");
+			if (flagBool(flags["so-far"])) q.set("so_far", "1");
+			const r = await staffRequest(ctx, "GET", `${PLATFORM_USAGE}?${q}`);
+			const n = (v) => Math.round(v).toLocaleString("en-US");
+			printResult(io, flags, r, (x) =>
+				[
+					`Tokens, ${x.since_day} to ${x.until_day} (${x.tz})${x.customer_only ? ", customers only" : ""}: ${n(x.totals.tokens)}, Letterpress ${n(x.totals.letterpress)}`,
+					`by product: ${x.categories.map((c) => `${c.label} ${n(x.totals.by_category[c.key] ?? 0)}`).join(", ") || "—"}`,
+					...x.series.map(
+						(d) =>
+							`${d.day}  ${n(d.tokens).padStart(10)} tokens  ${n(d.letterpress).padStart(8)} Letterpress`
+					),
+					...(x.so_far
+						? [
+								`today so far ${n(x.so_far.today)}; by this time yesterday ${n(x.so_far.yesterday)}, a week ago ${n(x.so_far.week_ago)}`,
+							]
+						: []),
+				].join("\n")
+			);
+			return 0;
+		}
 		case "prs": {
 			// get_pull_requests (the days) or, with --day / --org / --state, list_pull_requests (the PRs behind them).
 			const listing = flags.day || flags.org || flags.state;

package/lib/commands/models.mjs

@@ -0,0 +1,219 @@
+// `models` — your own writing models from a terminal (docs/architecture/writing-models.md): each post-trained
+// on writing you give it, so it writes in your voice. Thin wrappers over the writing model tools
+// (create_writing_model, list_writing_models, get_writing_model, update_writing_model, add_writing_model_links,
+// find_writing_model_links, confirm_writing_model_links, remove_writing_model_links, train_writing_model,
+// write_with_writing_model), the same lib functions the app calls.
+//
+//   letterstory models [list] [--archived]
+//   letterstory models create "<name>" [--budget <usd>] [--description <d>]
+//   letterstory models show <id>
+//   letterstory models add <id> <url>… [--train]
+//   letterstory models find <id> "<the writing to find>" [--max <n>]
+//   letterstory models confirm <id> [<link-id>…] [--keep-rest] [--no-train]   no link ids: all of them
+//   letterstory models remove <id> <link-id>…
+//   letterstory models train <id> [--retry]
+//   letterstory models stop <id>                                               stop what is training
+//   letterstory models write <id> "<what to write>" [--words <n>]
+//   letterstory models update <id> [--name <n>] [--budget <usd>] [--description <d>]
+//   letterstory models archive <id> | models restore <id>
+
+import { CliError } from "../client.mjs";
+import { argsFromFlags, flagStr, printResult, refuseUnknownFlags } from "./shared.mjs";
+
+const modelId = { positional: 0, label: "model-id", required: true };
+const rest = (from) => (flags, positionals) => {
+	const list = positionals.slice(from).filter(Boolean);
+	return list.length ? list : undefined;
+};
+
+export const ARGS = {
+	create_writing_model: {
+		name: { value: (flags, positionals) => flagStr(flags.name) ?? (positionals.join(" ").trim() || undefined) },
+		description: "description",
+		budget_usd: { flag: "budget", type: "num" },
+	},
+	list_writing_models: { archived: { flag: "archived", type: "bool" } },
+	get_writing_model: { model_id: modelId },
+	update_writing_model: {
+		model_id: modelId,
+		name: "name",
+		description: "description",
+		budget_usd: { flag: "budget", type: "num" },
+		archived: { internal: "models archive / models restore" },
+	},
+	add_writing_model_links: {
+		model_id: modelId,
+		urls: { value: rest(1) },
+		train: { flag: "train", type: "bool" },
+	},
+	find_writing_model_links: {
+		model_id: modelId,
+		prompt: { value: (flags, positionals) => positionals.slice(1).join(" ").trim() || undefined },
+		max_links: { flag: "max", type: "num" },
+	},
+	confirm_writing_model_links: {
+		model_id: modelId,
+		confirm: { value: (flags, positionals) => rest(1)(flags, positionals) ?? "all" },
+		decline_rest: { flag: "keep-rest", type: "bool", invert: true },
+		train: { flag: "no-train", type: "bool", invert: true },
+	},
+	remove_writing_model_links: { model_id: modelId, source_ids: { value: rest(1) } },
+	train_writing_model: { model_id: modelId, retry: { flag: "retry", type: "bool" } },
+	cancel_writing_model_run: { model_id: modelId },
+	write_with_writing_model: {
+		model_id: modelId,
+		ask: { value: (flags, positionals) => positionals.slice(1).join(" ").trim() || undefined },
+		max_words: { flag: "words", type: "num" },
+	},
+};
+
+function call(ctx, tool, extra = {}) {
+	return ctx.client.callTool(tool, { ...argsFromFlags(ARGS[tool], ctx.flags, ctx.positionals), ...extra });
+}
+
+const STATE = {
+	empty: "no writing yet",
+	confirming: "links to confirm",
+	untrained: "not trained",
+	training: "training",
+	stopped: "needs you",
+	ready: "ready",
+	archived: "archived",
+};
+
+export async function cmdModels(ctx) {
+	const sub = ctx.positionals[0];
+	const next = { ...ctx, positionals: ctx.positionals.slice(1) };
+	switch (sub) {
+		case undefined:
+		case "list":
+		case "ls": {
+			refuseUnknownFlags(next, ARGS.list_writing_models, []);
+			const result = await call(next, "list_writing_models");
+			printResult(next.io, next.flags, result, (r) => {
+				if (!r.models?.length) return 'No models yet. Make one: models create "Our voice"';
+				return r.models
+					.map(
+						(m) =>
+							`${m.id}  ${m.name.slice(0, 28).padEnd(28)} ${(STATE[m.state] ?? m.state).padEnd(17)} ${m.links.confirmed} links${m.version ? `  v${m.version.n}` : ""}`
+					)
+					.join("\n");
+			});
+			return 0;
+		}
+		case "create": {
+			refuseUnknownFlags(next, ARGS.create_writing_model, ["name"]);
+			const args = argsFromFlags(ARGS.create_writing_model, next.flags, next.positionals);
+			if (!args.name) throw new CliError('Name it: models create "Our voice" [--budget 100]');
+			return modelShow(next, await next.client.callTool("create_writing_model", args));
+		}
+		case "show":
+			return modelShow(next, await call(next, "get_writing_model"));
+		case "add": {
+			refuseUnknownFlags(next, ARGS.add_writing_model_links, []);
+			const args = argsFromFlags(ARGS.add_writing_model_links, next.flags, next.positionals);
+			if (!args.urls) throw new CliError("Give links: models add <id> <url> [<url>…] [--train]");
+			const result = await next.client.callTool("add_writing_model_links", args);
+			return trainingShow(next, result, `Added ${result.added} links.`);
+		}
+		case "find": {
+			refuseUnknownFlags(next, ARGS.find_writing_model_links, []);
+			const args = argsFromFlags(ARGS.find_writing_model_links, next.flags, next.positionals);
+			if (!args.prompt) throw new CliError('Say what to find: models find <id> "every post on our blog"');
+			const result = await next.client.callTool("find_writing_model_links", args);
+			printResult(next.io, next.flags, result, (r) =>
+				[
+					`Found ${r.proposed.length} links (of ${r.considered} pages), waiting to be confirmed:`,
+					...r.proposed.map((s) => `  ${s.id}  ${s.title ? `${s.title.slice(0, 50)}  ` : ""}${s.url}`),
+					"",
+					`Confirm them all and train: models confirm ${args.model_id}`,
+					`Or only some: models confirm ${args.model_id} <link-id> [<link-id>…]`,
+				].join("\n")
+			);
+			return 0;
+		}
+		case "confirm": {
+			refuseUnknownFlags(next, ARGS.confirm_writing_model_links, []);
+			const result = await call(next, "confirm_writing_model_links");
+			return trainingShow(
+				next,
+				result,
+				`Confirmed ${result.confirmed} links${result.declined ? `, declined ${result.declined}` : ""}.`
+			);
+		}
+		case "remove": {
+			const args = argsFromFlags(ARGS.remove_writing_model_links, next.flags, next.positionals);
+			if (!args.source_ids) throw new CliError("Give the link ids: models remove <id> <link-id> [<link-id>…]");
+			const result = await next.client.callTool("remove_writing_model_links", args);
+			printResult(next.io, next.flags, result, (r) => `Removed ${r.removed} links.`);
+			return 0;
+		}
+		case "train": {
+			refuseUnknownFlags(next, ARGS.train_writing_model, []);
+			const result = await call(next, "train_writing_model");
+			printResult(next.io, next.flags, result, (r) => runLine(r.run));
+			return 0;
+		}
+		case "stop": {
+			refuseUnknownFlags(next, ARGS.cancel_writing_model_run, []);
+			const result = await call(next, "cancel_writing_model_run");
+			printResult(next.io, next.flags, result, (r) => runLine(r.run));
+			return 0;
+		}
+		case "write": {
+			refuseUnknownFlags(next, ARGS.write_with_writing_model, []);
+			const args = argsFromFlags(ARGS.write_with_writing_model, next.flags, next.positionals);
+			if (!args.ask) throw new CliError('Say what to write: models write <id> "Write a 300-word post on…"');
+			const result = await next.client.callTool("write_with_writing_model", args);
+			printResult(next.io, next.flags, result, (r) => r.text);
+			return 0;
+		}
+		case "update":
+			refuseUnknownFlags(next, ARGS.update_writing_model, []);
+			return modelShow(next, await call(next, "update_writing_model"));
+		case "archive":
+		case "restore":
+			return modelShow(next, await call(next, "update_writing_model", { archived: sub === "archive" }));
+		default:
+			throw new CliError(
+				"Usage: models [list|create|show|add|find|confirm|remove|train|stop|write|update|archive|restore]"
+			);
+	}
+}
+
+function runLine(run) {
+	if (!run) return "Not trained yet.";
+	const where = run.blockedOn ? `stopped: ${run.blockedOn}` : (run.stageNote ?? run.stage);
+	return `Version ${run.n}: ${run.status}, ${where} ($${run.spentUsd} of up to $${run.budgetUsd})`;
+}
+
+function trainingShow(ctx, result, line) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		const t = r.training;
+		const after = !t
+			? ""
+			: t.started
+				? `\n${runLine(t.run)}\nFollow it: models show ${r.model.id}`
+				: `\nNot training: ${t.reason}`;
+		return `${line}${after}`;
+	});
+	return 0;
+}
+
+function modelShow(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		const m = r.model;
+		const lines = [
+			`${m.name}  ${m.id}`,
+			`  ${STATE[m.state] ?? m.state}, built on ${m.base}, up to $${m.budgetUsd} a training run`,
+			`  ${m.links.confirmed} links (${m.links.read} read, ${m.links.words} words)${m.links.proposed ? `, ${m.links.proposed} to confirm` : ""}`,
+			`  ${runLine(m.latestRun)}`,
+		];
+		const proposed = m.sources.filter((s) => s.status === "proposed");
+		if (proposed.length) lines.push("", `Confirm the links found and train: models confirm ${m.id}`);
+		else if (!m.links.confirmed)
+			lines.push("", `Give it writing: models add ${m.id} <url>…  or  models find ${m.id} "<where>"`);
+		return lines.join("\n");
+	});
+	return 0;
+}

package/lib/commands.mjs

@@ -58,3 +58,4 @@ export * from "./commands/bench.mjs";
 export * from "./commands/replicate.mjs";
 export * from "./commands/deploy.mjs";
 export * from "./commands/refs.mjs";
+export * from "./commands/models.mjs";

package/lib/parked.mjs

@@ -3,7 +3,7 @@
 // parked. Which are parked is decided on the server (Super Admin → Parked), so `help` asks it
 // (GET /api/parked, `cli_sections`). This list is only what it falls back to when the server can't
 // be reached: the state when this version shipped.
-export const PARKED_HELP_SECTIONS = ["Seers", "Shredder", "Ledes"];
+export const PARKED_HELP_SECTIONS = ["Seers", "Shredder", "Ledes", "Models"];
 
 /** The parked help sections the server names now, or null when it can't say in time. */
 export async function fetchParkedSections(url, { fetchImpl = globalThis.fetch, timeoutMs = 1500 } = {}) {

package/package.json

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