@stackstackstack/dsh-commands 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/interaction/commands/README.md
+README.md: a6c48c84a816fcd5ff8048b5d9634f93e29f8f76
+README.zh.md: df19b3728458543ecabfb2f398879ae14b741564

package/README.md

@@ -0,0 +1,40 @@
+# @stackstackstack/dsh-commands
+
+English | [中文](README.zh.md)
+
+Plugin-owned human-command registry consumed by interactive UI adapters. The [plugin command registration Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md) owns the boundary and dispatch contract.
+
+## Service contract
+
+`ctx.commands.register(definition)` registers one lowercase command name, description, optional unstructured-input hint, optional `recordInput` policy, and abortable handler. `recordInput` defaults to true; a command whose authoritative domain event owns the payload sets it to false so `command/run` omits `args` instead of duplicating the input. A registered command is available to every composed command adapter; a plugin that is incompatible with a deployment does not register there. A plain-context registration is global. A command-producing plugin mounted beneath `agent.ctx` declares its own `commands` injection and creates an exact agent-scoped definition; it shadows a global definition with the same name. This child-injection shape preserves the agent scope without making the core agent loop depend on a UI service. Duplicate names within one layer fail during registration. Every disposer is the exact Cordis effect disposer, and registration or removal notifies every `commands/change` observer so live adapters can refresh discovery; observer failures are logged and cannot veto the registry mutation or starve later observers.
+
+`list(agent)` returns immutable, name-sorted descriptors after scoped shadowing. `find(agent, name)` returns the corresponding definition. `execute(agent, line, signal)` uses `parseCommand()` and runs only a known command, returning the settled `CommandExecution` (the normalized result plus the lifecycle pairing `commandId`) or `undefined` for invalid syntax or unknown names. A resolved command's lifecycle is logged on the receiving agent's session as the log-only pair `command/run` (before the handler, with a minted `commandId`, the parser's structured name, the issuing `CommandSource`, and `args` unless `recordInput` is false) and `command/done` (at settlement, with the outcome kind and verbatim text; a successful result may also name an earlier non-command authoritative domain event through `sourceEventSeq`; a thrown or aborted handler settles as `kind: 'error'`). Admission misses log nothing. Both are direct standalone appends on the receiving agent's session: no turn wraps them, and persistence drains them through ordinary checkpoints and teardown.
+
+`parseCommand()` recognizes a slash at byte zero, a lowercase name containing letters, digits, `_`, or `-`, and either end-of-input or whitespace. It returns every byte after the name as `rawInput`, including separator whitespace; consumers own their command-specific grammar and may normalize only what that grammar permits.
+
+Handlers return `success` or `error` plus optional UI text. A successful handler may also return `sourceEventSeq` when an earlier domain event owns a richer presentation; the lifecycle invariant requires that reference to be a prior non-command event in the same session. Results are rendered directly by the adapter and never enter model history. The registry never submits `rawInput` to the agent implicitly; a command producer may explicitly schedule model-visible work through the receiving `Agent`, in which case that producer owns the resulting message contract. The registry races handler completion against the supplied abort signal, but an uncooperative handler may continue its own external side effects after the caller stops awaiting it.
+
+## Composition
+
+The shipped `dsh` base mounts this service and the Web client dispatches through it. UI-less demo spines and ACP automation do not provide a command adapter. Custom interactive compositions and command producers mount `@stackstackstack/dsh-commands` explicitly.
+
+## Model Experience
+
+### Direct human commands
+
+#### What the model sees
+
+The registry itself submits nothing. Known slash commands execute in the UI command plane, and their `CommandResult` text is not submitted as a user message. Unknown slash-command input is rejected by shipped adapters instead of becoming a model prompt. A command producer may explicitly use the receiving `Agent`; for example, [`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-interactions) submits the optional message in `/plan [message]` after selecting plan mode.
+
+#### Token effect
+
+Command discovery, execution, and UI output add no model tokens. Explicit agent work scheduled by a command producer has the same token effect as the corresponding agent input.
+
+#### KV Cache effect
+
+Registry metadata, command input, and direct output never enter a model request and do not affect its cache. A mutated domain owns any later cache effect.
+
+## Known Limitations and Deferred Work
+
+- **Only unstructured text input** — forms, completion schemas, and typed arguments remain command-owned parsing concerns.
+- **Cooperative side-effect cancellation** — dispatch stops awaiting on abort; handlers must honor the signal to stop work that has already escaped into external systems.

package/README.zh.md

@@ -0,0 +1,40 @@
+# @stackstackstack/dsh-commands
+
+[English](README.md) | 中文
+
+由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发约定。
+
+## 服务约定
+
+`ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示、可选的 `recordInput` 策略，以及可中止的处理器。`recordInput` 默认为 true；若载荷由命令的权威领域事件持有，该命令会将 `recordInput` 设为 false，让 `command/run` 省略 `args`，避免重复记录输入。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent（智能体）的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop（智能体循环）依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使运行中的适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
+
+`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带新生成的 `commandId`、解析器的结构化名称、发起方 `CommandSource`，以及 `args`（`recordInput` 为 false 时省略））与 `command/done`（结算时记录，携带结果类型与原样文本；成功结果还可通过 `sourceEventSeq` 指向更早的一条非命令权威领域事件；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都直接独立追加到接收 agent 的会话中：没有轮次包裹它们，持久化机制会在常规检查点和销毁期间排空这些事件。
+
+`parseCommand()` 识别位于第 0 字节的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方负责各命令专用的语法，只能执行该语法允许的规范化。
+
+处理器返回 `success` 或 `error`，并可附带 UI 文本。若更丰富的呈现由一条更早的领域事件持有，成功的处理器还可返回 `sourceEventSeq`；生命周期不变量要求该引用指向同一会话中更早的一条非命令事件。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息约定。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。
+
+## 组合
+
+随产品交付的 `dsh` 基础组合会挂载此服务，Web 客户端通过它分派命令。无 UI 的演示主干和 ACP（Agent Client Protocol）自动化不提供命令适配器。自定义交互式组合与命令生产方会显式挂载 `@stackstackstack/dsh-commands`。
+
+## 模型体验
+
+### 直接面向用户的命令
+
+#### 模型看到的内容
+
+注册表自身不会提交任何内容。已知斜杠命令在 UI 命令平面执行，其 `CommandResult` 文本不会作为用户消息提交。已交付的适配器会拒绝未知斜杠命令输入，而不是将其变成模型提示词。命令生产方可以显式使用接收命令的 `Agent`；例如，[`dsh-plan-mode`](../../plan/plan-mode/README.md#model-and-human-interactions)在选择 plan mode 后，会提交 `/plan [message]` 中的可选消息。
+
+#### Token 影响
+
+命令发现、执行和 UI 输出不会增加模型 token。命令生产方显式安排的 agent 工作与相应 agent 输入具有相同的 token 影响。
+
+#### KV Cache 影响
+
+注册表元数据、命令输入和直接输出绝不会进入模型请求，也不会影响其缓存。发生变更的领域负责之后产生的所有缓存影响。
+
+## 已知限制与暂缓事项
+
+- **仅支持非结构化文本输入**：表单、补全 schema 和类型化参数仍由各命令自行解析。
+- **副作用采用协作式取消**：中止后，分发会停止等待；处理器必须遵循信号，才能停止已经进入外部系统的工作。

package/lib/index.js

@@ -0,0 +1,360 @@
+import { NamedEntries, ScopedLayers } from "@stackstackstack/dsh-scope";
+import { Remote, TypertRemoteService } from "@stackstackstack/dsh-typert-protocol";
+//#region lib/types/brand.js
+/**
+* dsh-commands' owned branded id: command lifecycle pairing across the
+* session log, the wire admission response, and client-side flow pairing.
+*
+* The `Branded<B>` primitive lives in `@stackstackstack/dsh-brand`; this module
+* is a pure type/constructor outlet (no cordis imports, no module
+* augmentation) so wire and client programs can name the brand without
+* loading the host plugin's Context merges — the `dsh-llm/brand` shape.
+*
+* @module @stackstackstack/dsh-commands/brand
+*/
+/**
+* Brand a string as a {@link CommandId}.
+* @param id - the executor-minted pairing id.
+* @returns the same string, branded; no validation is performed.
+*/
+function CommandId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Plugin-owned human-command registry shared by interactive UI adapters.
+* @module @stackstackstack/dsh-commands
+*/
+var __runInitializers = function(thisArg, initializers, value) {
+	var useValue = arguments.length > 2;
+	for (var i = 0; i < initializers.length; i++) value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+	return useValue ? value : void 0;
+};
+var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+	function accept(f) {
+		if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected");
+		return f;
+	}
+	var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+	var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+	var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+	var _, done = false;
+	for (var i = decorators.length - 1; i >= 0; i--) {
+		var context = {};
+		for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+		for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+		context.addInitializer = function(f) {
+			if (done) throw new TypeError("Cannot add initializers after decoration has completed");
+			extraInitializers.push(accept(f || null));
+		};
+		var result = (0, decorators[i])(kind === "accessor" ? {
+			get: descriptor.get,
+			set: descriptor.set
+		} : descriptor[key], context);
+		if (kind === "accessor") {
+			if (result === void 0) continue;
+			if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+			if (_ = accept(result.get)) descriptor.get = _;
+			if (_ = accept(result.set)) descriptor.set = _;
+			if (_ = accept(result.init)) initializers.unshift(_);
+		} else if (_ = accept(result)) if (kind === "field") initializers.unshift(_);
+		else descriptor[key] = _;
+	}
+	if (target) Object.defineProperty(target, contextIn.name, descriptor);
+	done = true;
+};
+const name = "commands";
+const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/u;
+/** All command registrations owned by one global or scoped layer. */
+var CommandLayer = class {
+	commands;
+	/**
+	* Create one command layer with diagnostics specific to its ownership scope.
+	* @param scope - the scoped owner, or `undefined` for global registrations.
+	*/
+	constructor(scope) {
+		this.commands = new NamedEntries((name) => /* @__PURE__ */ new Error(scope === void 0 ? `command "${name}" is already registered (for a per-agent variant, mount a command-injected plugin under that agent's \`agent.ctx\`)` : `command "${name}" is already registered in this scope`));
+	}
+	/** @returns whether this layer owns no command registrations. */
+	isEmpty() {
+		return this.commands.isEmpty();
+	}
+};
+/**
+* Parse an exact slash command without normalizing its trailing input.
+*
+* @param line - Complete candidate command line.
+* @returns The parsed command, or `undefined` when the line is not a command.
+*/
+function parseCommand(line) {
+	const match = /^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u.exec(line);
+	if (match === null) return void 0;
+	const name = match[1];
+	/* v8 ignore next -- the first capture is required whenever the regular expression matches */
+	if (name === void 0) return void 0;
+	return Object.freeze({
+		name,
+		rawInput: line.slice(match[0].length)
+	});
+}
+/** Convert arbitrary abort reasons to one stable rejected Error. */
+function abortError(signal) {
+	if (signal.reason instanceof Error) return signal.reason;
+	return new Error(typeof signal.reason === "string" ? signal.reason : "command aborted");
+}
+/** Render arbitrary thrown values without trusting their string coercion. */
+function renderThrown(value) {
+	try {
+		return String(value);
+	} catch {
+		return "<unrenderable thrown value>";
+	}
+}
+/** Stop awaiting an uncooperative handler once its owning UI request aborts. */
+function withAbort(promise, signal) {
+	if (signal.aborted) return Promise.reject(abortError(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			reject(abortError(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error instanceof Error ? error : new Error(`command handler rejected with a non-Error value: ${renderThrown(error)}`, { cause: error }));
+		});
+	});
+}
+/** Reject invalid command metadata before it can reach a UI protocol. */
+function normalizeDefinition(definition) {
+	if (!COMMAND_NAME.test(definition.name)) throw new TypeError(`command name "${definition.name}" must match ${String(COMMAND_NAME)}`);
+	if (typeof definition.description !== "string") throw new TypeError(`command "${definition.name}" description must be a string`);
+	if (definition.description.trim().length === 0) throw new TypeError(`command "${definition.name}" description must not be empty`);
+	if (typeof definition.handler !== "function") throw new TypeError(`command "${definition.name}" handler must be a function`);
+	const rawInput = definition.input;
+	let input;
+	if (rawInput !== void 0) {
+		if (typeof rawInput !== "object" || rawInput === null || !("hint" in rawInput) || typeof rawInput.hint !== "string") throw new TypeError(`command "${definition.name}" input hint must be a string`);
+		if (rawInput.hint.trim().length === 0) throw new TypeError(`command "${definition.name}" input hint must not be empty`);
+		input = Object.freeze({ hint: rawInput.hint });
+	}
+	const normalized = Object.freeze({
+		name: definition.name,
+		description: definition.description,
+		...input === void 0 ? {} : { input },
+		...definition.recordInput === void 0 ? {} : { recordInput: definition.recordInput },
+		handler: definition.handler
+	});
+	return {
+		definition: normalized,
+		descriptor: Object.freeze({
+			name: normalized.name,
+			description: normalized.description,
+			...normalized.input === void 0 ? {} : { input: normalized.input }
+		})
+	};
+}
+/** Validate and detach an untrusted handler result at the registry boundary. */
+function normalizeResult(command, value) {
+	if (typeof value !== "object" || value === null || !("kind" in value)) throw new TypeError(`command "${command}" handler must return a CommandResult`);
+	const result = value;
+	if (result.kind === "success") {
+		if (result.text !== void 0 && typeof result.text !== "string") throw new TypeError(`command "${command}" success text must be a string when supplied`);
+		if (result.sourceEventSeq !== void 0 && (!Number.isSafeInteger(result.sourceEventSeq) || result.sourceEventSeq < 0)) throw new TypeError(`command "${command}" success sourceEventSeq must be a non-negative safe integer when supplied`);
+		return Object.freeze({
+			kind: "success",
+			...result.text === void 0 ? {} : { text: result.text },
+			...result.sourceEventSeq === void 0 ? {} : { sourceEventSeq: result.sourceEventSeq }
+		});
+	}
+	if (result.kind === "error") {
+		if (typeof result.text !== "string" || result.text.trim().length === 0) throw new TypeError(`command "${command}" error text must be a non-empty string`);
+		return Object.freeze({
+			kind: "error",
+			text: result.text
+		});
+	}
+	throw new TypeError(`command "${command}" returned unknown result kind "${String(result.kind)}"`);
+}
+/**
+* Human-command registry. Plain-context definitions are global; definitions
+* registered through a command-injected child of an agent context shadow
+* globals for that agent.
+*/
+let CommandRuntime = (() => {
+	let _classSuper = TypertRemoteService;
+	let _instanceExtraInitializers = [];
+	let _list_decorators;
+	let _execute_decorators;
+	return class CommandRuntime extends _classSuper {
+		static {
+			const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+			_list_decorators = [Remote];
+			_execute_decorators = [Remote];
+			__esDecorate(this, null, _list_decorators, {
+				kind: "method",
+				name: "list",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "list" in obj,
+					get: (obj) => obj.list
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _execute_decorators, {
+				kind: "method",
+				name: "execute",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "execute" in obj,
+					get: (obj) => obj.execute
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			if (_metadata) Object.defineProperty(this, Symbol.metadata, {
+				enumerable: true,
+				configurable: true,
+				writable: true,
+				value: _metadata
+			});
+		}
+		layers = (__runInitializers(this, _instanceExtraInitializers), new ScopedLayers((scope) => new CommandLayer(scope), () => {
+			this.notifyChange();
+		}));
+		/** Monotonic per-instance counter behind {@link mintCommandId}. */
+		commandSeq = 0;
+		/** Instance token keeping minted ids unique across process restarts over one resumed log. */
+		instanceToken = crypto.randomUUID().slice(0, 8);
+		constructor(ctx) {
+			super(ctx, "commands");
+		}
+		/**
+		* Register a global or calling-agent-scoped command.
+		* @param definition - discovery metadata and direct UI handler.
+		* @returns the exact effect disposer that unregisters this definition.
+		*/
+		register(definition) {
+			const registered = normalizeDefinition(definition);
+			return this.layers.effect(this.ctx, (layer) => layer.commands.insert(registered.definition.name, registered), { label: "commands.register()" });
+		}
+		/**
+		* List the effective immutable command descriptors for one agent.
+		* @param agent - exact receiving agent and scoped-layer key.
+		* @returns name-sorted descriptors after scoped shadowing.
+		*/
+		list(agent) {
+			return Object.freeze([...this.view(agent).values()].map((command) => command.descriptor).sort((left, right) => left.name < right.name ? -1 : 1));
+		}
+		/**
+		* Resolve one effective command definition.
+		* @param agent - exact receiving agent and scoped-layer key.
+		* @param name - command name without a slash.
+		* @returns the scoped shadow or global definition.
+		*/
+		find(agent, name) {
+			return this.view(agent).get(name)?.definition;
+		}
+		/**
+		* Parse and execute a known command without sending it to the model.
+		*
+		* A resolved command's lifecycle is logged: `command/run` is appended
+		* before the handler is invoked and `command/done` after settlement (a
+		* thrown or aborted handler settles as `kind: 'error'`). Both are direct
+		* log-only appends — no turn wraps them, and persistence drains them at
+		* ordinary checkpoints. Admission misses (syntax or unknown name) log
+		* nothing — they never entered a handler. A `command/run` append failure
+		* fails the execution loud; a `command/done` append failure on the
+		* handler-failure path is contained so the handler's own error stays the
+		* reported failure.
+		*
+		* @param agent - exact receiving agent.
+		* @param line - complete slash-command line.
+		* @param signal - cancellation signal owned by the UI request.
+		* @returns the settled execution (result + lifecycle pairing id), or
+		*   `undefined` when syntax or name does not resolve.
+		*/
+		async execute(agent, line, signal) {
+			const parsed = parseCommand(line);
+			if (parsed === void 0) return void 0;
+			const command = this.view(agent).get(parsed.name);
+			if (command === void 0) return void 0;
+			if (signal.aborted) throw abortError(signal);
+			const commandId = this.mintCommandId();
+			this.appendLifecycle(agent.session, "command/run", {
+				commandId,
+				name: parsed.name,
+				...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
+				source: { kind: "user" }
+			});
+			const invocation = Object.freeze({
+				commandId,
+				agent,
+				rawInput: parsed.rawInput,
+				signal
+			});
+			let result;
+			try {
+				const output = command.definition.handler(invocation);
+				result = normalizeResult(parsed.name, await withAbort(Promise.resolve(output), signal));
+			} catch (error) {
+				try {
+					this.appendLifecycle(agent.session, "command/done", {
+						commandId,
+						kind: "error",
+						text: error instanceof Error ? error.message : renderThrown(error)
+					});
+				} catch (appendError) {
+					this.ctx.logger.warn(`command "${parsed.name}": command/done append failed: ${renderThrown(appendError)}`);
+				}
+				throw error;
+			}
+			this.appendLifecycle(agent.session, "command/done", {
+				commandId,
+				kind: result.kind,
+				...result.text === void 0 ? {} : { text: result.text },
+				...result.kind === "success" && result.sourceEventSeq !== void 0 ? { sourceEventSeq: result.sourceEventSeq } : {}
+			});
+			return Object.freeze({
+				commandId,
+				result
+			});
+		}
+		/** Mint the next pairing id (monotonic; instance-token-prefixed so a resumed log never repeats one). */
+		mintCommandId() {
+			this.commandSeq += 1;
+			return CommandId(`cmd-${this.instanceToken}-${this.commandSeq}`);
+		}
+		/**
+		* Append one log-only lifecycle event directly: no turn is opened for it and
+		* no flush is forced — persistence observes the eager `session/event` path
+		* and drains at ordinary checkpoints and teardown, like every other
+		* standalone plugin event.
+		*/
+		appendLifecycle(session, type, data) {
+			return session.append.bind(session)(type, data);
+		}
+		/** Resolve global definitions followed by exact scoped shadows. */
+		view(agent) {
+			return this.layers.merge(agent, (layer) => layer.commands);
+		}
+		/** Notify every registry observer without making UI refresh load-bearing. */
+		notifyChange() {
+			for (const callback of this.ctx.events.dispatch("emit", ["commands/change"])) try {
+				const returned = callback();
+				Promise.resolve(returned).catch((error) => {
+					this.ctx.logger.warn(`commands/change listener rejected: ${renderThrown(error)}`);
+				});
+			} catch (error) {
+				this.ctx.logger.warn(`commands/change listener threw: ${renderThrown(error)}`);
+			}
+		}
+	};
+})();
+//#endregion
+export { CommandId, CommandRuntime, CommandRuntime as default, name, parseCommand };

package/lib/invariant.js

@@ -0,0 +1,43 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-commands`:
+* command lifecycle events pair by commandId within one session log.
+* @module @stackstackstack/dsh-commands/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-commands";
+/** Cordis companion plugin name. */
+const name = "commands-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Install pairing validation over loaded logs and newly appended lifecycle events. */
+const install = Object.assign((ctx, fail) => {
+	const runIds = /* @__PURE__ */ new WeakMap();
+	const validateEvent = (session, event) => {
+		if (event.type === "command/run") {
+			const ids = runIds.get(session) ?? /* @__PURE__ */ new Set();
+			if (ids.has(event.data.commandId)) fail(`command/run repeats commandId ${JSON.stringify(event.data.commandId)}`);
+			ids.add(event.data.commandId);
+			runIds.set(session, ids);
+			return;
+		}
+		if (event.type !== "command/done") return;
+		if (runIds.get(session)?.has(event.data.commandId) !== true) fail(`command/done ${JSON.stringify(event.data.commandId)} pairs no prior command/run in this log`);
+		const source = event.data.sourceEventSeq;
+		const sourceEvent = source === void 0 ? void 0 : session.events[source];
+		if (source !== void 0 && (event.data.kind !== "success" || !Number.isSafeInteger(source) || source < 0 || source >= event.seq || sourceEvent?.seq !== source || sourceEvent.type === "command/run" || sourceEvent.type === "command/done")) fail(`command/done ${JSON.stringify(event.data.commandId)} has invalid sourceEventSeq ${String(source)}`);
+	};
+	for (const session of ctx.sessions.list()) for (const event of session.events) validateEvent(session, event);
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		validateEvent(session, event);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @stackstackstack/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown