@letterstory/cli 0.19.0 → 0.23.0

package/lib/commands/kernel.mjs

@@ -16,7 +16,42 @@
 // unless you tell it not to.
 
 import { CliError } from "../client.mjs";
-import { flagStr, requireFlag, requirePositional, printResult, compact, ok, readBodyInput } from "./shared.mjs";
+import {
+	flagStr,
+	flagBool,
+	requireFlag,
+	requirePositional,
+	printResult,
+	compact,
+	ok,
+	readBodyInput,
+	toolField,
+	followJob,
+	argsFromFlags,
+} from "./shared.mjs";
+
+/**
+ * How the commands ADDED to this file source their arguments — see `argsFromFlags`
+ * in shared.mjs, and `scripts/parity-check.ts`, which compares these keys against
+ * each tool's published input schema.
+ *
+ * The rest of this module predates the field-level ratchet and is covered by the
+ * frozen UNMAPPED_TOOLS list. New commands declare; that list only shrinks.
+ */
+export const ARGS = {
+	create_kernel_endpoint: {
+		name: { flag: "name", required: true },
+		// Both optional bindings the tool has always accepted at create: which kernel
+		// writes, and which shredder (if any) runs inside the loop. Exposed rather than
+		// left as a known gap — an endpoint you cannot bind at create is one you have to
+		// go and fix in the app.
+		kernel_id: "kernel",
+		shredder_endpoint_id: "shredder",
+	},
+	delete_kernel_endpoint: {
+		endpoint_id: { positional: 1, label: "endpoint-id", required: true },
+	},
+};
 
 export async function cmdKernel(ctx) {
 	const sub = ctx.positionals[0];
@@ -31,6 +66,8 @@ export async function cmdKernel(ctx) {
 			return kernelStatus(rest);
 		case "endpoints":
 			return kernelEndpoints(rest);
+		case "endpoint":
+			return kernelEndpoint(rest);
 		case "write":
 			return kernelWrite(rest);
 		case "polish":
@@ -43,7 +80,7 @@ export async function cmdKernel(ctx) {
 			return kernelBalance(rest);
 		default:
 			throw new CliError(
-				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, write, polish, run-status, runs, balance, run, status`
+				`Unknown kernel subcommand: ${sub ?? "(none)"}. Try: list, endpoints, endpoint, write, polish, run-status, runs, balance, run, status`
 			);
 	}
 }
@@ -84,19 +121,6 @@ const POLL_INTERVAL_MS = 20_000;
 /** Stop following after this; the run keeps going and `run-status` picks it up. */
 const POLL_CEILING_MS = 45 * 60 * 1000;
 
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/** The tool result is a text payload holding JSON; pull one field out, leniently. */
-function readToolField(result, field) {
-	const raw = result?.content?.[0]?.text;
-	if (typeof raw !== "string") return undefined;
-	try {
-		return JSON.parse(raw)?.[field];
-	} catch {
-		return undefined;
-	}
-}
-
 async function kernelEndpoints(ctx) {
 	const { client, flags, io } = ctx;
 	const result = await client.callTool("list_kernel_endpoints", {});
@@ -121,10 +145,17 @@ async function kernelWrite(ctx) {
 		// it, so the verdict lands on the text that actually ships. Costs a shred as well as a
 		// run. Reachable from every other surface and, until now, not from here.
 		shredder_endpoint_id: flagStr(flags.shredder),
+		// The flag is --read-as, which is what shipped; an earlier draft of this branch
+		// called it --brief-mode and never reached anyone.
 		brief_mode: flagStr(flags["read-as"]),
+		// The other three `run_kernel` has always taken and the CLI still did not expose,
+		// so the only way to reach them was hand-written JSON through `mcp call`.
+		person: flagStr(flags.person),
+		author_name: flagStr(flags.author),
+		allow_experience_claims: flagBool(flags["experience-claims"]),
 	});
 	const result = await client.callTool("run_kernel", args);
-	const runId = readToolField(result, "run_id");
+	const runId = toolField(result, "run_id");
 	if (!runId) {
 		printResult(io, flags, result);
 		return 0;
@@ -136,22 +167,62 @@ async function kernelWrite(ctx) {
 	}
 
 	ok(ctx, `Write started as ${runId}. Waiting — this keeps running on the server if you stop.`);
-	const deadline = Date.now() + POLL_CEILING_MS;
-	for (;;) {
-		await sleep(POLL_INTERVAL_MS);
-		const polled = await client.callTool("get_kernel_endpoint_run", { run_id: runId });
-		const status = readToolField(polled, "status");
-		if (status && status !== "running") {
-			ok(ctx, `Write ${status}.`);
-			printResult(io, flags, polled);
-			return status === "done" ? 0 : 1;
-		}
-		if (Date.now() > deadline) {
-			ok(ctx, `Still running after 45 minutes. Follow it with: letterstory kernel run-status ${runId}`);
-			printResult(io, flags, polled);
-			return 0;
+	let lastStatus;
+	const { settled, value: polled } = await followJob(
+		io,
+		async () => {
+			const r = await client.callTool("get_kernel_endpoint_run", { run_id: runId });
+			lastStatus = toolField(r, "status");
+			return { done: !!lastStatus && lastStatus !== "running" && lastStatus !== "queued", value: r };
+		},
+		{ intervalMs: POLL_INTERVAL_MS, ceilingMs: POLL_CEILING_MS }
+	);
+
+	if (!settled) {
+		ok(ctx, `Still running after 45 minutes. Follow it with: letterstory kernel run-status ${runId}`);
+		printResult(io, flags, polled);
+		return 0;
+	}
+	ok(ctx, `Write ${lastStatus}.`);
+	// The operator waited for the ARTICLE; print it, not the envelope. --json still
+	// gets the whole payload.
+	printResult(io, flags, polled, (v) => (typeof v?.article === "string" ? v.article : JSON.stringify(v, null, 2)));
+	return lastStatus === "done" ? 0 : 1;
+}
+
+/**
+ * `kernel endpoint create|delete` — the standalone endpoint's own CRUD.
+ *
+ * `create_kernel_endpoint` and `delete_kernel_endpoint` existed as tools with no
+ * command at all, so provisioning the thing `kernel write` runs against could
+ * only be done through the app or hand-written JSON.
+ */
+async function kernelEndpoint(ctx) {
+	const { client, positionals, flags, io } = ctx;
+	const action = positionals[0];
+	if (action === "create" || action === "new") {
+		const args = argsFromFlags(ARGS.create_kernel_endpoint, flags, positionals);
+		const name = args.name;
+		const result = await client.callTool("create_kernel_endpoint", args);
+		ok(ctx, `Created kernel endpoint "${name}".`);
+		printResult(io, flags, result);
+		return 0;
+	}
+	if (action === "delete" || action === "rm") {
+		const id = requirePositional(positionals, 1, "endpoint-id");
+		if (!flags.yes) {
+			io.error(`Re-run with --yes to confirm: ${ctx.bin} kernel endpoint delete ${id} --yes`);
+			return 1;
 		}
+		const result = await client.callTool(
+			"delete_kernel_endpoint",
+			argsFromFlags(ARGS.delete_kernel_endpoint, flags, positionals)
+		);
+		ok(ctx, "Kernel endpoint deleted.");
+		printResult(io, flags, result);
+		return 0;
 	}
+	throw new CliError(`Unknown kernel endpoint action: ${action ?? "(none)"}. Try: create, delete`);
 }
 
 /** The OTHER door: reword the document you already have, keeping its own markup. */