dsh-code 0.1.0 → 0.2.0

package/lib/index.mjs

@@ -1,12 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { createElement, useState, useSyncExternalStore } from "react";
+import { createElement, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import z from "@deepseek-ai/schemastery";
 import { installModelSelection } from "@deepseek-ai/dsh-agent";
 import { assertNever, boundContextSummary, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import { Box, Text, render, useInput } from "ink";
 import chalk from "chalk";
+import { isUserInvocable } from "@deepseek-ai/dsh-skill";
 //#region src/theme.ts
 /**
 * Terminal color tokens for the dsh TUI, mapped from the product design
@@ -76,6 +78,10 @@ function dim(text) {
 function error(text) {
 	return chalk.rgb(...TUI_RGB.error)(text);
 }
+/** Paint warnings. */
+function warn(text) {
+	return chalk.rgb(...TUI_RGB.warn)(text);
+}
 //#endregion
 //#region src/whale-glyph.ts
 /** Half-block whale glyph rows; render with the brand color. */
@@ -152,19 +158,45 @@ function buildStatusGroups(facts, stats) {
 	return groups;
 }
 //#endregion
+//#region src/render/text.ts
+/**
+* Display-boundary sanitization for externally sourced text (model output,
+* tool payloads, skill descriptions). Control characters — including ANSI
+* CSI/OSC escape sequences — would otherwise pass through Ink into the
+* terminal, letting output rewrite the screen or inject prompts. Newlines
+* and tabs survive; everything else in C0/C1 plus DEL becomes a visible
+* `\xNN` escape.
+*
+* @module @deepseek-ai/dsh-code/render/text
+*/
+/** C0 controls except tab (0x09) and newline (0x0a), plus DEL and C1. */
+const CONTROL_ESCAPE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu;
+/**
+* Escape control characters so externally sourced text cannot drive the
+* terminal.
+* @param text - raw text from a session event, tool payload, or catalog.
+* @returns text with every control character (except `\n`, `\t`) rendered
+* as a literal `\xNN` escape.
+*/
+function displayText(text) {
+	return text.replace(CONTROL_ESCAPE, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+//#endregion
 //#region src/app.ts
 /**
 * The Ink terminal app: whale-and-wordmark header in DeepSeek blue, the live
-* transcript, the streaming line, local notices, and the input box. All state
-* arrives through the transcript store (derived from the durable session log)
-* plus local input state; the app owns no session mutation of its own.
+* transcript, the todo panel, the streaming line, the approval bar, the model
+* panel, local notices, and the input box with history and slash-command
+* completion. All state arrives through the transcript store (derived from
+* the durable session log) plus local input state; the app owns no session
+* mutation of its own.
 *
 * Element construction uses `createElement` (not JSX): the `dsh` source launch
 * compiles this file through tsx's ESM-only hook, which does not adopt this
 * package's `jsx: react-jsx` compiler option, and the classic JSX runtime
 * would demand a React global.
 *
-* @module @deepseek-ai/dsh-tui/app
+* @module @deepseek-ai/dsh-code/app
 */
 /** Ink `color` string for one palette triple. */
 function inkColor(triple) {
@@ -173,18 +205,22 @@ function inkColor(triple) {
 /** One settled transcript row. */
 function EntryLine({ entry }) {
 	switch (entry.kind) {
-		case "user": return createElement(Text, null, brand("❯ "), entry.text);
-		case "assistant": return createElement(Text, null, entry.text);
+		case "user": return createElement(Text, null, brand("❯ "), displayText(entry.text));
+		case "assistant": return createElement(Text, null, displayText(entry.text));
 		case "tool": {
 			const mark = entry.state === "running" ? createElement(Text, { color: inkColor(TUI_RGB.brandBright) }, "◐") : entry.state === "error" ? createElement(Text, { color: inkColor(TUI_RGB.error) }, "⨯") : createElement(Text, { color: inkColor(TUI_RGB.success) }, "⏺");
-			return createElement(Text, null, mark, " ", brand(entry.name), entry.summary === "" ? "" : ` ${dim(entry.summary)}`);
+			return createElement(Text, null, mark, " ", brand(entry.name), entry.summary === "" ? "" : ` ${dim(displayText(entry.summary))}`);
 		}
-		case "error": return createElement(Text, null, error(entry.text));
+		case "command": {
+			const mark = entry.state === "running" ? createElement(Text, { color: inkColor(TUI_RGB.brandBright) }, "◐") : entry.state === "error" ? createElement(Text, { color: inkColor(TUI_RGB.error) }, "⨯") : createElement(Text, { color: inkColor(TUI_RGB.success) }, "⏺");
+			return createElement(Text, null, mark, " ", brand(`/${entry.name}`), entry.args === "" ? "" : ` ${dim(displayText(entry.args))}`, entry.summary === "" ? "" : ` ${dim(displayText(entry.summary))}`);
+		}
+		case "error": return createElement(Text, null, error(displayText(entry.text)));
 		default: return assertNever(entry, "transcript entry kind");
 	}
 }
 /** The whale wordmark header in DeepSeek blue, hugging its content width. */
-function Header() {
+function Header({ resumed }) {
 	return createElement(Box, {
 		flexDirection: "row",
 		gap: 1,
@@ -204,7 +240,32 @@ function Header() {
 	}, createElement(Text, {
 		color: inkColor(TUI_RGB.brand),
 		bold: true
-	}, "DeepSeek Harness"), createElement(Text, { dimColor: true }, "/help commands · Ctrl+C quit")));
+	}, "DeepSeek Harness"), createElement(Text, { dimColor: true }, resumed ? "resumed session · /help commands · Esc interrupt" : "/help commands · Esc interrupt · Ctrl+C quit")));
+}
+/** Todo status glyph: web TodoPanel's three-state marker. */
+function todoMark(status) {
+	return status === "completed" ? "✓" : status === "in_progress" ? "●" : "○";
+}
+/** Inline todo list (web TodoPanel's compact terminal form). */
+function TodoPanel({ todos }) {
+	if (todos.length === 0) return void 0;
+	const completed = todos.filter((todo) => todo.status === "completed").length;
+	const inProgress = todos.filter((todo) => todo.status === "in_progress").length;
+	const pending = todos.length - completed - inProgress;
+	return createElement(Box, {
+		flexDirection: "column",
+		paddingX: 1,
+		borderStyle: "round",
+		borderColor: inkColor(TUI_RGB.brandDeep),
+		alignSelf: "flex-start",
+		marginLeft: 1
+	}, createElement(Text, {
+		color: inkColor(TUI_RGB.brand),
+		bold: true
+	}, `todos ${completed}/${todos.length}`, createElement(Text, { dimColor: true }, ` · ${inProgress} active · ${pending} pending`)), ...todos.map((todo, index) => createElement(Text, {
+		key: index,
+		color: todo.status === "completed" ? inkColor(TUI_RGB.success) : todo.status === "in_progress" ? inkColor(TUI_RGB.brandBright) : inkColor(TUI_RGB.dim)
+	}, `${todoMark(todo.status)} ${displayText(todo.content)}`)));
 }
 /**
 * The footer status line: Claude-Code-style identity facts (model, working
@@ -221,75 +282,468 @@ function StatusLine({ facts, stats, busy }) {
 	});
 	return createElement(Box, { paddingX: 1 }, ...children);
 }
-/** The prompt box: slash commands handled locally, other text submitted. */
-function Input({ busy, onSubmit, onQuit }) {
+/** The y/n approval bar rendered while an approval ask is pending. */
+function ApprovalBar({ approval }) {
+	const snapshot = useSyncExternalStore(approval.subscribe, approval.getSnapshot);
+	if (snapshot.pending === void 0) return void 0;
+	const { pending, answered } = snapshot;
+	return createElement(Box, {
+		flexDirection: "column",
+		paddingX: 1,
+		borderStyle: "round",
+		borderColor: inkColor(TUI_RGB.warn),
+		alignSelf: "flex-start",
+		marginLeft: 1
+	}, createElement(Text, {
+		color: inkColor(TUI_RGB.warn),
+		bold: true
+	}, "⏸ waiting for approval"), createElement(Text, null, warn(displayText(pending.headline))), pending.command === "" ? void 0 : createElement(Text, { dimColor: true }, dim(`  ${displayText(pending.command)}`)), answered ? createElement(Text, { dimColor: true }, "  submitted…") : createElement(Text, { dimColor: true }, dim("  y allow once · n reject")));
+}
+/** The /model panel: a scrolling list over the advisory model directory. */
+function ModelPanel({ directory, error, onSelect, onClose }) {
+	const [cursor, setCursor] = useState(0);
+	useInput((input, key) => {
+		if (key.escape || input === "q") {
+			onClose();
+			return;
+		}
+		const rows = directory?.rows ?? [];
+		if (key.upArrow) {
+			setCursor(cursor > 0 ? cursor - 1 : rows.length - 1);
+			return;
+		}
+		if (key.downArrow) {
+			setCursor(cursor < rows.length - 1 ? cursor + 1 : 0);
+			return;
+		}
+		if (key.return && rows[cursor] !== void 0) onSelect(rows[cursor]);
+	});
+	const rows = directory?.rows ?? [];
+	const window = 8;
+	const first = Math.max(0, Math.min(cursor - Math.floor(window / 2), rows.length - window));
+	const visible = rows.slice(Math.max(0, first), Math.max(0, first) + window);
+	return createElement(Box, {
+		flexDirection: "column",
+		paddingX: 1,
+		borderStyle: "round",
+		borderColor: inkColor(TUI_RGB.brand),
+		alignSelf: "flex-start",
+		marginLeft: 1
+	}, createElement(Text, {
+		color: inkColor(TUI_RGB.brand),
+		bold: true
+	}, "/model — select the model for the next step"), directory === void 0 && error === void 0 ? createElement(Text, { dimColor: true }, "  loading models…") : void 0, error !== void 0 ? createElement(Text, { color: inkColor(TUI_RGB.error) }, `  ${error}`) : void 0, ...visible.map((row) => {
+		const index = rows.indexOf(row);
+		const label = displayText(`${row.providerName} · ${row.modelName}`);
+		return createElement(Text, {
+			key: `${row.provider}/${row.model}`,
+			color: index === cursor ? inkColor(TUI_RGB.brandBright) : inkColor(TUI_RGB.dim)
+		}, `${index === cursor ? "❯ " : "  "}${label}`);
+	}), createElement(Text, { dimColor: true }, dim("  ↑↓ move · enter select · esc close")));
+}
+/**
+* Resolve completion candidates for the current input: TUI-local commands,
+* the live registry descriptors, and user-invocable skills, filtered by the
+* typed prefix. Command names win collisions (the dispatch tries the
+* registry first and only then falls through to the skill gesture).
+*/
+function completionCandidates(value, descriptors, skills) {
+	if (!value.startsWith("/")) return [];
+	const prefix = value.slice(1).split(" ")[0] ?? "";
+	const local = [
+		{
+			label: "/help",
+			description: "show commands",
+			origin: "command"
+		},
+		{
+			label: "/model",
+			description: "switch the model",
+			origin: "command"
+		},
+		{
+			label: "/clear",
+			description: "clear the screen",
+			origin: "command"
+		},
+		{
+			label: "/quit",
+			description: "exit",
+			origin: "command"
+		}
+	];
+	const registry = descriptors.map((descriptor) => ({
+		label: `/${descriptor.name}`,
+		description: descriptor.description,
+		origin: "command"
+	}));
+	const taken = new Set([...local, ...registry].map((candidate) => candidate.label.slice(1)));
+	const skillRows = skills.filter((skill) => !taken.has(skill.name)).map((skill) => ({
+		label: `/${skill.name}`,
+		description: skill.modelInvocable ? `skill · ${skill.description}` : `skill (user only) · ${skill.description}`,
+		origin: "skill"
+	}));
+	const all = [
+		...local,
+		...registry,
+		...skillRows
+	];
+	if (prefix === "") return all.slice(0, 10);
+	return all.filter((candidate) => candidate.label.slice(1).startsWith(prefix)).slice(0, 10);
+}
+/**
+* The prompt box: TUI-local slash commands handled locally, other lines
+* dispatched; input editing keeps a cursor with history and completion.
+*/
+function Input({ busy, descriptors, skills, dispatch, steer, interrupt, quit, openModel, notify }) {
 	const [value, setValue] = useState("");
-	const [notices, setNotices] = useState([]);
+	const [cursor, setCursor] = useState(0);
+	const history = useRef([]);
+	const historyIndex = useRef(null);
+	const draft = useRef("");
+	const [completionIndex, setCompletionIndex] = useState(0);
+	const candidates = completionCandidates(value, descriptors, skills);
+	const completionActive = candidates.length > 0 && value.startsWith("/") && !value.includes(" ") && !value.includes("\n");
 	useInput((input, key) => {
-		if (key.ctrl && (input === "c" || input === "d")) {
-			onQuit();
+		if (key.ctrl && input === "c") {
+			if (busy) interrupt();
+			else if (value !== "") {
+				setValue("");
+				setCursor(0);
+				setCompletionIndex(0);
+			} else quit();
+			return;
+		}
+		if (key.ctrl && input === "d") {
+			if (busy) notify("cancel the running turn before exiting (Esc or Ctrl+C)");
+			else quit();
+			return;
+		}
+		if (key.escape) {
+			if (busy) interrupt();
 			return;
 		}
 		if (key.return) {
+			if (key.meta || key.ctrl && input === "j") {
+				setValue(value.slice(0, cursor) + "\n" + value.slice(cursor));
+				setCursor(cursor + 1);
+				return;
+			}
 			const text = value.trim();
 			setValue("");
+			setCursor(0);
+			setCompletionIndex(0);
 			if (text === "") return;
+			history.current = [...history.current, text];
+			historyIndex.current = null;
 			if (text === "/quit") {
-				onQuit();
+				quit();
 				return;
 			}
 			if (text === "/help") {
-				setNotices([...notices, "/help show commands · /clear clear the screen · /quit exit"]);
+				notify("/model switch · /clear clear the screen · /quit exit · other /commands reach the registry · Esc or Ctrl+C interrupts the running turn");
 				return;
 			}
 			if (text === "/clear") {
-				setNotices([]);
 				console.clear();
 				return;
 			}
-			if (busy) {
-				setNotices([...notices, "the agent is working — wait for the turn to finish"]);
+			if (text === "/model" || text.startsWith("/model ")) {
+				openModel();
+				return;
+			}
+			if (busy && !text.startsWith("/")) {
+				steer(text);
 				return;
 			}
-			onSubmit(text);
+			dispatch(text);
+			return;
+		}
+		if (completionActive && key.upArrow) {
+			setCompletionIndex((index) => (index + candidates.length - 1) % candidates.length);
+			return;
+		}
+		if (completionActive && key.downArrow) {
+			setCompletionIndex((index) => (index + 1) % candidates.length);
+			return;
+		}
+		if (key.upArrow) {
+			const entries = history.current;
+			if (entries.length === 0) return;
+			const next = historyIndex.current === null ? entries.length - 1 : Math.max(0, historyIndex.current - 1);
+			if (historyIndex.current === null) draft.current = value;
+			historyIndex.current = next;
+			setValue(entries[next] ?? "");
+			setCursor((entries[next] ?? "").length);
+			return;
+		}
+		if (key.downArrow) {
+			const entries = history.current;
+			if (historyIndex.current === null) return;
+			const next = historyIndex.current + 1;
+			if (next >= entries.length) {
+				historyIndex.current = null;
+				setValue(draft.current);
+				setCursor(draft.current.length);
+				return;
+			}
+			historyIndex.current = next;
+			setValue(entries[next] ?? "");
+			setCursor((entries[next] ?? "").length);
+			return;
+		}
+		if (key.tab && completionActive) {
+			const candidate = candidates[completionIndex % candidates.length];
+			if (candidate !== void 0) {
+				setValue(`${candidate.label} `);
+				setCursor(candidate.label.length + 1);
+				setCompletionIndex(0);
+			}
 			return;
 		}
 		if (key.backspace || key.delete) {
-			setValue(value.slice(0, -1));
+			if (cursor > 0) {
+				setValue(value.slice(0, cursor - 1) + value.slice(cursor));
+				setCursor(cursor - 1);
+				setCompletionIndex(0);
+			}
+			return;
+		}
+		if (key.leftArrow) {
+			setCursor(Math.max(0, cursor - 1));
+			return;
+		}
+		if (key.rightArrow) {
+			setCursor(Math.min(value.length, cursor + 1));
 			return;
 		}
-		if (input !== "") setValue(value + input);
+		if (key.ctrl && input === "u") {
+			setValue("");
+			setCursor(0);
+			return;
+		}
+		if (key.ctrl && input === "a") {
+			setCursor(0);
+			return;
+		}
+		if (key.ctrl && input === "e") {
+			setCursor(value.length);
+			return;
+		}
+		if (input !== "" && !key.ctrl && !key.meta) {
+			setValue(value.slice(0, cursor) + input + value.slice(cursor));
+			setCursor(cursor + input.length);
+			setCompletionIndex(0);
+		}
 	});
-	return createElement(Box, { flexDirection: "column" }, ...notices.map((notice, index) => createElement(Text, {
-		key: index,
-		dimColor: true
-	}, notice)), createElement(Box, null, createElement(Text, { color: inkColor(TUI_RGB.brand) }, busy ? "… " : "❯ "), createElement(Text, null, value)));
+	return createElement(Box, { flexDirection: "column" }, completionActive && !busy ? createElement(Box, {
+		flexDirection: "column",
+		marginLeft: 1
+	}, ...candidates.map((candidate, index) => createElement(Text, {
+		key: candidate.label,
+		color: index === completionIndex % candidates.length ? inkColor(TUI_RGB.brandBright) : inkColor(TUI_RGB.dim)
+	}, `${index === completionIndex % candidates.length ? "❯ " : "  "}${candidate.label} ${dim(displayText(candidate.description))}`)), createElement(Text, { dimColor: true }, dim("  ↑↓ choose · tab complete"))) : void 0, busy && value === "" ? createElement(Text, { dimColor: true }, dim("  enter steers the running turn · esc or ctrl+c cancels")) : void 0, createElement(Box, null, createElement(Text, { color: inkColor(TUI_RGB.brand) }, busy ? "… " : "❯ "), createElement(Text, null, value.slice(0, cursor)), createElement(Text, { inverse: true }, value.slice(cursor, cursor + 1) === "" ? " " : value.slice(cursor, cursor + 1)), createElement(Text, null, value.slice(cursor + 1))));
 }
 /** The whole terminal app; state arrives via the store, output via Ink. */
-function App({ store, model, cwd, branch, sessionId, onSubmit, onQuit }) {
-	const view = useSyncExternalStore(store.subscribe, store.getView);
-	return createElement(Box, { flexDirection: "column" }, createElement(Header), createElement(Box, {
+function App(props) {
+	const view = useSyncExternalStore(props.store.subscribe, props.store.getView);
+	const descriptors = useSyncExternalStore(props.commands.subscribe, () => props.commands.descriptors);
+	const skills = useSyncExternalStore(props.skills.subscribe, () => props.skills.rows);
+	const [modelLabel, setModelLabel] = useState(props.model);
+	const [modelOpen, setModelOpen] = useState(false);
+	const [directory, setDirectory] = useState(void 0);
+	const [modelError, setModelError] = useState(void 0);
+	const [notices, setNotices] = useState([]);
+	const notify = (text) => {
+		setNotices((current) => [...current, text]);
+	};
+	useEffect(() => {
+		props.onBridgeReady({ notify });
+	}, []);
+	useEffect(() => {
+		if (!modelOpen || directory !== void 0) return;
+		let cancelled = false;
+		setModelError(void 0);
+		props.loadModels().then((loaded) => {
+			if (!cancelled) setDirectory(loaded);
+		}, (error) => {
+			if (!cancelled) setModelError(error instanceof Error ? error.message : String(error));
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [modelOpen]);
+	const busy = view.busy;
+	return createElement(Box, { flexDirection: "column" }, createElement(Header, { resumed: props.resumed }), createElement(Box, {
 		flexDirection: "column",
 		paddingX: 1
 	}, ...view.entries.map((entry, index) => createElement(EntryLine, {
 		key: index,
 		entry
-	})), view.streaming !== "" ? createElement(Text, null, view.streaming) : void 0, view.busy && view.streaming === "" ? createElement(Text, { dimColor: true }, "thinking…") : void 0), createElement(Input, {
-		busy: view.busy,
-		onSubmit,
-		onQuit
+	})), view.streaming !== "" ? createElement(Text, null, displayText(view.streaming)) : void 0, busy && view.streaming === "" ? createElement(Text, { dimColor: true }, "thinking…") : void 0), createElement(TodoPanel, { todos: view.todos }), createElement(ApprovalBar, { approval: props.approval }), modelOpen ? createElement(ModelPanel, {
+		directory,
+		error: modelError,
+		onSelect: (row) => {
+			setModelLabel(props.selectModel(row));
+			notify(`model → next step uses ${row.provider}/${row.model}`);
+			setModelOpen(false);
+		},
+		onClose: () => {
+			setModelOpen(false);
+		}
+	}) : void 0, createElement(Box, { flexDirection: "column" }, ...notices.slice(-3).map((notice, index) => createElement(Text, {
+		key: index,
+		dimColor: true
+	}, notice))), createElement(Input, {
+		busy,
+		descriptors,
+		skills,
+		dispatch: props.dispatch,
+		steer: props.steer,
+		interrupt: props.interrupt,
+		quit: props.quit,
+		openModel: () => {
+			setModelOpen(true);
+		},
+		notify
 	}), createElement(StatusLine, {
 		facts: {
-			model,
-			cwd,
-			branch,
-			sessionId
+			model: modelLabel,
+			cwd: props.cwd,
+			branch: props.branch,
+			sessionId: props.sessionId
 		},
 		stats: view.stats,
-		busy: view.busy
+		busy
 	}));
 }
 //#endregion
+//#region src/approval.ts
+/**
+* Create the approval store and mount the answerer listener on the context.
+* The listener claims only requests for `owns`-owned agents and defers every
+* other request back into the waterfall (`next()`), so sibling answerers stay
+* usable. An aborted ask never reaches the human. Plugin teardown removes the
+* listener; the service then fails its own question closed.
+* @param ctx - plugin context whose event bus carries `approval/request`.
+* @param owns - agents this terminal answers for.
+* @param preview - resolves a tool-call preview for a pending request (the
+* request contract carries no arguments; the UI self-serves from the
+* transcript projection via `callId`).
+* @returns the store the renderer subscribes to.
+*/
+function mountApprovalAnswerer(ctx, owns, preview) {
+	let snapshot = {
+		pending: void 0,
+		answered: false
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const set = (next) => {
+		snapshot = next;
+		for (const listener of listeners) listener();
+	};
+	ctx.on("approval/request", (request, next) => {
+		if (!owns(request.agent)) return next();
+		if (request.signal?.aborted === true) return Promise.resolve("cancelled");
+		let resolved = false;
+		let settle;
+		const withdraw = () => {
+			if (resolved) return;
+			resolved = true;
+			set({
+				pending: void 0,
+				answered: false
+			});
+			settle("cancelled");
+		};
+		if (request.signal !== void 0) request.signal.addEventListener("abort", withdraw, { once: true });
+		const pending = {
+			headline: request.reason ?? `tool ${request.toolName} asks for your approval`,
+			toolName: request.toolName,
+			command: preview(request),
+			answer: (outcome) => {
+				if (resolved) return;
+				resolved = true;
+				set({
+					pending,
+					answered: true
+				});
+				settle(outcome);
+			}
+		};
+		set({
+			pending,
+			answered: false
+		});
+		return new Promise((resolve) => {
+			settle = resolve;
+		}).then((outcome) => {
+			if (outcome !== "cancelled") set({
+				pending: void 0,
+				answered: false
+			});
+			return outcome;
+		});
+	});
+	return {
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		getSnapshot() {
+			return snapshot;
+		}
+	};
+}
+//#endregion
+//#region src/commands.ts
+/**
+* Watch the live command registry. Reads the current list immediately and
+* re-reads on every registry mutation or agent retarget; notification
+* failures are contained by the registry itself, so this watcher only ever
+* re-reads. Without a `commands` service the view stays empty and all lines
+* fall through to normal prompts.
+* @param ctx - context carrying the `commands` service (optional).
+* @returns the view the completion menu subscribes to.
+*/
+function watchCommands(ctx) {
+	const commands = ctx.get("commands");
+	let agent;
+	let descriptors = [];
+	const listeners = /* @__PURE__ */ new Set();
+	const refresh = () => {
+		if (commands === void 0 || agent === void 0) return;
+		descriptors = commands.list(agent);
+		for (const listener of listeners) listener();
+	};
+	if (commands !== void 0) ctx.on("commands/change", () => refresh());
+	return {
+		get descriptors() {
+			return descriptors;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		setAgent(next) {
+			agent = next;
+			refresh();
+		}
+	};
+}
+/**
+* Whether one command line is a syntactically valid slash command.
+* @param line - the complete candidate line.
+* @returns true when the line parses as `/name` or `/name input`.
+*/
+function isSlashLine(line) {
+	return /^\/[a-z][a-z0-9_-]*(?=$|[\t ])/u.test(line);
+}
+//#endregion
 //#region src/internals.ts
 /**
 * Injectable process-facing effects for the TUI runner. Tests substitute the
@@ -309,6 +763,50 @@ const internals = {
 	stderr: process.stderr
 };
 //#endregion
+//#region src/models.ts
+/**
+* Load the selectable model directory from the live `ctx.llm` registry.
+* Providers are listed synchronously; each provider's models are discovered
+* with a bounded parallel fan-out whose failures degrade to that provider
+* contributing no rows (mirrors the web catalog's per-provider failures).
+* @param ctx - context carrying the `llm` service.
+* @returns the resolved directory; empty rows when `llm` is unavailable.
+*/
+async function loadModelDirectory(ctx) {
+	const llm = ctx.get("llm");
+	if (llm === void 0) return {
+		rows: [],
+		failures: []
+	};
+	const providers = llm.listProviders();
+	const listed = await Promise.all(providers.map(async (provider) => {
+		try {
+			const models = await llm.listModels(provider.id);
+			return {
+				provider: provider.id,
+				providerName: provider.name,
+				models: models.map((model) => ({
+					provider: provider.id,
+					providerName: provider.name,
+					model: model.id,
+					modelName: model.name
+				}))
+			};
+		} catch {
+			return {
+				provider: provider.id,
+				providerName: provider.name,
+				models: [],
+				failed: true
+			};
+		}
+	}));
+	return {
+		rows: listed.flatMap((entry) => entry.models),
+		failures: listed.filter((entry) => "failed" in entry && entry.failed === true).map((entry) => entry.provider)
+	};
+}
+//#endregion
 //#region src/render/projection.ts
 /**
 * Pure session-event-to-view projection for the TUI transcript: one reducer
@@ -329,6 +827,7 @@ function createTranscriptView() {
 		streaming: "",
 		todos: [],
 		busy: false,
+		model: "",
 		stats: {
 			turns: 0,
 			steps: 0,
@@ -448,6 +947,7 @@ function projectEvent(view, event) {
 		case "turn/start": return {
 			...view,
 			busy: true,
+			todos: [],
 			stats: {
 				...view.stats,
 				turns: view.stats.turns + 1
@@ -477,17 +977,67 @@ function projectEvent(view, event) {
 				}]
 			};
 		}
+		case "request/header": {
+			const config = event.data.header.config;
+			return {
+				...view,
+				model: `${config.provider}/${config.model}`
+			};
+		}
+		case "command/run": {
+			const data = event.data;
+			return {
+				...view,
+				entries: [...view.entries, {
+					kind: "command",
+					commandId: data.commandId,
+					name: data.name,
+					args: data.args ?? "",
+					state: "running",
+					summary: ""
+				}]
+			};
+		}
+		case "command/done": {
+			const data = event.data;
+			const entries = view.entries.map((entry) => {
+				if (entry.kind !== "command" || entry.commandId !== data.commandId) return entry;
+				return {
+					...entry,
+					state: data.kind === "success" ? "done" : "error",
+					summary: boundContextSummary(data.text ?? "")
+				};
+			});
+			return {
+				...view,
+				entries
+			};
+		}
 		default: return view;
 	}
 }
+/**
+* Fold a replayed event history into one view.
+* @param events - events in `seq` order.
+* @returns the folded view.
+*/
+function projectEvents(events) {
+	return events.reduce(projectEvent, createTranscriptView());
+}
 //#endregion
 //#region src/store.ts
 /**
-* Create one transcript store.
+* Create one transcript store, optionally seeded with replayed history. The
+* seed folds synchronously BEFORE the first render, so a resumed session
+* paints its full transcript on mount (no live `session/event` fires for
+* constructor seeds — the store's `session/event` feed only carries new
+* appends).
+* @param replay - persisted events in `seq` order (e.g. a resumed session's
+* constructor seed); folded once and never re-notified.
 * @returns the store the runner feeds and the renderer subscribes to.
 */
-function createTranscriptStore() {
-	let view = createTranscriptView();
+function createTranscriptStore(replay) {
+	let view = replay === void 0 ? createTranscriptView() : projectEvents(replay);
 	const listeners = /* @__PURE__ */ new Set();
 	return {
 		getView: () => view,
@@ -506,16 +1056,69 @@ function createTranscriptStore() {
 	};
 }
 //#endregion
+//#region src/skills.ts
+function toRows(skills) {
+	return skills.filter((skill) => isUserInvocable(skill)).map((skill) => ({
+		name: skill.name,
+		description: skill.description,
+		modelInvocable: skill.invocation.modelInvocable === true
+	})).sort((left, right) => left.name < right.name ? -1 : 1);
+}
+/**
+* Watch the user-invocable skill catalog for one agent's workspace. The first
+* load starts when the owning agent is known (`setAgent`); `skills/change`
+* and agent retargets re-read. Read failures keep the last good rows (the
+* next change notification is the retry surface) — a missing `skills`
+* service leaves the view permanently empty.
+* @param ctx - context carrying the `skills` service (optional).
+* @returns the view the completion menu subscribes to.
+*/
+function watchSkills(ctx) {
+	const skills = ctx.get("skills");
+	let agent;
+	let rows = [];
+	const listeners = /* @__PURE__ */ new Set();
+	const reload = () => {
+		if (skills === void 0 || agent === void 0) return;
+		skills.list({
+			cwd: agent.session.header.cwd,
+			scope: agent
+		}).then((summaries) => {
+			const next = toRows(summaries);
+			if (next.length === rows.length && next.every((row, index) => row.name === rows[index]?.name)) return;
+			rows = next;
+			for (const listener of listeners) listener();
+		}, () => {});
+	};
+	if (skills !== void 0) ctx.on("skills/change", reload);
+	return {
+		get rows() {
+			return rows;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		setAgent(next) {
+			agent = next;
+			reload();
+		}
+	};
+}
+//#endregion
 //#region src/index.ts
 /**
-* @deepseek-ai/dsh-tui — the interactive terminal driver. The bundle patch
+* @deepseek-ai/dsh-code — the interactive terminal driver. The bundle patch
 * rides over dsh-base without Host, HTTP, or browser plugins; this runner
-* creates one Agent through the core registry, mounts the Ink app (DeepSeek
-* blue, whale wordmark), folds submitted prompts into the same durable
-* session, streams `session/event` into the transcript, and on quit flushes
-* and requests process exit.
+* creates (or resumes) one Agent through the core registry, mounts the Ink
+* app (DeepSeek blue, whale wordmark), folds submitted prompts into the same
+* durable session, answers approval asks with a y/n bar, dispatches slash
+* commands through the shared registry, and on quit flushes and requests
+* process exit.
 *
-* @module @deepseek-ai/dsh-tui
+* @module @deepseek-ai/dsh-code
 */
 /** Stable Cordis plugin name. */
 const name = "tui-runner";
@@ -525,6 +1128,10 @@ const inject = [
 	"agents",
 	"sessions"
 ];
+const Config = z.object({ startup: z.object({
+	kind: z.string().required(),
+	sessionId: z.string()
+}) });
 /** Report an unexpected direct-driver failure and request a failing exit. */
 function fail(io, error) {
 	internals.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -543,36 +1150,155 @@ function gitBranch(cwd) {
 	}
 }
 /**
-* Run the interactive terminal session: create one Agent, mount the app, and
-* keep the process alive until the user quits.
+* Resolve the invocation's target session against the persisted headers.
+* @param startup - the parsed startup flags.
+* @param persistence - the persistence service; required for resume/latest.
+* @param cwd - the working directory `--continue` filters by.
+* @returns the target identity.
+* @throws with a user-facing message when the flags name nothing resolvable.
+*/
+async function resolveTarget(startup, persistence, cwd) {
+	if (startup.kind === "fresh") return {
+		sessionId: `session-${randomUUID()}`,
+		resume: false
+	};
+	if (startup.kind === "named") return {
+		sessionId: startup.sessionId,
+		resume: false
+	};
+	if (persistence === void 0) throw new Error("cannot resolve the requested session: session persistence is not configured");
+	const headers = await persistence.list();
+	if (startup.kind === "resume") {
+		const wanted = startup.sessionId;
+		const exact = headers.filter((header) => header.id === wanted);
+		const matches = exact.length > 0 ? exact : headers.filter((header) => header.id.startsWith(wanted));
+		if (matches.length === 0) throw new Error(`no persisted session matches "${wanted}"`);
+		if (matches.length > 1) throw new Error(`session prefix "${wanted}" is ambiguous (${matches.length} matches): use more of the id`);
+		return {
+			sessionId: matches[0].id,
+			resume: true
+		};
+	}
+	const local = headers.filter((header) => header.cwd === cwd).sort((left, right) => right.createdAt - left.createdAt);
+	if (local.length === 0) throw new Error(`no persisted session for this directory (${cwd}); start one without --continue`);
+	return {
+		sessionId: local[0].id,
+		resume: true
+	};
+}
+/**
+* Resolve a bounded command preview for one pending approval: the request
+* contract carries no arguments, so the bar self-serves from the transcript
+* projection via `callId` (mirrors the web ApprovalPanel's argsRaw lookup).
+* @param events - the transcript entries to search.
+* @param callId - the tool call the question is about, when the asker had one.
+* @param toolName - the tool the question is about.
+* @returns a bounded preview line, '' when nothing useful resolves.
+*/
+function approvalCommandPreview(events, callId, toolName) {
+	if (callId === void 0) return "";
+	const entry = events.find((candidate) => candidate.kind === "tool" && candidate.callId === callId);
+	if (entry === void 0) return "";
+	const args = entry.arguments ?? "";
+	try {
+		const parsed = JSON.parse(args);
+		if (parsed !== null && typeof parsed === "object") {
+			const record = parsed;
+			for (const key of [
+				"command",
+				"cmd",
+				"description",
+				"path",
+				"pattern",
+				"query"
+			]) {
+				const value = record[key];
+				if (typeof value === "string" && value !== "") return value;
+			}
+		}
+	} catch {}
+	return args.length > 80 ? `${args.slice(0, 77)}...` : args === "" ? toolName : args;
+}
+/**
+* Run the interactive terminal session: resolve the target session, create or
+* resume one Agent, mount the app, and keep the process alive until the user
+* quits.
 * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+* @param startup - the parsed invocation flags.
 * @param io - process-facing effects.
 */
-async function run(ctx, io) {
+async function run(ctx, startup, io) {
 	await ctx.get("loader")?.await();
 	const agents = ctx.get("agents");
 	const defaultModel = ctx.get("agentDefaultModel");
 	const sessions = ctx.get("sessions");
+	const persistence = ctx.get("sessionPersistence");
 	if (agents === void 0 || defaultModel === void 0 || sessions === void 0) return;
-	const selection = defaultModel.currentSelection();
-	const { agent } = await agents.create({
-		sessionId: SessionId(`session-${randomUUID()}`),
-		meta: { cwd: process.cwd() },
-		agentOptions: {
-			provider: selection.provider,
-			model: selection.model
-		},
-		setup: (agentCtx) => {
-			installModelSelection(agentCtx, {
-				current: selection,
-				assembled: void 0
-			});
-		}
-	});
-	const store = createTranscriptStore();
-	const off = ctx.on("session/event", (session, event) => {
-		if (session.id === agent.session.id) store.apply(event);
+	const cwd = process.cwd();
+	const target = await resolveTarget(startup, persistence, cwd);
+	const defaults = defaultModel.currentSelection();
+	let picked;
+	let session;
+	let agent;
+	if (target.resume) {
+		agent = (await agents.resume({
+			resumeSessionId: SessionId(target.sessionId),
+			agentOptions: {
+				provider: defaults.provider,
+				model: defaults.model
+			},
+			setup: (agentCtx) => {
+				installModelSelection(agentCtx, {
+					get current() {
+						if (picked !== void 0) return picked;
+						const logged = agentCtx.agent?.session.requestHeader()?.config;
+						if (logged !== void 0) return {
+							provider: logged.provider,
+							model: logged.model,
+							...logged.reasoningEffort === void 0 ? {} : { reasoningEffort: logged.reasoningEffort }
+						};
+						return defaults;
+					},
+					set current(next) {
+						picked = next;
+					},
+					assembled: void 0
+				});
+			}
+		})).agent;
+		session = agent.session;
+	} else {
+		agent = (await agents.create({
+			sessionId: SessionId(target.sessionId),
+			meta: { cwd },
+			agentOptions: {
+				provider: defaults.provider,
+				model: defaults.model
+			},
+			setup: (agentCtx) => {
+				installModelSelection(agentCtx, {
+					get current() {
+						return picked ?? defaults;
+					},
+					set current(next) {
+						picked = next;
+					},
+					assembled: void 0
+				});
+			}
+		})).agent;
+		session = agent.session;
+	}
+	const store = createTranscriptStore(session.events);
+	const off = ctx.on("session/event", (subject, event) => {
+		if (subject.id === session.id) store.apply(event);
 	});
+	const commands = watchCommands(ctx);
+	commands.setAgent(agent);
+	const skills = watchSkills(ctx);
+	skills.setAgent(agent);
+	const approval = mountApprovalAnswerer(ctx, (candidate) => candidate.id === agent.id, (request) => approvalCommandPreview(store.getView().entries, request.callId, request.toolName));
+	const bridge = { notify: () => {} };
 	const mountRef = {};
 	let quitting = false;
 	const quit = () => {
@@ -580,44 +1306,120 @@ async function run(ctx, io) {
 		quitting = true;
 		off();
 		mountRef.current?.unmount();
-		sessions.flush(agent.session).catch((flushError) => {
+		sessions.flush(session).catch((flushError) => {
 			internals.stderr.write(`dsh: session flush failed: ${flushError instanceof Error ? flushError.message : String(flushError)}\n`);
 		}).then(() => {
 			io.exit(0);
 		});
 	};
+	/** Dispatch one submitted line: slash commands to the registry, other text to the agent. */
+	const dispatch = (text) => {
+		const line = text.trim();
+		if (line === "") return;
+		if (isSlashLine(line)) {
+			const registry = ctx.get("commands");
+			if (registry === void 0) {
+				bridge.notify("no command registry is mounted in this composition");
+				return;
+			}
+			const controller = new AbortController();
+			registry.execute(agent, line, controller.signal).then((execution) => {
+				if (execution === void 0) agent.followup(createUserMessage({
+					content: [{
+						type: "text",
+						text: line
+					}],
+					source: { kind: "user" }
+				}));
+			}, (error) => {
+				bridge.notify(`command failed: ${error instanceof Error ? error.message : String(error)}`);
+			});
+			return;
+		}
+		agent.followup(createUserMessage({
+			content: [{
+				type: "text",
+				text: line
+			}],
+			source: { kind: "user" }
+		}));
+	};
+	/**
+	* Submit steering: a running driver consumes the text at its next step
+	* boundary (the inbox delivers between steps); an idle driver just starts
+	* a turn, so this doubles as the busy-state submit path.
+	*/
+	const steer = (text) => {
+		const line = text.trim();
+		if (line === "") return;
+		agent.steer(createUserMessage({
+			content: [{
+				type: "text",
+				text: line
+			}],
+			source: { kind: "user" }
+		}));
+		bridge.notify("steering queued — the next step sees it");
+	};
+	/** Interrupt the running turn (Esc); true when a turn was actually cancelled. */
+	const interrupt = () => {
+		if (agent.status !== "running") return false;
+		agent.cancel({ kind: "user" });
+		bridge.notify("turn cancelled — Ctrl+C or /quit to exit");
+		return true;
+	};
+	/** Apply one /model selection: takes effect from the next assembled step. */
+	const selectModel = (row) => {
+		picked = {
+			provider: row.provider,
+			model: row.model
+		};
+		return `${row.provider}/${row.model}`;
+	};
+	const initialModel = store.getView().model !== "" ? store.getView().model : `${defaults.provider}/${defaults.model}`;
 	mountRef.current = io.mount(createElement(App, {
 		store,
-		model: `${selection.provider}/${selection.model}`,
-		cwd: basename(process.cwd()),
-		branch: gitBranch(process.cwd()),
-		sessionId: agent.session.id.slice(-8),
-		onSubmit: (text) => {
-			agent.followup(createUserMessage({
-				content: [{
-					type: "text",
-					text
-				}],
-				source: { kind: "user" }
-			}));
-		},
-		onQuit: quit
+		approval,
+		commands,
+		skills,
+		model: initialModel,
+		cwd: basename(cwd),
+		branch: gitBranch(cwd),
+		sessionId: session.id.slice(-8),
+		resumed: target.resume,
+		dispatch,
+		steer,
+		interrupt,
+		quit,
+		loadModels: () => loadModelDirectory(ctx),
+		selectModel,
+		onBridgeReady: (instance) => {
+			bridge.notify = instance.notify;
+		}
 	}));
 }
 /**
 * Mount the interactive terminal driver.
 * @param ctx - plugin context carrying core services and the launcher-provided exit request.
+* @param config - validated startup config resolved from the tuiStartup provider.
 */
-function apply(ctx) {
+function apply(ctx, config) {
+	const startup = config.startup.kind === "resume" && config.startup.sessionId !== void 0 ? {
+		kind: "resume",
+		sessionId: config.startup.sessionId
+	} : config.startup.kind === "latest" ? { kind: "latest" } : config.startup.kind === "named" && config.startup.sessionId !== void 0 ? {
+		kind: "named",
+		sessionId: config.startup.sessionId
+	} : { kind: "fresh" };
 	const exit = ctx.get("appExit");
 	if (exit === void 0) throw new Error("tui-runner: the launcher must provide ctx.appExit before the tree mounts");
 	const io = {
 		mount: internals.mount,
 		exit
 	};
-	run(ctx, io).catch((error) => {
+	run(ctx, startup, io).catch((error) => {
 		fail(io, error);
 	});
 }
 //#endregion
-export { apply, inject, name };
+export { Config, apply, inject, name };