@dolusoft/command-console-core 1.0.1 → 1.1.0

package/dist/command-console-core.js

@@ -1,4 +1,4 @@
-import { quoteArgument, tokenize } from "@dolusoft/command-protocol";
+import { checkInputSchema, envelopeBytes, envelopeMaxBytes, formatCommandLine, parseEnvelope, parseOptions, quoteArgument, tokenize, validateInput } from "@dolusoft/command-protocol";
 // src/shared/registry.ts
 var createHooks = () => ({
 	lineSubmitted: [],
@@ -316,8 +316,9 @@ var checkName = (name, where) => {
 /**
 * Validates the commands (core README: Options, C-56): names and aliases are
 * non-empty, without whitespace or quotes, unique across every name and alias;
-* `fromArg` is a non-negative integer; `run` is a function. Throws on the
-* first violation.
+* `fromArg` is a non-negative integer; `run` is a function; `input` is an
+* input schema, `danger` a known value and `normalize` a function (C-76).
+* Throws on the first violation.
 */
 var validateCommands = (commands) => {
 	if (!Array.isArray(commands)) throw new Error("commands must be an array of command definitions.");
@@ -332,8 +333,24 @@ var validateCommands = (commands) => {
 		const { sensitive } = command;
 		if (sensitive !== void 0 && typeof sensitive !== "boolean" && !(typeof sensitive === "object" && sensitive !== null && Number.isInteger(sensitive.fromArg) && sensitive.fromArg >= 0)) throw new Error(`command ${command.name}: sensitive must be a boolean or { fromArg } with a non-negative integer.`);
 		if (typeof command.run !== "function") throw new Error(`command ${command.name}: run must be a function.`);
+		checkDescription(command);
 	}
 };
+var dangers = [
+	"read",
+	"change",
+	"irreversible"
+];
+/** The checks of C-76: `input`, `danger` and `normalize`. */
+var checkDescription = (command) => {
+	if (command.input !== void 0) try {
+		checkInputSchema(command.input);
+	} catch (error) {
+		throw new TypeError(`command ${command.name}: ${error.message}`, { cause: error });
+	}
+	if (command.danger !== void 0 && !dangers.includes(command.danger)) throw new Error(`command ${command.name}: danger must be 'read', 'change' or 'irreversible'.`);
+	if (command.normalize !== void 0 && typeof command.normalize !== "function") throw new Error(`command ${command.name}: normalize must be a function.`);
+};
 /** The JSON spec of a command, without its functions (`getCommands`). */
 var specOf = (command) => {
 	const spec = {
@@ -343,6 +360,8 @@ var specOf = (command) => {
 	if (command.summary !== void 0) spec.summary = command.summary;
 	if (command.usage !== void 0) spec.usage = command.usage;
 	if (command.sensitive !== void 0) spec.sensitive = typeof command.sensitive === "object" ? { fromArg: command.sensitive.fromArg } : command.sensitive;
+	if (command.input !== void 0) spec.input = JSON.parse(JSON.stringify(command.input));
+	if (command.danger !== void 0) spec.danger = command.danger;
 	return spec;
 };
 /** A command's return as a response (README: Running a line, End action). */
@@ -361,6 +380,73 @@ var blocksOf = (output) => {
 };
 /** Whether `value` is a promise or another thenable. */
 var isThenable = (value) => (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+// src/core/dispatch/operation.ts
+/** How many closed envelope ids a console remembers (C-81). */
+var closedLimit = 500;
+/** The longest `summary` an outcome carries, in code points (C-82). */
+var summaryLimit = 200;
+/** Whether two JSON values are equal, objects compared by their keys. */
+var sameJson = (a, b) => {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) return false;
+	const left = Object.keys(a);
+	const right = b;
+	return left.length === Object.keys(right).length && left.every((key) => Object.hasOwn(right, key) && sameJson(a[key], right[key]));
+};
+/** Remembers `id` among the newest `closedLimit` closed ids. */
+var rememberClosed = (closed, id) => {
+	closed.delete(id);
+	closed.add(id);
+	if (closed.size > closedLimit) closed.delete(closed.values().next().value);
+};
+/** `summary` cut to `summaryLimit` code points; `undefined` unless a string. */
+var cutSummary = (summary) => typeof summary === "string" ? Array.from(summary).slice(0, summaryLimit).join("") : void 0;
+/** An RFC 4122 version 4 UUID from 16 random bytes. */
+var uuidV4 = (bytes) => {
+	bytes[6] = bytes[6] & 15 | 64;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+	return [
+		hex.slice(0, 4),
+		hex.slice(4, 6),
+		hex.slice(6, 8),
+		hex.slice(8, 10),
+		hex.slice(10, 16)
+	].map((part) => part.join("")).join("-");
+};
+/**
+* The page's UUID function: `crypto.randomUUID`, else a v4 UUID from
+* `crypto.getRandomValues` (a page on an insecure origin has only the
+* latter), else none.
+*/
+var randomUUID = () => {
+	const crypto = globalThis.crypto;
+	if (typeof crypto?.randomUUID === "function") return () => crypto.randomUUID();
+	if (typeof crypto?.getRandomValues === "function") return () => uuidV4(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)));
+};
+/**
+* What makes envelope ids: `createEnvelopeId`, else the page's UUID function.
+* Throws when a gate is given and neither exists (C-78).
+*/
+var envelopeIds = (options) => {
+	const create = options.createEnvelopeId ?? randomUUID();
+	if (options.gate !== void 0 && create === void 0) throw new Error("A console with a gate needs crypto.randomUUID, crypto.getRandomValues or a createEnvelopeId option.");
+	return create;
+};
+/**
+* Checks the gate options at creation and on every `setOptions` (C-78):
+* envelope ids can be made, and `echoTimeoutMs` is a finite number above 0.
+*/
+var checkGateOptions = (options) => {
+	envelopeIds(options);
+	const ms = options.echoTimeoutMs;
+	if (ms !== void 0 && !(typeof ms === "number" && Number.isFinite(ms) && ms > 0)) throw new TypeError(`echoTimeoutMs must be a finite number above 0 (got ${typeof ms === "number" ? ms : typeof ms}).`);
+};
+/**
+* Whether a command can travel in an envelope: it has `input` and `danger`
+* and no `sensitive` (C-79).
+*/
+var describedCommand = (command) => command.input !== void 0 && command.danger !== void 0 && (command.sensitive === void 0 || command.sensitive === false);
 // src/core/console/consoleFeature.ts
 var controllable$1 = [
 	"entries",
@@ -420,7 +506,9 @@ var consoleFeature = {
 				const previous = record.options;
 				const given = resolveUpdater(updater, previous);
 				if (!sameFeatures(previous.features, given.features)) throw new Error("setOptions cannot change the feature set.");
+				if (given.gate !== previous.gate) throw new Error("setOptions cannot change the gate.");
 				validateCommands(given.commands);
+				checkGateOptions(given);
 				store.action(() => {
 					const before = { ...store.read() };
 					record.options = mergeOptions(featureDefaults.get(console), given);
@@ -489,6 +577,37 @@ var consoleFeature = {
 		});
 	}
 };
+// src/core/dispatch/commandError.ts
+var commandCodes = [
+	"target-not-found",
+	"invalid-args",
+	"failed"
+];
+/**
+* Thrown (or rejected) by a command's `run` to end the run with `code`: the
+* run fails as with any error (`onError`, the error entry), and the outcome a
+* `request()` resolves is `{ status: 'error', code }`.
+*/
+var CommandError = class extends Error {
+	/** The code the run's outcome carries. */
+	code;
+	constructor(code, message, options) {
+		super(message ?? code, options);
+		this.name = "CommandError";
+		this.code = code;
+	}
+};
+/**
+* The outcome code of an error a command's `run` threw: a `CommandError`'s
+* code when a command may give it, else `failed` (C-86). The error is known
+* by its `name`, not by `instanceof`: a command built against a second copy
+* of the core throws a `CommandError` of another class.
+*/
+var commandErrorCode = (error) => {
+	if (!(error instanceof Error) || error.name !== "CommandError") return "failed";
+	const { code } = error;
+	return commandCodes.includes(code) ? code : "failed";
+};
 // src/core/dispatch/sensitivity.ts
 /**
 * The first secret argument position of `command`: `0` for
@@ -726,14 +845,31 @@ var output = (tone, blocks, inputId, quiet) => quiet === true ? {
 	blocks,
 	inputId
 };
-/** Clears `running` when it still names `run` and resolves its promise. */
+var failure = (code) => ({
+	status: "error",
+	code
+});
+/**
+* Clears `running` when it still names `run`, cancels the echo timer,
+* records the envelope id as closed and resolves the run's promises.
+*/
 var cleanup = (console, run) => {
 	if (run.cleaned) return;
 	run.cleaned = true;
+	run.waiting = false;
 	const state = stateOf(console);
 	if (state.run === run) state.run = null;
+	if (run.envelope) rememberClosed(state.closed, run.envelope.id);
+	const cancelTimer = run.cancelTimer;
+	run.cancelTimer = null;
+	if (cancelTimer) try {
+		cancelTimer();
+	} catch (error) {
+		reportCallbackError(console, error);
+	}
 	recordOf(console)?.store.update("running", (running) => running?.runId === run.id ? null : running);
 	run.resolve(true);
+	run.onOutcome?.(run.outcome);
 };
 /** Effects in order, then the output (README: Running a line, B-29). */
 var apply = (console, run, response, defaultTone) => {
@@ -742,16 +878,28 @@ var apply = (console, run, response, defaultTone) => {
 	const blocks = blocksOf(response.output);
 	if (blocks.length > 0) addEntry(console, output(response.tone ?? defaultTone, blocks, run.inputId, response.quiet));
 };
+/** Ends `run` with what it returned; an `error` tone is `failed` (C-87). */
 var fulfil = (console, run, value) => {
 	run.current = false;
 	try {
-		apply(console, run, normalizeReturn(value), "default");
+		const response = normalizeReturn(value);
+		const summary = cutSummary(response.summary);
+		run.outcome = response.tone === "error" ? failure("failed") : summary === void 0 ? { status: "ok" } : {
+			status: "ok",
+			summary
+		};
+		apply(console, run, response, "default");
 	} finally {
 		cleanup(console, run);
 	}
 };
-var fail = (console, run, error) => {
+/**
+* Ends `run` as failed (C-18); `code` is the outcome's code, `failed` unless
+* the command's own `run` threw a `CommandError` (C-86).
+*/
+var fail = (console, run, error, code = "failed") => {
 	run.current = false;
+	run.outcome = failure(code);
 	try {
 		const { store, options } = liveRecord(console);
 		store.afterCommit(() => reportError(recordOf(console)?.options.onError, error, run.info));
@@ -768,11 +916,27 @@ var fail = (console, run, error) => {
 	}
 };
 /** Ends `run` without output and without an entry (`false`, reset, dispose). */
-var stop = (console, run, abort) => {
+var stop = (console, run, abort, code) => {
 	run.current = false;
+	run.outcome = failure(code);
 	if (abort) run.controller.abort();
 	cleanup(console, run);
 };
+/**
+* Ends an operation that did not run its command with an `operation-failed`
+* entry (C-79, C-80); `error` goes to `onError` with the run's info.
+*/
+var close$1 = (console, run, code, error) => {
+	run.current = false;
+	run.outcome = failure(code);
+	run.controller.abort();
+	try {
+		if (error) liveRecord(console).store.afterCommit(() => reportError(recordOf(console)?.options.onError, error, run.info));
+		addEntry(console, output("error", [message("operation-failed", { code })], run.inputId));
+	} finally {
+		cleanup(console, run);
+	}
+};
 /** Runs `fn` as its own action if `run` is still current (a settle). */
 var settle = (console, run, fn) => {
 	if (!run.current || isDisposed(console)) return;
@@ -781,16 +945,21 @@ var settle = (console, run, fn) => {
 		if (run.current) fn();
 	});
 };
-/** Handles a return that may be a promise: now, or in its own action. */
-var whenSettled = (console, run, value, onValue) => {
-	if (isThenable(value)) Promise.resolve(value).then((result) => settle(console, run, () => onValue(result)), (error) => settle(console, run, () => fail(console, run, error)));
+/**
+* Handles a return that may be a promise: now, or in its own action. A
+* rejection fails the run with the code `codeOf` gives it.
+*/
+var whenSettled = (console, run, value, onValue, codeOf = () => "failed") => {
+	if (isThenable(value)) Promise.resolve(value).then((result) => settle(console, run, () => onValue(result)), (error) => settle(console, run, () => fail(console, run, error, codeOf(error))));
 	else onValue(value);
 };
+var toRunning = (console, run) => liveRecord(console).store.update("running", (running) => running?.runId === run.id ? {
+	...running,
+	phase: "running"
+} : running);
+/** Calls the command's `run`. */
 var go = (console, run) => {
-	liveRecord(console).store.update("running", (running) => running?.runId === run.id ? {
-		...running,
-		phase: "running"
-	} : running);
+	toRunning(console, run);
 	const context = {
 		runId: run.id,
 		inputId: run.inputId,
@@ -801,10 +970,10 @@ var go = (console, run) => {
 	try {
 		result = run.command.run(run.request, context);
 	} catch (error) {
-		fail(console, run, error);
+		fail(console, run, error, commandErrorCode(error));
 		return;
 	}
-	whenSettled(console, run, result, (value) => fulfil(console, run, value));
+	whenSettled(console, run, result, (value) => fulfil(console, run, value), commandErrorCode);
 };
 var write$1 = (console, run, out, tone) => {
 	settle(console, run, () => {
@@ -812,7 +981,106 @@ var write$1 = (console, run, out, tone) => {
 		if (blocks.length > 0) addEntry(console, output(tone ?? "default", blocks, run.inputId));
 	});
 };
-var start = (console, command, request, inputId, sensitive) => {
+/** What the gate delivered: the echo of the pending envelope, or nothing. */
+var receive = (console, raw) => {
+	const record = recordOf(console);
+	const gate = record?.options.gate;
+	if (!record || !gate) return;
+	const parsed = parseEnvelope(raw);
+	if (!parsed.ok) return;
+	const echo = parsed.envelope;
+	const state = stateOf(console);
+	const run = state.run;
+	if (echo.target.tab !== gate.tab || echo.from.tab !== echo.target.tab || state.closed.has(echo.id) || !run?.waiting || run.envelope?.id !== echo.id) return;
+	settle(console, run, () => {
+		if (!run.waiting) return;
+		const local = run.envelope;
+		run.waiting = false;
+		if (echo.command === local.command && sameJson(echo.args, local.args) && sameJson(echo.target, local.target)) go(console, run);
+		else close$1(console, run, "id-conflict", /* @__PURE__ */ new Error(`The echo of operation ${local.id} differs from its record.`));
+	});
+};
+/**
+* Sends the run's envelope and waits for its echo (C-79): the timer and the
+* send are the gate's calls, made after the action's commit.
+*/
+var send = (console, run) => {
+	const { store, options } = liveRecord(console);
+	const gate = options.gate;
+	toRunning(console, run);
+	let envelope;
+	try {
+		const id = envelopeIds(options)();
+		if (typeof id !== "string" || id === "" || stateOf(console).closed.has(id)) throw new Error(`createEnvelopeId returned ${id}, an id already used.`);
+		const { view } = run.request;
+		envelope = {
+			v: 1,
+			id,
+			kind: "request",
+			actor: run.actor,
+			from: { tab: gate.tab },
+			target: view === void 0 ? { tab: gate.tab } : {
+				tab: gate.tab,
+				view
+			},
+			command: run.command.name,
+			args: run.request.input
+		};
+	} catch (error) {
+		fail(console, run, error);
+		return;
+	}
+	if (envelopeBytes(envelope) > envelopeMaxBytes) {
+		close$1(console, run, "too-large");
+		return;
+	}
+	run.envelope = envelope;
+	run.waiting = true;
+	const ended = (code) => () => settle(console, run, () => {
+		if (run.waiting) close$1(console, run, code);
+	});
+	store.afterCommit(() => {
+		const state = stateOf(console);
+		if (!run.waiting) return;
+		try {
+			if (state.unsubscribe === null) state.unsubscribe = gate.subscribe((raw) => receive(console, raw));
+			run.cancelTimer = gate.schedule(options.echoTimeoutMs ?? 5e3, ended("timeout"));
+			const copy = JSON.parse(JSON.stringify(envelope));
+			Promise.resolve(gate.send(copy)).then(void 0, ended("connection-lost"));
+		} catch {
+			ended("connection-lost")();
+		}
+	});
+};
+/** After `beforeRun` lets the run go: the gate, or the command at once. */
+var proceed = (console, run) => {
+	if (run.gated) send(console, run);
+	else go(console, run);
+};
+/**
+* Applies the plan of a command with `input` (C-77): normalizes and checks
+* the value, and completes the request from its canonical line. Throws on a
+* `normalize` or `activeView` that throws, or a value the schema refuses.
+*/
+var prepare = (run, plan) => {
+	const { command } = run;
+	const schema = command.input;
+	const view = plan.view();
+	const mapped = command.normalize ? command.normalize(plan.value) : plan.value;
+	const checked = validateInput(schema, mapped);
+	if (!checked.ok) throw new TypeError(`command ${command.name}: normalize returned an input the schema refuses.`);
+	const line = formatCommandLine(command.name, checked.value, schema);
+	const tokens = tokenize(line).tokens;
+	run.request = {
+		...run.request,
+		args: tokens.slice(1).map((token) => token.value),
+		rest: tokens.length > 1 ? line.slice(tokens[1].start) : "",
+		line,
+		input: checked.value
+	};
+	if (typeof view === "string" && view !== "") run.request.view = view;
+};
+var start = (console, command, request, inputId, sensitive, plan, onOutcome) => {
 	const { store, options } = liveRecord(console);
 	const provider = contextOf(console);
 	const frames = provider?.snapshot() ?? [];
@@ -839,9 +1107,16 @@ var start = (console, command, request, inputId, sensitive) => {
 		command,
 		controller: new AbortController(),
 		contextRevision: provider?.revision() ?? null,
+		gated: plan !== null && options.gate !== void 0 && !sensitive && describedCommand(command),
+		actor: plan?.actor ?? "user",
 		current: true,
 		cleaned: false,
-		resolve
+		envelope: null,
+		waiting: false,
+		cancelTimer: null,
+		outcome: failure("cancelled"),
+		resolve,
+		onOutcome
 	};
 	stateOf(console).run = run;
 	const { beforeRun } = options;
@@ -851,8 +1126,14 @@ var start = (console, command, request, inputId, sensitive) => {
 		inputId,
 		phase: beforeRun ? "authorizing" : "running"
 	}));
+	if (plan) try {
+		prepare(run, plan);
+	} catch (error) {
+		fail(console, run, error);
+		return done;
+	}
 	if (!beforeRun) {
-		go(console, run);
+		proceed(console, run);
 		return done;
 	}
 	let answer;
@@ -863,8 +1144,8 @@ var start = (console, command, request, inputId, sensitive) => {
 		return done;
 	}
 	whenSettled(console, run, answer, (value) => {
-		if (value === void 0) go(console, run);
-		else if (value === false) stop(console, run, false);
+		if (value === void 0) proceed(console, run);
+		else if (value === false) stop(console, run, false, "not-allowed");
 		else fulfil(console, run, value);
 	});
 	return done;
@@ -912,13 +1193,87 @@ var submitLine = (console) => {
 		addEntry(console, output("error", [message("command-not-found", { name: sensitive ? null : first.value })], inputId));
 		return Promise.resolve(true);
 	}
+	if (command.danger === "irreversible") {
+		addEntry(console, output("error", [message("operation-failed", { code: "not-allowed" })], inputId));
+		return Promise.resolve(true);
+	}
+	const args = parsed.tokens.slice(1).map((token) => token.value);
+	let plan = null;
+	if (command.input) {
+		const read = parseOptions(args, command.input);
+		if (!read.ok) {
+			const [error] = read.errors;
+			addEntry(console, output("error", [message("invalid-args", {
+				path: sensitive ? null : error.path,
+				reason: error.code
+			})], inputId));
+			return Promise.resolve(true);
+		}
+		plan = {
+			value: read.value,
+			view: () => liveRecord(console).options.activeView?.(),
+			actor: "user"
+		};
+	}
 	return start(console, command, {
 		name: first.value,
 		command: command.name,
-		args: parsed.tokens.slice(1).map((token) => token.value),
+		args,
 		rest: second ? trimmed.slice(second.start) : "",
 		line: trimmed
-	}, inputId, sensitive);
+	}, inputId, sensitive, plan);
+};
+/**
+* `request()` in the open action (C-82): every refusal before the line is
+* accepted leaves no entry.
+*/
+var requestLine = (console, input) => {
+	const refuse = (code) => Promise.resolve(failure(code));
+	const { store } = liveRecord(console);
+	if (store.read().running !== null) return refuse("busy");
+	const lookup = lookupOf(console);
+	let command;
+	let tokens = null;
+	let view;
+	if ("line" in input) {
+		const parsed = tokenize(String(input.line).trim());
+		if (!parsed.ok || parsed.tokens.length === 0) return refuse("invalid-args");
+		command = lookup.find(parsed.tokens[0].value);
+		tokens = parsed.tokens.slice(1).map((token) => token.value);
+		view = () => liveRecord(console).options.activeView?.();
+	} else {
+		command = typeof input.command === "string" ? lookup.find(input.command) : void 0;
+		const given = typeof input.view === "string" ? input.view : void 0;
+		view = () => given;
+	}
+	if (!command || command.hidden === true) return refuse("unknown-command");
+	if (!describedCommand(command) || command.danger !== "read" || input.actor !== "external-agent") return refuse("not-allowed");
+	const schema = command.input;
+	const read = tokens === null ? validateInput(schema, input.args) : parseOptions(tokens, schema);
+	if (!read.ok) return refuse("invalid-args");
+	const line = formatCommandLine(command.name, read.value, schema);
+	if (lookup.isSensitive(line)) return refuse("not-allowed");
+	const inputId = addEntry(console, {
+		kind: "input",
+		prompt: currentPrompt(console),
+		text: line,
+		redacted: false,
+		status: "submitted",
+		actor: input.actor
+	});
+	return new Promise((resolve) => {
+		start(console, command, {
+			name: command.name,
+			command: command.name,
+			args: [],
+			rest: "",
+			line
+		}, inputId, false, {
+			value: read.value,
+			view,
+			actor: input.actor
+		}, resolve);
+	});
 };
 /**
 * Ctrl+C without a run: the line ends as cancelled (README: Cancelling and
@@ -940,6 +1295,7 @@ var cancelLine = (console) => {
 /** Ctrl+C or `cancel()` during a run: invalidate, abort, `interrupted`. */
 var interrupt = (console, run) => {
 	run.current = false;
+	run.outcome = failure("cancelled");
 	run.controller.abort();
 	addEntry(console, output("notice", [message("interrupted")], run.inputId));
 	cleanup(console, run);
@@ -960,7 +1316,9 @@ var coreFeatures = [
 		constructConsoleAPIs(console) {
 			states.set(console, {
 				run: null,
-				lookup: null
+				lookup: null,
+				unsubscribe: null,
+				closed: /* @__PURE__ */ new Set()
 			});
 			const locked = (fn, otherwise) => {
 				const { store } = liveRecord(console);
@@ -975,11 +1333,20 @@ var coreFeatures = [
 				cancel() {
 					liveRecord(console).store.action(() => cancel(console));
 				},
+				request(input) {
+					try {
+						return liveRecord(console).store.action(() => requestLine(console, input));
+					} catch (error) {
+						reportCallbackError(console, error);
+						return Promise.resolve(failure("failed"));
+					}
+				},
 				isSensitive: (line) => lookupOf(console).isSensitive(line),
 				getCommands: () => lookupOf(console).visible().map(specOf)
 			}, {
 				submit: Promise.resolve(false),
 				run: Promise.resolve(false),
+				request: Promise.resolve(failure("cancelled")),
 				isSensitive: false,
 				getCommands: []
 			});
@@ -1002,17 +1369,21 @@ var coreFeatures = [
 			});
 			onContextChange(console, () => {
 				const run = stateOf(console).run;
-				if (run?.current && !run.controller.signal.aborted) run.controller.abort();
+				if (run?.current && run.waiting) interrupt(console, run);
+				else if (run?.current && !run.controller.signal.aborted) run.controller.abort();
 			});
 			onReset(console, () => {
 				const run = stateOf(console).run;
-				if (run) stop(console, run, true);
+				if (run) stop(console, run, true, "cancelled");
 			});
 			onDispose(console, () => {
 				const state = stateOf(console);
 				const run = state.run;
+				const unsubscribe = state.unsubscribe;
 				state.run = null;
-				if (run) stop(console, run, true);
+				state.unsubscribe = null;
+				if (run) stop(console, run, true, "cancelled");
+				unsubscribe?.();
 			});
 		}
 	}
@@ -1159,6 +1530,7 @@ function constructConsole(options, core) {
 	const defaults = Object.assign({}, ...features.map((feature) => feature.getDefaultOptions?.() ?? {}));
 	const merged = mergeOptions(defaults, options);
 	validateCommands(merged.commands);
+	checkGateOptions(merged);
 	let initial = emptyState();
 	for (const slice of controllable) {
 		const value = merged.initialState?.[slice];
@@ -1208,6 +1580,123 @@ function consoleFeatures(features) {
 function createConsole(options) {
 	return constructConsole(options, coreFeatures);
 }
+// src/helpers/agentTools.ts
+/**
+* A command an agent can see: one with `input` and `danger` whose definition
+* is not `sensitive` (what `request` could run, C-82).
+*/
+var described = (spec) => spec.input !== void 0 && spec.danger !== void 0 && (spec.sensitive === void 0 || spec.sensitive === false);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** `value` without its `undefined` fields, as JSON. */
+var json = (value) => JSON.parse(JSON.stringify(value));
+var error = (code) => ({
+	status: "error",
+	code
+});
+var failed = {
+	status: "error",
+	code: "failed"
+};
+/**
+* The `context`, `help` and `run` tools of `console` (C-83). `run` calls
+* `console.request` as `external-agent`, so only `read` commands run.
+*/
+function agentTools(console, options) {
+	const commands = () => console.getCommands().filter(described);
+	const help = (input) => {
+		const name = isRecord(input) ? input.command : void 0;
+		if (name === void 0) return commands().map((spec) => json({
+			name: spec.name,
+			summary: spec.summary,
+			danger: spec.danger
+		}));
+		const found = commands().find((spec) => spec.name === name || spec.aliases?.includes(name));
+		if (!found) return error("unknown-command");
+		return json({
+			name: found.name,
+			summary: found.summary,
+			usage: found.usage,
+			danger: found.danger,
+			input: found.input
+		});
+	};
+	return [
+		{
+			name: "context",
+			description: "The open tab, its views and the active view. Call it before run to pick a view; call help for the commands.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			},
+			annotations: {
+				readOnlyHint: true,
+				untrustedContentHint: true
+			},
+			execute: async () => {
+				try {
+					return await options.context();
+				} catch {
+					return failed;
+				}
+			}
+		},
+		{
+			name: "help",
+			description: "Without input: the commands you can run (name, summary, danger). With a command name: its usage and input schema. Call it before run.",
+			inputSchema: {
+				type: "object",
+				properties: { command: {
+					type: "string",
+					description: "A command name."
+				} }
+			},
+			annotations: { readOnlyHint: true },
+			execute: (input) => Promise.resolve(help(input))
+		},
+		{
+			name: "run",
+			description: "Runs a command: { line } as typed (name --field value), or { command, args, view? } with args matching its input schema. Returns { status, summary } or { status: \"error\", code }. Call help first.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					line: {
+						type: "string",
+						description: "A whole command line."
+					},
+					command: {
+						type: "string",
+						description: "A command name."
+					},
+					args: {
+						type: "object",
+						description: "The command input."
+					},
+					view: {
+						type: "string",
+						description: "A view id from context."
+					}
+				}
+			},
+			annotations: {
+				readOnlyHint: true,
+				untrustedContentHint: true
+			},
+			execute: async (input) => {
+				if (isRecord(input) && typeof input.line === "string") return console.request({
+					line: input.line,
+					actor: "external-agent"
+				});
+				if (isRecord(input) && typeof input.command === "string" && isRecord(input.args) && (input.view === void 0 || typeof input.view === "string")) return console.request({
+					command: input.command,
+					args: input.args,
+					...input.view === void 0 ? {} : { view: input.view },
+					actor: "external-agent"
+				});
+				return error("invalid-args");
+			}
+		}
+	];
+}
 // src/features/context/context.utils.ts
 /**
 * The id sequence of `frames`, as one comparable string. Two stacks with the
@@ -1727,6 +2216,6 @@ var completionFeature = {
 		onLineCleared(console, () => setSession(console, null));
 	}
 };
-export { completionFeature, consoleFeatures, contextFeature, createConsole, recallFeature };
+export { CommandError, agentTools, completionFeature, consoleFeatures, contextFeature, createConsole, recallFeature };
 
 //# sourceMappingURL=command-console-core.js.map