@cloudraker/milliseconds 0.1.0

package/dist/cli.js

@@ -0,0 +1,1402 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+//#region src/errors.ts
+/** A brand property, so a duplicated copy of the package in a bundle still matches. */
+const BRAND = "~milliseconds.error";
+/**
+* One error class. Switch on `code`: the union narrows exhaustively and never goes stale
+* when the API adds a code.
+*/
+var MillisecondsError = class extends Error {
+	name = "MillisecondsError";
+	[BRAND] = true;
+	code;
+	/** 0 when the call never reached the API. */
+	status;
+	/** The API's own message, unchanged. `message` adds one hint line. */
+	apiMessage;
+	/** Seconds from the retry-after header. Only 429 rate_limit_exceeded carries it. */
+	retryAfter;
+	rateLimit;
+	response;
+	/** Attempts this call made, including the first. */
+	attempts;
+	/** True for the codes the SDK retries. */
+	retryable;
+	constructor(init) {
+		super(init.message ?? init.apiMessage, init.cause === void 0 ? void 0 : { cause: init.cause });
+		this.code = init.code;
+		this.status = init.status ?? 0;
+		this.apiMessage = init.apiMessage;
+		this.retryAfter = init.retryAfter ?? null;
+		this.rateLimit = init.rateLimit ?? null;
+		this.response = init.response ?? null;
+		this.attempts = init.attempts ?? 1;
+		this.retryable = init.retryable ?? false;
+	}
+};
+function isMillisecondsError(e) {
+	return typeof e === "object" && e !== null && e[BRAND] === true;
+}
+/** Every client-side check throws this: status 0, code client_error, nothing sent. */
+const clientError = (message) => new MillisecondsError({
+	code: "client_error",
+	status: 0,
+	apiMessage: message
+});
+//#endregion
+//#region src/validate.ts
+const MAX_CHARS = 2e4;
+const MAX_TEXTS = 32;
+const MAX_ITEMS = 32;
+const n = (x) => x.toLocaleString("en-US");
+const count = (size) => size === 1 ? "1 entry" : `${n(size)} entries`;
+/** The key is a secret, so a browser bundle needs an explicit opt-in. */
+function checkRuntime(apiKey, allowBrowser) {
+	if (!apiKey) throw clientError("No API key. Pass new DecisionMachine({ apiKey }) or set MS_API_KEY. Get a key at https://console.milliseconds.ai.");
+	if (typeof globalThis === "object" && typeof globalThis.document?.createElement === "function" && !allowBrowser) throw clientError("The API key is a secret. Call the API from your server, or pass dangerouslyAllowBrowser: true when the bundle never reaches a user.");
+}
+/**
+* `texts` is 1 to 32 items, and every text is 1 to 20,000 characters.
+*
+* An empty text is a 400, not the 200-with-empty-results trap. That trap needs `text` and
+* `texts` both absent, and the SDK always sends one of them. This check only replaces a
+* round trip with a local error.
+*/
+function checkInput(input) {
+	if (typeof input === "string") {
+		if (input === "") throw empty("text");
+		if (input.length > MAX_CHARS) throw tooLong("text", input.length);
+		return;
+	}
+	if (input.length === 0) throw clientError("texts is empty. Send at least one text.");
+	if (input.length > MAX_TEXTS) throw clientError(`texts has ${n(input.length)} items. The limit is ${n(MAX_TEXTS)}. Split the batch.`);
+	for (const [i, text] of input.entries()) {
+		if (text === "") throw empty(`texts[${i}]`);
+		if (text.length > MAX_CHARS) throw tooLong(`texts[${i}]`, text.length);
+	}
+}
+const empty = (where) => clientError(`${where} is empty. Send at least one character.`);
+const tooLong = (where, length) => clientError(`${where} is ${n(length)} characters. The limit is ${n(MAX_CHARS)}. Split on paragraphs and send the parts as texts.`);
+/**
+* `statements` and `questions` are 1 to 32 items. The wire message for a body without one
+* is `provide statement or statements, not both`, which names both fields and misleads.
+*/
+function checkSpec(name, value) {
+	if (typeof value === "string") {
+		if (value !== "") return;
+		if (name === "statements") throw clientError("yes-no needs a statement. The wire message for a body without one names both fields and misleads.");
+		throw clientError(`${name} has 0 items. Send 1 to ${MAX_ITEMS}.`);
+	}
+	if (value.length === 0 || value.length > MAX_ITEMS) throw clientError(`${name} has ${n(value.length)} items. Send 1 to ${MAX_ITEMS}.`);
+}
+/**
+* `labels` is 2 to 64, `types` is 1 to 64 and `scale` is 2 to 10. Three limits, because
+* `decide.schema.ts` holds three. One shared rule would reject a legal single-type
+* `entities` call.
+*
+* `decide.schema.ts` bounds the array branch of `labels` and `types` only: the
+* `name -> description` branch is a plain `z.record`, so any number of described labels is
+* legal. `classify-tree` passes `bounded` because its own `superRefine` bounds every level.
+*/
+function checkList(name, value, min, max, capability, bounded = Array.isArray(value)) {
+	const size = Array.isArray(value) ? value.length : Object.keys(value).length;
+	if (bounded ? size >= min && size <= max : size > 0) return;
+	const found = size === 0 ? `${name} is empty.` : `${name} has ${count(size)}.`;
+	throw clientError(`${found} ${capability} needs ${min} to ${max}.`);
+}
+/** `planFor` throws unless the schema is an object with properties. Beat it locally. */
+function checkSchema(schema) {
+	const s = schema;
+	if ((Array.isArray(s?.type) ? s.type.find((t) => t !== "null") : s?.type) !== "object" || typeof s?.properties !== "object" || s.properties === null) throw clientError("The schema must be an object with properties.");
+}
+//#endregion
+//#region src/client.ts
+const USER_AGENT = `cloudraker-milliseconds-js/0.1.0`;
+const DEFAULT_BASE_URL = "https://api.milliseconds.ai";
+const RETRY = /* @__PURE__ */ new Set([
+	"rate_limit_exceeded",
+	"runner_error",
+	"overloaded",
+	"connection_error",
+	"timeout"
+]);
+/** Full jitter, capped at 8 s. */
+const backoff = (n) => Math.random() * Math.min(500 * 2 ** n, 8e3);
+/** Resolves early when the caller aborts. The loop then throws the caller's reason. */
+const sleep = (ms, signal) => new Promise((resolve) => {
+	const timer = setTimeout(resolve, ms);
+	signal?.addEventListener("abort", () => {
+		clearTimeout(timer);
+		resolve();
+	}, { once: true });
+});
+/** Reads an environment variable without assuming `process` exists. */
+function env(name) {
+	try {
+		return globalThis.process?.env?.[name];
+	} catch {
+		return;
+	}
+}
+/** A Promise of the result, with the headers one call away. No Promise subclass. */
+const decision = (p) => {
+	const result = p.then((r) => r.result);
+	return Object.assign(result, { withUsage: () => {
+		result.catch(() => {});
+		return p;
+	} });
+};
+function rateLimitOf(h) {
+	const limitRequests = h.get("x-ratelimit-limit-requests");
+	if (limitRequests === null) return null;
+	const num = (k) => Number(h.get(k)) || 0;
+	return {
+		limitRequests: Number(limitRequests) || 0,
+		remainingRequests: num("x-ratelimit-remaining-requests"),
+		resetRequests: h.get("x-ratelimit-reset-requests") ?? "",
+		limitTokens: num("x-ratelimit-limit-tokens"),
+		remainingTokens: num("x-ratelimit-remaining-tokens"),
+		resetTokens: h.get("x-ratelimit-reset-tokens") ?? ""
+	};
+}
+function usageOf(response) {
+	const h = response.headers;
+	const num = (k) => Number(h.get(k)) || 0;
+	return {
+		inputChars: num("x-input-chars"),
+		inputTokens: num("x-input-tokens"),
+		inferenceMs: num("x-inference-ms"),
+		rateLimit: rateLimitOf(h),
+		headers: h
+	};
+}
+/** The hint line under the API message. Section 8.2 of DESIGN.md holds the copy. */
+function describe(code, status, apiMessage, attempts, ms) {
+	const over = attempts > 1 ? ` after ${attempts} attempts over ${(ms / 1e3).toFixed(1)}s` : "";
+	const tail = apiMessage ? `:\n${apiMessage}` : ".";
+	switch (code) {
+		case "missing_api_key":
+		case "invalid_api_key": return `milliseconds rejected the API key (${status} ${code}).\nKeys start with "sk-ms-". Check MS_API_KEY, or create a key at\nhttps://console.milliseconds.ai.`;
+		case "rate_limit_exceeded": return `rate limited (${status} ${code})${over}${tail}\n  Lower your concurrency, or raise maxRetries. Limits are per organization and\n  shared by every key.`;
+		case "insufficient_quota": return `no token credits left (${status} ${code})${tail}\n  Not retried. A timer retry will not help.`;
+		case "overloaded": return `every inference slot stayed busy (${status} ${code})${over}${tail}\n  This is backpressure, not a fault. Send fewer texts per call, or back off further.\n  A texts batch of 32 asks for 32 slots at once.`;
+		case "runner_error": return `inference failed twice (${status} ${code})${over}${tail}\n  The model, not your request. Retry later, or raise maxRetries.`;
+		case "timeout": return `the request timed out${over}${tail}\n  Raise timeout, or send fewer texts per call.`;
+		case "connection_error": return `could not reach the API${over}${tail}\n  Check baseUrl and the network. maxRetries: 0 fails fast.`;
+		default: return `milliseconds rejected the request (${status} ${code})${tail}${apiMessage.startsWith("labels:") ? "\n  classify needs two or more labels. Describe each one. Described labels score\n  measurably better than bare names." : ""}`;
+	}
+}
+/** One AbortSignal for the attempt: the per-attempt timeout, plus the caller's signal. */
+function attemptSignal(timeout, signal) {
+	const hasAny = typeof AbortSignal.any === "function";
+	if (typeof AbortSignal.timeout === "function" && (!signal || hasAny)) {
+		const t = AbortSignal.timeout(timeout);
+		return {
+			signal: signal ? AbortSignal.any([signal, t]) : t,
+			done: () => {}
+		};
+	}
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new DOMException("The operation timed out.", "TimeoutError")), timeout);
+	signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+	return {
+		signal: controller.signal,
+		done: () => clearTimeout(timer)
+	};
+}
+/** Transport: fetch, retries, errors and usage. Every capability is two lines on top. */
+var Client = class {
+	baseUrl;
+	#apiKey;
+	#timeout;
+	#maxRetries;
+	#headers;
+	#fetch;
+	constructor(options = {}) {
+		const apiKey = options.apiKey ?? env("MS_API_KEY");
+		checkRuntime(apiKey, options.dangerouslyAllowBrowser);
+		this.#apiKey = apiKey;
+		this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+		this.#timeout = options.timeout ?? 6e4;
+		this.#maxRetries = options.maxRetries ?? 2;
+		this.#headers = { ...options.headers };
+		this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+	}
+	/** Escape hatch. Your path, your body, your type, the SDK's auth, retries and errors. */
+	post(path, body, options) {
+		return this.call(path, body, options, (raw) => raw);
+	}
+	/** `unwrap` maps the parsed body to the result. It follows the request, never the response. */
+	call(path, body, options, unwrap) {
+		return decision(this.send(path, body, options ?? {}).then(({ response, raw }) => ({
+			result: unwrap(raw),
+			usage: usageOf(response),
+			response
+		})));
+	}
+	async send(path, body, call) {
+		const url = `${this.baseUrl}${path}`;
+		const maxRetries = call.maxRetries ?? this.#maxRetries;
+		const timeout = call.timeout ?? this.#timeout;
+		const headers = new Headers({
+			"content-type": "application/json",
+			"user-agent": USER_AGENT
+		});
+		for (const [k, v] of Object.entries({
+			...this.#headers,
+			...call.headers
+		})) headers.set(k, v);
+		headers.set("authorization", `Bearer ${this.#apiKey}`);
+		const init = {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		};
+		const started = Date.now();
+		for (let attempt = 1;; attempt++) {
+			if (call.signal?.aborted) throw call.signal.reason;
+			const outcome = await this.attempt(url, init, timeout, call.signal, attempt, started);
+			if (!(outcome instanceof MillisecondsError)) return outcome;
+			if (!outcome.retryable || attempt > maxRetries) throw outcome;
+			const wait = outcome.retryAfter === null ? backoff(attempt - 1) : Math.min(outcome.retryAfter, 60) * 1e3;
+			await sleep(wait, call.signal);
+		}
+	}
+	async attempt(url, init, timeout, signal, attempt, started) {
+		const guard = attemptSignal(timeout, signal);
+		try {
+			const response = await this.#fetch(url, {
+				...init,
+				signal: guard.signal
+			});
+			if (response.ok) return {
+				response,
+				raw: await response.json()
+			};
+			return await httpError(response, attempt, Date.now() - started);
+		} catch (cause) {
+			if (signal?.aborted) throw cause;
+			return transportError(cause, attempt, Date.now() - started);
+		} finally {
+			guard.done();
+		}
+	}
+};
+function transportError(cause, attempts, ms) {
+	const name = cause?.name ?? "";
+	const code = name === "TimeoutError" || name === "AbortError" ? "timeout" : "connection_error";
+	const apiMessage = cause?.message ?? String(cause);
+	return new MillisecondsError({
+		code,
+		status: 0,
+		apiMessage,
+		message: describe(code, 0, apiMessage, attempts, ms),
+		attempts,
+		retryable: true,
+		cause
+	});
+}
+async function httpError(response, attempts, ms) {
+	const body = await response.clone().json().catch(() => null);
+	const code = body?.error?.code ?? (response.status >= 500 ? "internal_error" : "http_error");
+	const apiMessage = body?.error?.message ?? response.statusText;
+	const retryAfter = response.headers.get("retry-after");
+	return new MillisecondsError({
+		code,
+		status: response.status,
+		apiMessage,
+		message: describe(code, response.status, apiMessage, attempts, ms),
+		retryAfter: retryAfter === null ? null : Number(retryAfter) || 0,
+		rateLimit: rateLimitOf(response.headers),
+		response,
+		attempts,
+		retryable: RETRY.has(code) || response.status >= 502 && response.status <= 504
+	});
+}
+//#endregion
+//#region src/schema.ts
+const CONVERT = "Pass a JSON Schema. zod: typed<z.infer<typeof S>>(z.toJSONSchema(S)). valibot: typed<v.InferOutput<typeof S>>(toJsonSchema(S)). arktype works directly.";
+/**
+* The object to send. A Standard Schema with a converter method (arktype) is converted.
+* A Standard Schema without one cannot be: the SDK has zero dependencies, so it names the
+* one line that converts it instead of importing zod.
+*/
+function toJsonSchema(schema) {
+	const s = schema;
+	const convert = typeof s.toJsonSchema === "function" ? s.toJsonSchema : s.toJSONSchema;
+	if (typeof convert === "function") return convert.call(s);
+	if ("~standard" in s) throw new MillisecondsError({
+		code: "invalid_schema",
+		status: 0,
+		apiMessage: CONVERT
+	});
+	return s;
+}
+//#endregion
+//#region src/decision-machine.ts
+const MODEL = "decision-machine-1";
+/** The batch shape follows the request, never the response. */
+const same = (raw) => raw;
+const key = (name) => (raw) => raw[name];
+/** `text` for one result, `texts` for a batch. The mutual exclusion is impossible here. */
+const inputBody = (input) => typeof input === "string" ? { text: input } : { texts: input };
+/**
+* `decision-machine-1` at api.milliseconds.ai. Every capability is a pure function, so
+* every retry is safe.
+*/
+var DecisionMachine = class extends Client {
+	/** Paths are `${baseUrl}/v1/${model}/<capability>`. */
+	static model = MODEL;
+	/**
+	* Answers each statement with yes or no and a probability. The statements share one
+	* inference call, so extra statements are nearly free.
+	*/
+	yesNo(input, statements, options) {
+		checkInput(input);
+		checkSpec("statements", statements);
+		const { when_true, when_false, ...call } = options ?? {};
+		const body = {
+			...inputBody(input),
+			...typeof statements === "string" ? { statement: statements } : { statements },
+			...when_true === void 0 ? {} : { when_true },
+			...when_false === void 0 ? {} : { when_false }
+		};
+		return this.capability("yes-no", body, input, call, typeof statements === "string" ? same : key("results"));
+	}
+	/** Picks one label and returns the full distribution. Describe each label. */
+	classify(input, labels, options) {
+		checkInput(input);
+		checkList("labels", labels, 2, 64, "classify");
+		return this.capability("classify", {
+			...inputBody(input),
+			labels
+		}, input, options, same);
+	}
+	/**
+	* Runs classify once per level of a nested tree, descending into the winner.
+	*
+	* The per-level `input_chars` and `input_tokens` do not sum to `Usage.inputChars`: the
+	* header counts one pass over the body, and each level re-sends the text.
+	*/
+	classifyTree(input, tree, options) {
+		checkInput(input);
+		checkList("labels", tree, 2, 64, "classify-tree", true);
+		return this.capability("classify-tree", {
+			...inputBody(input),
+			tree
+		}, input, options, same);
+	}
+	/** Places the text on an ordered scale of described levels, low to high. */
+	rate(input, scale, options) {
+		checkInput(input);
+		checkList("scale", scale, 2, 10, "rate");
+		return this.capability("rate", {
+			...inputBody(input),
+			scale
+		}, input, options, same);
+	}
+	/** Quotes the answer out of the text, with its offsets. `answer` is null when nothing fits. */
+	answer(input, questions, options) {
+		checkInput(input);
+		checkSpec("questions", questions);
+		const body = {
+			...inputBody(input),
+			...typeof questions === "string" ? { question: questions } : { questions }
+		};
+		return this.capability("answer", body, input, options, typeof questions === "string" ? same : key("results"));
+	}
+	/**
+	* Fills a JSON Schema from the text. Missing values are null, arrays of objects come back
+	* empty, arrays of scalars come back as strings, and enums are not checked server side.
+	*/
+	extract(input, schema, options) {
+		checkInput(input);
+		const json = toJsonSchema(schema);
+		checkSchema(json);
+		return this.capability("extract", {
+			...inputBody(input),
+			schema: json
+		}, input, options, key("data"));
+	}
+	/** Finds every span matching each type, with offsets, sorted by start. */
+	entities(input, types, options) {
+		checkInput(input);
+		checkList("types", types, 1, 64, "entities");
+		return this.capability("entities", {
+			...inputBody(input),
+			types
+		}, input, options, key("entities"));
+	}
+	/** Checks whether the text says `value` for `field`. */
+	verify(input, field, value, options) {
+		checkInput(input);
+		const body = {
+			...inputBody(input),
+			field: typeof field === "string" ? { name: field } : field,
+			value
+		};
+		return this.capability("verify", body, input, options, same);
+	}
+	/** `{ results }` is unwrapped for a batch, and the per-text envelope for one text. */
+	capability(name, body, input, options, one) {
+		const unwrap = typeof input === "string" ? one : (raw) => (raw.results ?? []).map(one);
+		return this.call(`/v1/${MODEL}/${name}`, body, options, unwrap);
+	}
+};
+//#endregion
+//#region src/cli/print.ts
+const num = (r, k) => Number(r[k] ?? 0);
+const text = (r, k) => String(r[k] ?? "");
+const p3 = (n) => n.toFixed(3);
+const int = (n) => n.toLocaleString("en-US");
+/** ANSI off for --no-color, for NO_COLOR, and for a pipe. */
+const dimmer = (color) => (s) => color ? `\u001B[2m${s}\u001B[0m` : s;
+/** `label        billing` — a padded key column. */
+const kv = (rows, dim, width = 12) => rows.map(([k, v]) => `${dim(k.padEnd(width))} ${v}`).join("\n");
+/** 20 blocks at 1.0. 0.001 rounds to none, so a flat score prints no bar. */
+const bar = (p) => "█".repeat(Math.round(p * 20));
+/** The scores block under a table. `sort` orders by score; a scale keeps its own order. */
+function scores(entries, dim, sort) {
+	const rows = sort ? [...entries].sort((a, b) => b[1] - a[1]) : entries;
+	const width = Math.max(0, ...rows.map(([name]) => name.length)) + 3;
+	const body = rows.map(([name, p]) => {
+		const drawn = bar(p);
+		return `  ${name.padEnd(width)}${p3(p)}${drawn ? `  ${drawn}` : ""}`;
+	});
+	return [dim("scores"), ...body].join("\n");
+}
+/** An aligned block of columns, two spaces apart. */
+function columns(rows) {
+	const width = [];
+	for (const row of rows) row.forEach((cell, i) => width[i] = Math.max(width[i] ?? 0, cell.length));
+	return rows.map((row) => row.map((cell, i) => i === row.length - 1 ? cell : cell.padEnd(width[i] ?? 0)).join("  ").trimEnd()).join("\n");
+}
+//#endregion
+//#region src/cli/spec.ts
+/** Bad arguments or bad stdin. Nothing was sent, so `dm1` exits 2. */
+var UsageError = class extends Error {};
+const specSize = (list) => Array.isArray(list) ? list.length : Object.keys(list).length;
+/** Reads a file, or stdin for `-`. */
+function read(path, stdin) {
+	if (path === "-") return stdin();
+	try {
+		return readFileSync(path, "utf8");
+	} catch (e) {
+		throw new UsageError(`cannot read ${path}: ${e.message}`);
+	}
+}
+/** `@labels.json` and `--schema @invoice.json`. `@-` reads stdin. */
+function loadJson(path, stdin) {
+	const raw = read(path, stdin);
+	try {
+		return JSON.parse(raw);
+	} catch (e) {
+		throw new UsageError(`${path === "-" ? "stdin" : path} is not JSON: ${e.message}`);
+	}
+}
+/** `--schema` and `--tree` take a file, `@file`, `@-` or inline JSON. */
+function loadDocument(flag, value, stdin) {
+	if (value.trimStart().startsWith("{")) try {
+		return JSON.parse(value);
+	} catch (e) {
+		throw new UsageError(`--${flag} is not JSON: ${e.message}`);
+	}
+	return loadJson(value.replace(/^@/, ""), stdin);
+}
+/**
+* Turns the positionals into the capability's list.
+*
+* `described` splits `name=description` on the first `=`. yes-no, answer and rate take free
+* text, so they never split. `@path` loads a JSON array or a name-to-description object.
+*/
+function parseSpec(items, described, stdin) {
+	const names = [];
+	const map = {};
+	let mapped = false;
+	for (const item of items) {
+		if (item.startsWith("@")) {
+			const loaded = loadJson(item.slice(1), stdin);
+			if (Array.isArray(loaded)) names.push(...loaded.map(String));
+			else if (typeof loaded === "object" && loaded !== null) {
+				if (!described) throw new UsageError(`${item.slice(1)} holds a name-to-description object. yes-no, rate and answer take a JSON array.`);
+				mapped = true;
+				for (const [k, v] of Object.entries(loaded)) map[k] = String(v);
+			} else throw new UsageError(`${item.slice(1)} must hold an array or a name-to-description object.`);
+			continue;
+		}
+		const at = described ? item.indexOf("=") : -1;
+		if (at > 0) {
+			mapped = true;
+			map[item.slice(0, at)] = item.slice(at + 1);
+		} else names.push(item);
+	}
+	if (!mapped) return {
+		list: names,
+		bare: true
+	};
+	for (const name of names) map[name] ??= "";
+	return {
+		list: map,
+		bare: false
+	};
+}
+//#endregion
+//#region src/cli/commands.ts
+/** The flags, for node:util parseArgs. */
+const OPTIONS = {
+	json: { type: "boolean" },
+	jsonl: { type: "boolean" },
+	raw: { type: "boolean" },
+	quiet: {
+		type: "boolean",
+		short: "q"
+	},
+	check: { type: "boolean" },
+	min: { type: "string" },
+	"min-confidence": { type: "string" },
+	key: { type: "string" },
+	"base-url": { type: "string" },
+	retries: { type: "string" },
+	timeout: { type: "string" },
+	usage: {
+		type: "boolean",
+		short: "v"
+	},
+	"no-color": { type: "boolean" },
+	help: {
+		type: "boolean",
+		short: "h"
+	},
+	version: {
+		type: "boolean",
+		short: "V"
+	},
+	file: {
+		type: "string",
+		short: "f",
+		multiple: true
+	},
+	lines: { type: "string" },
+	schema: { type: "string" },
+	tree: { type: "string" },
+	field: { type: "string" },
+	value: { type: "string" },
+	"when-true": { type: "string" },
+	"when-false": { type: "string" }
+};
+const need = (v, flag, example) => {
+	if (v === void 0 || v === "") throw new UsageError(`${flag} is required. For example: ${example}`);
+	return v;
+};
+const list = (l) => Array.isArray(l) ? l : Object.keys(l);
+const asRow = (r) => r;
+const asRows = (r) => r;
+/** `field` takes a bare name or `name=description`. The SDK sends `{ name }` for a bare one. */
+function fieldOf(raw) {
+	const at = raw.indexOf("=");
+	return at > 0 ? {
+		name: raw.slice(0, at),
+		description: raw.slice(at + 1)
+	} : raw;
+}
+const span = (r) => r.start === null ? "" : `${num(r, "start")}-${num(r, "end")}`;
+const HELP = `dm1 — typed decisions over text, from milliseconds.ai
+
+USAGE
+  dm1 <capability> [text] [args...] [options]
+  <command> | dm1 <capability> [args...]
+
+CAPABILITIES
+  classify       <text> <label[=description]>...   Pick one label
+  yes-no         <text> <statement>...             True or false, per statement
+  rate           <text> <level>...                 Place the text on a low-to-high scale
+  answer         <text> <question>...              Quote the answer out of the text
+  entities       <text> <type[=description]>...    Find every mention, with offsets
+  extract        <text> --schema <file|json>       Fill a JSON Schema
+  verify         <text> --field <name> --value <v> Check a value against the text
+  classify-tree  <text> --tree <file|json>         Walk a nested label tree
+  check                                            Test the key. Print the limits.
+
+TEXT
+  [text]              The text itself. Omit it, or pass -, to read stdin.
+  -f, --file <path>   Read the text from a file. Repeat it for a batch, in order.
+  --lines <path>      One text per line. Sent in chunks of 32, in order.
+  Piped input that starts with { becomes the whole request body. Flags still win.
+
+SPECIFICATION
+  A positional after the text is a label, statement, level, question or type.
+  name=description splits on the first =. A bare name has no description.
+  Any list also loads from a file: @labels.json holds an array or a name-to-description object.
+  --tree @taxonomy.json   --schema @invoice.json   @- reads stdin.
+  --when-true <s> --when-false <s>     yes-no hints
+  --field <name[=description]> --value <v>   verify
+
+OPTIONS
+  --json              Print JSON, even on a terminal.
+  --jsonl             One compact JSON result per line. For pipes.
+  --raw               Print the result with its API envelope.
+  -q, --quiet         Print the primary value only.
+  --check             yes-no and verify only. Exit 3 when the answer is no.
+  --min <p>           Exit 3 when probability is below <p>. Not rate or extract.
+  --min-confidence <c>  Exit 3 when confidence is below <c>. classify, rate and
+                        classify-tree only.
+  --key <key>         API key. Default: $MS_API_KEY.
+  --base-url <url>    Default: https://api.milliseconds.ai
+  --retries <n>       Retries on 429, 502, 529 and network errors. Default 2.
+  --timeout <ms>      Per attempt. Default 60000.
+  -v, --usage         Print tokens, model time and rate limits to stderr.
+  --no-color          No ANSI. NO_COLOR and a non-TTY stdout do the same.
+  -h, --help          This text. After a capability, that capability's help.
+  -V, --version
+
+DESCRIBE YOUR LABELS
+  The label text is the instruction. The model reads it literally.
+    dm1 classify "$T" billing shipping                     works
+    dm1 classify "$T" billing="charges and refunds" shipping="delivery and tracking"
+  The second call scores measurably better. Use name=description everywhere.
+
+EXIT CODES
+  0  decided          2  bad usage
+  1  API error        3  --check or --min failed
+
+EXAMPLES
+  dm1 classify "I was charged twice" billing shipping account
+  dm1 yes-no "Ship it today" "The customer expresses urgency." --check
+  dm1 rate "This is unacceptable" Calm Annoyed Angry "Threatening to leave"
+  dm1 entities "Ada met Grace in Paris" person place --json | jq -r '.[].text'
+  dm1 extract -f invoice.txt --schema @invoice.json
+  dm1 classify --lines tickets.txt billing shipping account --jsonl > labelled.ndjson
+  pbpaste | dm1 classify @labels.json
+
+  No key yet?  https://console.milliseconds.ai  then  export MS_API_KEY=sk-ms-...
+`;
+const CHECK_HELP = `
+  dm1 check [options]
+
+  Tests the key and prints the limits. It sends one small classify, about 20 tokens.
+  Do not run it in a health-check loop.
+
+  EXAMPLES
+    dm1 check
+    dm1 check --base-url https://api.milliseconds.ai --key sk-ms-...
+`;
+const CAPABILITIES = {
+	classify: {
+		name: "classify",
+		described: true,
+		envelope: null,
+		checkable: false,
+		probability: true,
+		confidence: true,
+		hint: "dm1 classify \"I was charged twice.\" billing=\"charges and refunds\" shipping=\"delivery\"",
+		help: `
+  dm1 classify [text] <label[=description]>... [options]
+
+  Picks one label and returns the full distribution.
+  POST /v1/decision-machine-1/classify
+
+  ARGUMENTS
+    [text]                  The text. Omit it, or pass -, to read stdin.
+    <label[=description]>   2 to 64 labels. Describe each one for better accuracy.
+                            @labels.json loads an array or a name-to-description object.
+
+  RESULT
+    label, probability, confidence, scores
+
+  PREDICATES
+    --min <p>               Exit 3 when probability is below p.
+    --min-confidence <c>    Exit 3 when confidence is below c.
+
+  EXAMPLES
+    dm1 classify "I was charged twice." billing="charges and refunds" shipping="delivery"
+    dm1 classify -f ticket.txt @labels.json --json
+    dm1 classify --lines tickets.txt @labels.json --jsonl | jq -r '.label'
+    cat ticket.txt | dm1 classify @labels.json --min 0.9 -q
+`,
+		call: (c) => c.dm.classify(c.input, c.list),
+		fragment: (c) => specSize(c.list) > 0 ? { labels: c.list } : {},
+		table: (r, dim) => {
+			const o = asRow(r);
+			return `${kv([
+				["label", text(o, "label")],
+				["probability", p3(num(o, "probability"))],
+				["confidence", p3(num(o, "confidence"))]
+			], dim)}\n\n${scores(Object.entries(o.scores), dim, true)}`;
+		},
+		quiet: (r) => [text(asRow(r), "label")]
+	},
+	"yes-no": {
+		name: "yes-no",
+		described: false,
+		envelope: "results",
+		checkable: true,
+		probability: true,
+		confidence: false,
+		hint: "dm1 yes-no \"Fix this today.\" \"The customer expresses urgency.\"",
+		help: `
+  dm1 yes-no [text] <statement>... [options]
+
+  Answers each statement with yes or no and a probability.
+  POST /v1/decision-machine-1/yes-no
+
+  ARGUMENTS
+    [text]          The text. Omit it, or pass -, to read stdin.
+    <statement>     1 to 32 third-person claims about the text. They share one
+                    inference call, so extra statements are nearly free.
+
+  FLAGS
+    --when-true <s>   What makes the statement true. It improves accuracy.
+    --when-false <s>  What makes it false.
+    --check           Exit 3 when the answer is no. In a batch, any no fails the run.
+
+  RESULT
+    statement, answer, probability
+
+  EXAMPLES
+    dm1 yes-no "Fix this today." "The customer expresses urgency."
+    dm1 yes-no -f reply.txt "The reply promises a refund." --check --min 0.9 -q
+    dm1 yes-no -f a.txt -f b.txt "The text mentions a price." --jsonl
+`,
+		call: (c) => c.dm.yesNo(c.input, list(c.list), {
+			...c.v["when-true"] === void 0 ? {} : { when_true: c.v["when-true"] },
+			...c.v["when-false"] === void 0 ? {} : { when_false: c.v["when-false"] }
+		}),
+		fragment: (c) => ({
+			...specSize(c.list) > 0 ? {
+				statements: list(c.list),
+				statement: void 0
+			} : {},
+			...c.v["when-true"] === void 0 ? {} : { when_true: c.v["when-true"] },
+			...c.v["when-false"] === void 0 ? {} : { when_false: c.v["when-false"] }
+		}),
+		table: (r) => columns(asRows(r).map((o) => [
+			o.answer === true ? "yes" : "no",
+			p3(num(o, "probability")),
+			text(o, "statement")
+		])),
+		quiet: (r) => asRows(r).map((o) => o.answer === true ? "yes" : "no")
+	},
+	rate: {
+		name: "rate",
+		described: false,
+		envelope: null,
+		checkable: false,
+		probability: false,
+		confidence: true,
+		hint: "dm1 rate \"I am done with this company.\" Calm Annoyed Angry \"Threatening to leave\"",
+		help: `
+  dm1 rate [text] <level>... [options]
+
+  Places the text on an ordered scale of described levels.
+  POST /v1/decision-machine-1/rate
+
+  ARGUMENTS
+    [text]      The text. Omit it, or pass -, to read stdin.
+    <level>     2 to 10 level descriptions, low to high, in order. Never numbers.
+
+  RESULT
+    score, level, label, confidence, scores
+    Route on score and confidence. level flips on 0.001.
+
+  EXAMPLES
+    dm1 rate "I am done with this company." Calm Annoyed Angry "Threatening to leave"
+    dm1 rate -f email.txt @scale.json --usage
+`,
+		call: (c) => c.dm.rate(c.input, list(c.list)),
+		fragment: (c) => specSize(c.list) > 0 ? { scale: list(c.list) } : {},
+		table: (r, dim, names) => {
+			const o = asRow(r);
+			const scale = o.scores.map((p, i) => [names[i] ?? `${i}`, p]);
+			return `${kv([
+				["label", text(o, "label")],
+				["score", num(o, "score").toFixed(2)],
+				["level", text(o, "level")],
+				["confidence", p3(num(o, "confidence"))]
+			], dim)}\n\n${scores(scale, dim, false)}`;
+		},
+		quiet: (r) => [text(asRow(r), "label")]
+	},
+	answer: {
+		name: "answer",
+		described: false,
+		envelope: "results",
+		checkable: false,
+		probability: true,
+		confidence: false,
+		hint: "dm1 answer -f press.txt \"Who announced the product?\" \"How much does it cost?\"",
+		help: `
+  dm1 answer [text] <question>... [options]
+
+  Quotes the answer out of the text, with its offsets.
+  POST /v1/decision-machine-1/answer
+
+  ARGUMENTS
+    [text]        The text. Omit it, or pass -, to read stdin.
+    <question>    1 to 32 questions. They share one inference call.
+                  Name the role, not the type: "the date the payment is due".
+
+  RESULT
+    question, answer, probability, start, end
+    answer is null when nothing fits. start and end are then null too.
+    Offsets index the text at the same position in the batch, never a joined string.
+
+  EXAMPLES
+    dm1 answer -f press.txt "Who announced the product?" "How much does it cost?"
+    curl -s https://example.com/press.txt | dm1 answer - "Who announced the product?"
+`,
+		call: (c) => c.dm.answer(c.input, list(c.list)),
+		fragment: (c) => specSize(c.list) > 0 ? {
+			questions: list(c.list),
+			question: void 0
+		} : {},
+		table: (r) => columns(asRows(r).map((o) => [
+			o.answer === null ? "-" : text(o, "answer"),
+			p3(num(o, "probability")),
+			span(o),
+			text(o, "question")
+		])),
+		quiet: (r) => asRows(r).map((o) => o.answer === null ? "" : text(o, "answer"))
+	},
+	entities: {
+		name: "entities",
+		described: true,
+		envelope: "entities",
+		checkable: false,
+		probability: true,
+		confidence: false,
+		hint: "dm1 entities \"Ada met Grace in Paris.\" person=\"a human name\" place=\"a city or country\"",
+		help: `
+  dm1 entities [text] <type[=description]>... [options]
+
+  Finds every span matching each type, with offsets.
+  POST /v1/decision-machine-1/entities
+
+  ARGUMENTS
+    [text]                 The text. Omit it, or pass -, to read stdin.
+    <type[=description]>   1 to 64 entity types. Describe each one.
+
+  RESULT
+    A list of { type, text, probability, start, end }, sorted by start.
+
+  EXAMPLES
+    dm1 entities "Ada met Grace in Paris." person="a human name" place="a city or country"
+    pbpaste | dm1 entities @types.json --json | jq -r '.[] | select(.type=="person") | .text'
+`,
+		call: (c) => c.dm.entities(c.input, c.list),
+		fragment: (c) => specSize(c.list) > 0 ? { types: c.list } : {},
+		table: (r) => columns(asRows(r).map((o) => [
+			text(o, "type"),
+			text(o, "text"),
+			p3(num(o, "probability")),
+			span(o)
+		])),
+		quiet: (r) => asRows(r).map((o) => text(o, "text"))
+	},
+	extract: {
+		name: "extract",
+		described: true,
+		envelope: "data",
+		checkable: false,
+		probability: false,
+		confidence: false,
+		hint: "dm1 extract -f invoice.txt --schema @invoice.json --json > invoice.json",
+		help: `
+  dm1 extract [text] --schema <file|json> [options]
+
+  Fills a JSON Schema from the text.
+  POST /v1/decision-machine-1/extract
+
+  FLAGS
+    --schema @invoice.json   The JSON Schema. @- reads stdin. Inline JSON works too.
+
+  RESULT
+    The data object. Missing values are null. Arrays of objects come back empty.
+    Arrays of scalars come back as strings. Enums are not checked server side.
+
+  EXAMPLES
+    dm1 extract -f invoice.txt --schema @invoice.json --json > invoice.json
+    dm1 extract -f a.txt -f b.txt --schema @invoice.json --jsonl
+`,
+		call: (c) => c.dm.extract(c.input, loadDocument("schema", need(c.v.schema, "--schema", "dm1 extract -f invoice.txt --schema @invoice.json"), c.stdin)),
+		fragment: (c) => c.v.schema === void 0 ? {} : { schema: loadDocument("schema", c.v.schema, c.stdin) },
+		table: (r) => columns(Object.entries(asRow(r)).map(([k, v]) => [k, v === null ? "-" : typeof v === "object" ? JSON.stringify(v) : String(v)])),
+		quiet: (r) => [JSON.stringify(r)]
+	},
+	verify: {
+		name: "verify",
+		described: false,
+		envelope: null,
+		checkable: true,
+		probability: true,
+		confidence: false,
+		hint: "dm1 verify -f invoice.txt --field total --value 999 --json | jq .found",
+		help: `
+  dm1 verify [text] --field <name[=description]> --value <v> [options]
+
+  Checks whether the text says <v> for <field>.
+  POST /v1/decision-machine-1/verify
+
+  FLAGS
+    --field <name[=description]>   The field to read out of the text.
+    --value <v>                    The value you already hold.
+    --check                        Exit 3 when the value does not match.
+
+  RESULT
+    matches, probability, found
+    found shows what the text actually says.
+
+  EXAMPLES
+    dm1 verify -f invoice.txt --field invoice_number="the identifier printed on the invoice" \\
+      --value 4471 --check
+    dm1 verify -f invoice.txt --field total --value 999 --json | jq .found
+`,
+		call: (c) => c.dm.verify(c.input, fieldOf(need(c.v.field, "--field", "dm1 verify -f invoice.txt --field total --value 999")), need(c.v.value, "--value", "dm1 verify -f invoice.txt --field total --value 999")),
+		fragment: (c) => ({
+			...c.v.field === void 0 ? {} : { field: fieldOf(c.v.field) },
+			...c.v.value === void 0 ? {} : { value: c.v.value }
+		}),
+		table: (r, dim) => {
+			const o = asRow(r);
+			return kv([
+				["matches", o.matches === true ? "yes" : "no"],
+				["probability", p3(num(o, "probability"))],
+				["found", o.found.join(", ")]
+			], dim);
+		},
+		quiet: (r) => [asRow(r).matches === true ? "yes" : "no"]
+	},
+	"classify-tree": {
+		name: "classify-tree",
+		described: false,
+		envelope: null,
+		checkable: false,
+		probability: true,
+		confidence: true,
+		hint: "dm1 classify-tree -f ticket.txt --tree @taxonomy.json --json",
+		help: `
+  dm1 classify-tree [text] --tree <file|json> [options]
+
+  Runs classify once per level of a nested tree, descending into the winner.
+  POST /v1/decision-machine-1/classify-tree
+
+  FLAGS
+    --tree @taxonomy.json   name -> description, or name -> { description, labels }.
+                            2 to 64 labels per level, at most 8 levels.
+
+  RESULT
+    path, label, probability, confidence, levels[]
+    probability and confidence are products over the levels, so they fall with depth.
+    Each level re-sends the text, so the per-level input numbers do not sum to the
+    x-input-chars header.
+
+  EXAMPLES
+    dm1 classify-tree -f ticket.txt --tree @taxonomy.json --json
+    dm1 classify-tree "I want my money back." --tree @taxonomy.json -q
+`,
+		call: (c) => c.dm.classifyTree(c.input, loadDocument("tree", need(c.v.tree, "--tree", "dm1 classify-tree -f ticket.txt --tree @taxonomy.json"), c.stdin)),
+		fragment: (c) => c.v.tree === void 0 ? {} : { tree: loadDocument("tree", c.v.tree, c.stdin) },
+		table: (r, dim) => {
+			const o = asRow(r);
+			const levels = o.levels;
+			const head = kv([
+				["label", text(o, "label")],
+				["path", o.path.join(" > ")],
+				["probability", p3(num(o, "probability"))],
+				["confidence", p3(num(o, "confidence"))]
+			], dim);
+			const body = columns(levels.map((l, i) => [
+				`  ${i + 1}`,
+				text(l, "label"),
+				p3(num(l, "probability")),
+				p3(num(l, "confidence")),
+				`${int(num(l, "inference_ms"))} ms`
+			]));
+			return `${head}\n\n${dim("levels")}\n${body}`;
+		},
+		quiet: (r) => [text(asRow(r), "label")]
+	}
+};
+//#endregion
+//#region src/cli/input.ts
+/** One trailing newline is a file ending, not text. It would bill and print. */
+function readFile(path) {
+	try {
+		return readFileSync(path, "utf8").replace(/\r?\n$/, "");
+	} catch (e) {
+		throw new UsageError(`cannot read ${path}: ${e.message}`);
+	}
+}
+const NO_TEXT = "no text. Pass the text, or -f <file>, or --lines <file>, or pipe the text in.";
+/** A @file and a name=description are list arguments. Anything else could be the text. */
+const listOnly = (item) => item.startsWith("@") || item.includes("=");
+/** The pipe wins over a positional, so say which argument lost the text. */
+const shadowed = (first) => `dm1: the text comes from stdin. "${first.length > 32 ? `${first.slice(0, 31)}…` : first}" is a list argument, not the text. Pass - to silence this.`;
+/**
+* One source only.
+*
+* `--file` and `--lines` win. A leading `-` reads stdin. A pipe that carries text reads
+* stdin, and every positional then belongs to the capability's list. Otherwise the first
+* positional is the text. No text anywhere is a usage error.
+*/
+function resolveInput(s) {
+	if (s.lines !== void 0) {
+		const texts = readFile(s.lines).split(/\r?\n/).filter((line) => line.trim() !== "");
+		if (texts.length === 0) throw new UsageError(`${s.lines} holds no text.`);
+		return {
+			input: texts,
+			items: s.positionals
+		};
+	}
+	if (s.files.length > 0) {
+		const texts = s.files.map(readFile);
+		return {
+			input: texts.length === 1 ? texts[0] : texts,
+			items: s.positionals
+		};
+	}
+	let items = s.positionals;
+	let explicit = false;
+	if (items[0] === "-") {
+		explicit = true;
+		items = items.slice(1);
+	}
+	const raw = explicit || !s.stdinIsTty ? s.stdin() : "";
+	const trimmed = raw.trim();
+	if (trimmed === "") {
+		if (explicit) throw new UsageError("stdin is empty. Send the text in, or pass -f <file>.");
+		if (items.length === 0) throw new UsageError(NO_TEXT);
+		return {
+			input: items[0],
+			items: items.slice(1)
+		};
+	}
+	if (!trimmed.startsWith("{")) {
+		const first = items[0];
+		const quiet = explicit || first === void 0 || listOnly(first);
+		return {
+			input: raw.replace(/\r?\n$/, ""),
+			items,
+			...quiet ? {} : { note: shadowed(first) }
+		};
+	}
+	let body;
+	try {
+		body = JSON.parse(trimmed);
+	} catch (e) {
+		throw new UsageError(`stdin starts with { but is not JSON: ${e.message}. Fix the JSON, or send plain text with -f <file>.`);
+	}
+	if (Array.isArray(body.texts)) {
+		if (body.texts.length === 0) throw new UsageError("the piped body has an empty texts array. Send at least one text.");
+		return {
+			input: body.texts,
+			items,
+			body
+		};
+	}
+	if (typeof body.text !== "string") throw new UsageError("the piped body has no text and no texts. Add one of them to the JSON.");
+	return {
+		input: body.text,
+		items,
+		body
+	};
+}
+function chunk(texts) {
+	const out = [];
+	for (let i = 0; i < texts.length; i += 32) out.push(texts.slice(i, i + 32));
+	return out;
+}
+//#endregion
+//#region src/cli/run.ts
+const VERSION = "0.1.0";
+const path = (name) => `/v1/decision-machine-1/${name}`;
+const wrapOne = (v, env) => env === null ? v : env === "results" ? { results: v } : env === "entities" ? { entities: v } : { data: v };
+const unwrapOne = (raw, env) => env === null ? raw : raw[env];
+const number = (flag, raw) => {
+	const n = Number(raw);
+	if (!Number.isFinite(n)) throw new UsageError(`${flag} takes a number, not ${raw}.`);
+	return n;
+};
+/** Every result of one text: the object itself, or each element of a list. */
+const items = (result) => Array.isArray(result) ? result : [result];
+/** `dm1: <code>: <message>` on stderr, then the capability's first example. */
+function fail(io, e, cap) {
+	const hint = () => {
+		if (cap) io.err(`\n  ${cap.hint}`);
+	};
+	if (e instanceof UsageError) {
+		io.err(`dm1: usage: ${e.message}`);
+		hint();
+		return 2;
+	}
+	if (isMillisecondsError(e)) {
+		io.err(`dm1: ${e.code}: ${e.message}`);
+		const local = e.status === 0 && (e.code === "client_error" || e.code === "invalid_schema");
+		if (local) hint();
+		return local ? 2 : 1;
+	}
+	io.err(`dm1: internal_error: ${e.message}`);
+	return 1;
+}
+async function run(io) {
+	const found = {};
+	try {
+		return await dispatch(io, found);
+	} catch (e) {
+		return fail(io, e, found.cap);
+	}
+}
+async function dispatch(io, found) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: io.argv,
+			options: OPTIONS,
+			allowPositionals: true
+		});
+	} catch (e) {
+		throw new UsageError(`${e.message}\n  Run dm1 --help.`);
+	}
+	const v = parsed.values;
+	const [name, ...rest] = parsed.positionals;
+	if (v.version) {
+		io.out(VERSION);
+		return 0;
+	}
+	if (name === void 0) {
+		io.out(HELP);
+		return 0;
+	}
+	const color = io.stdoutIsTty && v["no-color"] !== true && !io.env.NO_COLOR;
+	if (name === "check") {
+		if (v.help === true) {
+			io.out(CHECK_HELP);
+			return 0;
+		}
+		return await check(io, client(io, v), v, color);
+	}
+	const cap = CAPABILITIES[name];
+	if (!cap) throw new UsageError(`unknown capability ${name}. Run dm1 --help.`);
+	found.cap = cap;
+	if (v.help === true) {
+		io.out(cap.help);
+		return 0;
+	}
+	if (v.check === true && !cap.checkable) throw new UsageError(`--check works with yes-no and verify only, not ${name}.`);
+	const min = v.min === void 0 ? null : number("--min", v.min);
+	const minConfidence = v["min-confidence"] === void 0 ? null : number("--min-confidence", v["min-confidence"]);
+	if (min !== null && !cap.probability) throw new UsageError(`--min reads a probability. A ${name} result carries none.`);
+	if (minConfidence !== null && !cap.confidence) throw new UsageError(`--min-confidence reads a confidence. A ${name} result carries none.`);
+	const piped = io.argv.includes("-") || io.argv.includes("@-") || !io.stdinIsTty && v.lines === void 0 && (v.file ?? []).length === 0 ? await io.stdin() : "";
+	const stdin = () => piped;
+	const source = resolveInput({
+		files: v.file ?? [],
+		lines: v.lines,
+		positionals: rest,
+		stdin,
+		stdinIsTty: io.stdinIsTty
+	});
+	if (source.note !== void 0) io.err(source.note);
+	const spec = parseSpec(source.items, cap.described, stdin);
+	const names = Array.isArray(spec.list) ? spec.list : Object.keys(spec.list);
+	const bare = spec.bare ? names[0] : void 0;
+	const dm = client(io, v);
+	const mode = v.raw === true ? "raw" : v.jsonl === true ? "jsonl" : v.quiet === true ? "quiet" : v.json === true || !io.stdoutIsTty ? "json" : "table";
+	const body = source.body ? {
+		...source.body,
+		...cap.fragment({
+			dm,
+			input: source.input,
+			list: spec.list,
+			v,
+			stdin
+		})
+	} : null;
+	const batch = Array.isArray(source.input);
+	const env = body ? envelopeOf(cap, body) : cap.envelope;
+	const pieces = batch ? chunk(source.input) : [source.input];
+	const decided = [];
+	const total = {
+		chars: 0,
+		tokens: 0,
+		ms: 0,
+		rateLimit: null
+	};
+	const streaming = mode === "jsonl" || mode === "quiet";
+	for (const [i, piece] of pieces.entries()) {
+		let value;
+		let usage;
+		try {
+			const got = await (body ? dm.post(path(cap.name), body) : cap.call({
+				dm,
+				input: piece,
+				list: spec.list,
+				v,
+				stdin
+			})).withUsage();
+			usage = got.usage;
+			value = body ? unwrapBody(got.result, env, batch) : got.result;
+		} catch (e) {
+			if (pieces.length > 1 && isMillisecondsError(e) && e.status !== 0) {
+				if (!streaming) emit(io, decided, mode, cap, color, batch, bare, names);
+				const first = i * 32 + 1;
+				io.err(`dm1: ${e.code}: chunk ${i + 1} of ${pieces.length} (texts ${first}-${first + piece.length - 1}) failed.\n${e.message}`);
+				if (v.usage === true) io.err(usageLine(total));
+				return 1;
+			}
+			if (v.usage === true && total.chars > 0) io.err(usageLine(total));
+			throw e;
+		}
+		total.chars += usage.inputChars;
+		total.tokens += usage.inputTokens;
+		total.ms += usage.inferenceMs;
+		total.rateLimit = usage.rateLimit ?? total.rateLimit;
+		const part = Array.isArray(piece) ? piece.map((t, k) => ({
+			text: t,
+			result: value[k],
+			raw: wrapOne(value[k], env)
+		})) : [{
+			text: piece,
+			result: value,
+			raw: wrapOne(value, env)
+		}];
+		if (streaming) emit(io, part, mode, cap, color, batch, bare, names);
+		decided.push(...part);
+	}
+	if (!streaming) emit(io, decided, mode, cap, color, batch, bare, names);
+	if (v.usage === true) io.err(usageLine(total));
+	return failed(decided, v, min, minConfidence, cap) ? 3 : 0;
+}
+/** The CLI never chunks a piped body: the user wrote it, so the SDK sends it unchanged. */
+function unwrapBody(raw, env, batch) {
+	if (!batch) return unwrapOne(raw, env);
+	return (raw.results ?? []).map((r) => unwrapOne(r, env));
+}
+/** A piped body picks its own shape: `statement` answers one result, `statements` a list. */
+function envelopeOf(cap, body) {
+	if (cap.name === "yes-no") return body.statement === void 0 ? "results" : null;
+	if (cap.name === "answer") return body.question === void 0 ? "results" : null;
+	return cap.envelope;
+}
+function client(io, v) {
+	if (!(v.key ?? io.env.MS_API_KEY)) throw new UsageError("no API key. Run export MS_API_KEY=sk-ms-..., or pass --key. Get a key at https://console.milliseconds.ai.");
+	return new DecisionMachine({
+		apiKey: v.key ?? io.env.MS_API_KEY,
+		...v["base-url"] === void 0 ? {} : { baseUrl: v["base-url"] },
+		...v.retries === void 0 ? {} : { maxRetries: number("--retries", v.retries) },
+		...v.timeout === void 0 ? {} : { timeout: number("--timeout", v.timeout) },
+		...io.fetch ? { fetch: io.fetch } : {}
+	});
+}
+/** stdout holds results only. One blank line separates the texts of a batch. */
+function emit(io, decided, mode, cap, color, batch, bare, names) {
+	if (decided.length === 0) return;
+	const dim = dimmer(color);
+	const indent = io.stdoutIsTty ? 2 : 0;
+	if (mode === "raw") {
+		const raws = decided.map((d) => d.raw);
+		io.out(JSON.stringify(batch ? { results: raws } : raws[0], null, indent));
+		return;
+	}
+	if (mode === "json") {
+		const results = decided.map((d) => d.result);
+		io.out(JSON.stringify(batch ? results : results[0], null, indent));
+		return;
+	}
+	if (mode === "jsonl") {
+		for (const d of decided) io.out(JSON.stringify(line(d, cap.envelope)));
+		return;
+	}
+	if (mode === "quiet") {
+		for (const d of decided) for (const l of cap.quiet(d.result)) io.out(l);
+		return;
+	}
+	const blocks = decided.map((d) => batch ? `${dim(head(d.text))}\n${cap.table(d.result, dim, names)}` : cap.table(d.result, dim, names));
+	io.out(blocks.join("\n\n"));
+	if (bare !== void 0 && cap.name === "classify") io.out(`\n  Bare label names score worse. Try: ${bare}="charges and refunds"`);
+}
+const head = (text) => text.length > 72 ? `${text.slice(0, 71)}…` : text;
+/** One compact object per line, with the input text, so a batch stays joinable. */
+function line(d, env) {
+	if (Array.isArray(d.result)) return {
+		text: d.text,
+		[env ?? "results"]: d.result
+	};
+	return {
+		...d.result,
+		text: d.text
+	};
+}
+function usageLine(t) {
+	const rate = t.rateLimit ? `, ${int(t.rateLimit.remainingRequests)}/${int(t.rateLimit.limitRequests)} requests left` : "";
+	return `usage: ${int(t.chars)} chars, ${int(t.tokens)} tokens, ${int(t.ms)} ms inference${rate}`;
+}
+/** `--check`, `--min` and `--min-confidence`. The result still printed, so this only exits 3. */
+function failed(decided, v, min, minConfidence, cap) {
+	if (v.check !== true && min === null && minConfidence === null) return false;
+	for (const d of decided) {
+		const list = items(d.result);
+		if (v.check === true && list.length === 0) return true;
+		for (const item of list) {
+			if (v.check === true) {
+				if (!(cap.name === "verify" ? item.matches === true : item.answer === true)) return true;
+			}
+			if (min !== null && typeof item.probability === "number" && item.probability < min) return true;
+			if (minConfidence !== null && typeof item.confidence === "number" && item.confidence < minConfidence) return true;
+		}
+	}
+	return false;
+}
+/** One small classify. It proves the key, the endpoint and the limits. */
+async function check(io, dm, v, color) {
+	const started = Date.now();
+	const { usage } = await dm.classify("ok", ["yes", "no"]).withUsage();
+	const round = Date.now() - started;
+	const key = v.key ?? io.env.MS_API_KEY ?? "";
+	const masked = key.length > 16 ? `${key.slice(0, 12)}…${key.slice(-4)}` : key;
+	const rl = usage.rateLimit;
+	if (v.json === true || !io.stdoutIsTty) {
+		io.out(JSON.stringify({
+			key: masked,
+			endpoint: dm.baseUrl,
+			round_trip_ms: round,
+			inference_ms: usage.inferenceMs,
+			rate_limit: rl
+		}, null, io.stdoutIsTty ? 2 : 0));
+		return 0;
+	}
+	const limits = rl ? `${int(rl.limitRequests)} req/min` : "unknown";
+	const remaining = rl ? `${int(rl.remainingRequests)} req` : "unknown";
+	const width = Math.max(limits.length, remaining.length);
+	const dim = dimmer(color);
+	io.out(kv([
+		["key", `${masked}   valid`],
+		["endpoint", dm.baseUrl],
+		["latency", `${int(round)} ms round trip · ${int(usage.inferenceMs)} ms model`],
+		["limits", rl ? `${limits.padEnd(width)}  ·  ${int(rl.limitTokens)} tok/min` : "unknown"],
+		["remaining", rl ? `${remaining.padEnd(width)}  ·  ${int(rl.remainingTokens)} tok` : "unknown"]
+	], dim, 10));
+	io.out("ok");
+	return 0;
+}
+//#endregion
+//#region src/cli/index.ts
+/** All of stdin. A pipe ends it; a terminal ends it on Ctrl-D. */
+async function stdin() {
+	const parts = [];
+	for await (const part of process.stdin) parts.push(part);
+	return Buffer.concat(parts).toString("utf8");
+}
+process.exitCode = await run({
+	argv: process.argv.slice(2),
+	env: process.env,
+	out: (line) => process.stdout.write(`${line}\n`),
+	err: (line) => process.stderr.write(`${line}\n`),
+	stdin,
+	stdinIsTty: process.stdin.isTTY === true,
+	stdoutIsTty: process.stdout.isTTY === true
+});
+//#endregion
+export {};