dsh-code 0.4.0 → 0.5.0

package/lib/startup.mjs

@@ -3,7 +3,7 @@ import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
 //#region src/startup.ts
 /**
 * The interactive terminal app's command-line provider: parses `--resume`,
-* `--continue`, `--session`, and `--help`, then publishes
+* `--continue`, `--session`, `--mode`, and `--help`, then publishes
 * {@link TUI_STARTUP_SERVICE} for the runner to consume lazily. Follows the
 * headless bundle's startup shape (a commander action publishing a service
 * through {@link parseCmdline}).
@@ -26,17 +26,41 @@ const name = "tui-startup";
 const inject = ["cmdlineArgs"];
 /** Service provided by this plugin and injected by the terminal runner. */
 const TUI_STARTUP_SERVICE = "tuiStartup";
+/** Pure option policy shared by Commander and tests. */
+function resolveTuiStartup(options) {
+	if ([
+		options.resume !== void 0,
+		options.continue === true,
+		options.session !== void 0
+	].filter(Boolean).length > 1) throw new Error("--resume, --continue, and --session are mutually exclusive");
+	if (options.session === "") throw new Error("--session needs an id");
+	if (options.resume === "") throw new Error("--resume needs a session id or id prefix");
+	if (options.mode === "") throw new Error("--mode needs a preset id");
+	if (options.mode !== void 0 && (options.resume !== void 0 || options.continue === true)) throw new Error("--mode applies only to a new session; it cannot be combined with --resume or --continue");
+	return options.resume !== void 0 ? {
+		kind: "resume",
+		sessionId: options.resume
+	} : options.continue === true ? { kind: "latest" } : options.session !== void 0 ? {
+		kind: "named",
+		sessionId: options.session,
+		...options.mode === void 0 ? {} : { mode: options.mode }
+	} : {
+		kind: "fresh",
+		...options.mode === void 0 ? {} : { mode: options.mode }
+	};
+}
 /**
 * This app's command: the launcher's flags this app owns, its description,
 * and its help text.
 * @returns a fresh program, so one process can parse more than once (tests).
 */
 function tuiCommand() {
-	return new Command().name("dsh --profile cli").description("Claude-Code-style interactive terminal for DeepSeek Harness.").helpOption("-h, --help", "show this help").option("-r, --resume <session>", "resume the persisted session with this id (or unique id prefix)").option("-c, --continue", "resume the most recent persisted session for this working directory").option("--session <id>", "create a new session under this explicit id").addHelpText("after", `
+	return new Command().name("dsh --profile cli").description("Claude-Code-style interactive terminal for DeepSeek Harness.").helpOption("-h, --help", "show this help").option("-r, --resume <session>", "resume the persisted session with this id (or unique id prefix)").option("-c, --continue", "resume the most recent persisted session for this working directory").option("--session <id>", "create a new session under this explicit id").option("--mode <preset>", "agent preset for a newly created session").addHelpText("after", `
 Examples:
   dsh --profile cli                       fresh session, minted id
   dsh --profile cli --resume abc123       resume session by id prefix
   dsh --profile cli --continue            resume the latest local session
+  dsh --profile cli --mode minimal        fresh session using the minimal preset
 `);
 }
 /**
@@ -48,23 +72,16 @@ function apply(ctx) {
 	const program = tuiCommand();
 	program.action(() => {
 		const options = program.opts();
-		if ([
-			options.resume !== void 0,
-			options.continue === true,
-			options.session !== void 0
-		].filter(Boolean).length > 1) program.error("error: --resume, --continue, and --session are mutually exclusive");
-		if (options.session !== void 0 && options.session === "") program.error("error: --session needs an id");
-		if (options.resume !== void 0 && options.resume === "") program.error("error: --resume needs a session id or id prefix");
-		const startup = options.resume !== void 0 ? {
-			kind: "resume",
-			sessionId: options.resume
-		} : options.continue === true ? { kind: "latest" } : options.session !== void 0 ? {
-			kind: "named",
-			sessionId: options.session
-		} : { kind: "fresh" };
+		let startup;
+		try {
+			startup = resolveTuiStartup(options);
+		} catch (error) {
+			program.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (startup === void 0) return;
 		ctx.provide(TUI_STARTUP_SERVICE, { startup });
 	});
 	parseCmdline(ctx, program);
 }
 //#endregion
-export { TUI_STARTUP_SERVICE, apply, inject, name };
+export { TUI_STARTUP_SERVICE, apply, inject, name, resolveTuiStartup };

package/lib/types/app.d.ts

@@ -21,6 +21,11 @@ import type { ModelDirectory, ModelRow } from './models.ts';
 import type { QuestionStore } from './questions.ts';
 import type { SkillsView } from './skills.ts';
 import type { MentionCandidate } from './mentions.ts';
+import type { PresetRow } from './presets.ts';
+import type { PluginRow } from './plugin-inventory.ts';
+import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
+/** Visual priority for one bounded local notice. */
+export type NoticeTone = 'info' | 'warning' | 'error';
 /** Props the runner hands the app; callbacks stay owned by the runner. */
 export interface AppProps {
     /** Event-fed transcript store for the live session. */
@@ -37,12 +42,16 @@ export interface AppProps {
     model: string;
     /** Working-directory basename the session serves. */
     cwd: string;
+    /** Absolute working directory used by session filters and references. */
+    workspaceRoot: string;
     /** Git branch name, empty outside a repository. */
     branch: string;
     /** Short session identifier. */
     sessionId: string;
     /** Whether this session was resumed from persistence. */
     resumed: boolean;
+    /** Agent preset currently composing the session. */
+    mode: string;
     /** Submit one line: slash commands to the registry, other text to the agent. */
     dispatch(text: string): void;
     /** Submit steering: consumed at the running turn's next step boundary. */
@@ -63,9 +72,18 @@ export interface AppProps {
     exportTranscript(argument: string): Promise<void>;
     /** Rename the session (/title <text>); returns the outcome line for the notice. */
     renameTitle(argument: string): string;
+    /** Preset/session/plugin kernel operations. */
+    loadPresets(): Promise<readonly PresetRow[]>;
+    switchMode(id: string): Promise<string>;
+    createSession(mode?: string): void;
+    loadSessions(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>;
+    loadSessionTranscript(id: string, signal?: AbortSignal): Promise<string>;
+    switchSession(row: SessionRow): void;
+    cancelSessionSwitch(): boolean;
+    loadPlugins(): readonly PluginRow[];
     /** Registers the app's notice channel with the runner (called once on mount). */
     onBridgeReady(bridge: {
-        notify(text: string): void;
+        notify(text: string, tone?: NoticeTone): void;
     }): void;
 }
 /** The whole terminal app; state arrives via the store, output via Ink. */

package/lib/types/commands.d.ts

@@ -14,6 +14,8 @@ import type { CommandDescriptor } from '@deepseek-ai/dsh-commands';
 export interface CommandsView {
     /** Name-sorted descriptors after scoped shadowing. */
     readonly descriptors: readonly CommandDescriptor[];
+    /** Latest descriptor-read failure; the help panel exposes it in place. */
+    readonly error?: string;
     /** Subscribe to list changes (`commands/change`); returns the unsubscribe function. */
     subscribe(listener: () => void): () => void;
     /** Retarget the agent whose scoped view the list is read through. */

package/lib/types/index.d.ts

@@ -1,11 +1,10 @@
 /**
  * @deepseek-ai/dsh-code — the interactive terminal driver. The bundle patch
  * rides over dsh-base without Host, HTTP, or browser plugins; this runner
- * 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.
+ * creates or resumes preset-composed Agents through the core registry, keeps
+ * one Ink owner while the active session changes, folds submitted prompts
+ * into the selected durable session, answers approval asks with a y/n bar,
+ * dispatches slash commands, and on quit flushes and requests process exit.
  *
  * @module @deepseek-ai/dsh-code
  */
@@ -21,6 +20,7 @@ export interface Config {
     startup: {
         kind: string;
         sessionId?: string;
+        mode?: string;
     };
 }
 export declare const Config: z<Config>;

package/lib/types/internals.d.ts

@@ -8,6 +8,8 @@
 import type { ReactElement } from 'react';
 /** A mounted terminal app instance; the runner owns unmount ordering. */
 export interface TuiMount {
+    /** Replace the root element while preserving Ink's single terminal owner. */
+    rerender(element: ReactElement): void;
     /** Tear the terminal app down before flush and exit. */
     unmount(): void;
 }

package/lib/types/kernel-panels.d.ts

@@ -0,0 +1,23 @@
+/** Bounded, composer-safe panels for preset, session, and plugin kernel views. */
+import { type ReactElement } from 'react';
+import type { PresetRow } from './presets.ts';
+import type { PluginRow } from './plugin-inventory.ts';
+import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
+export declare function ModePanel({ current, load, select, close }: {
+    current: string;
+    load(): Promise<readonly PresetRow[]>;
+    select(id: string): void;
+    close(): void;
+}): ReactElement;
+export declare function PluginPanel({ load, close, initialQuery }: {
+    load(): readonly PluginRow[];
+    close(): void;
+    initialQuery?: string;
+}): ReactElement;
+export declare function ResumePanel({ currentCwd, load, readTranscript, select, close }: {
+    currentCwd: string;
+    load(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>;
+    readTranscript(id: string, signal?: AbortSignal): Promise<string>;
+    select(row: SessionRow): void;
+    close(): void;
+}): ReactElement;

package/lib/types/plugin-inventory.d.ts

@@ -0,0 +1,11 @@
+/** Read-only projection of Cordis Loader entries for /plugin. */
+import type { Context } from '@deepseek-ai/cordis';
+export type PluginPhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | null;
+export interface PluginRow {
+    readonly entryId: string;
+    readonly moduleName: string;
+    readonly enabled: boolean;
+    readonly phase: PluginPhase;
+}
+/** Snapshot the live Loader; group-only rows are composition containers, not plugins. */
+export declare function listPluginRows(ctx: Context): PluginRow[];

package/lib/types/presets.d.ts

@@ -0,0 +1,32 @@
+/** Agent-preset policy kept independent from the Ink surface. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+/** One discoverable agent composition. */
+export interface PresetRow {
+    readonly id: string;
+    readonly trust: 'system' | 'user';
+    readonly name?: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly broken?: string;
+}
+/** Structural boundary for the optional upstream AgentPresets service. */
+export interface AgentPresetsService {
+    readonly defaultId: string;
+    list(): Promise<PresetRow[]>;
+    resolve(id?: string): Promise<PresetRow>;
+    mount(agentCtx: Context, id?: string): Promise<PresetRow>;
+    recompose(agentCtx: Context, id: string): Promise<PresetRow>;
+    composedPreset(agentCtx: Context): string | undefined;
+}
+/** Read an optional Cordis service without requiring its package at build time. */
+export declare function agentPresetsFrom(ctx: Context): AgentPresetsService | undefined;
+/** A preset may change only before the first durable turn begins. */
+export declare function isBlankSession(events: readonly SessionEvent[]): boolean;
+/** Latest logged selection wins; legacy sessions deliberately fall back to standard. */
+export declare function resolvePreset(session: Pick<Session, 'header' | 'events'>): string;
+/** Recompose atomically from the caller's perspective, logging only success. */
+export declare function switchPreset(service: AgentPresetsService, agent: Agent, presetId: string): Promise<PresetRow>;
+/** Minimal handle shape used by lifecycle tests without exposing Agent internals. */
+export type OwnedAgent = Pick<AgentHandle, 'agent' | 'dispose'>;

package/lib/types/render/inspector.d.ts

@@ -5,11 +5,15 @@ export interface InspectorViewport {
     maxHeight: number;
     /** Rows available to the selected entry after border, title, and footer. */
     bodyRows: number;
+    /** Optional blank rows separating title/body/footer on roomy terminals. */
+    gapRows: 0 | 2;
     /** Columns available inside the horizontal border and padding. */
     contentColumns: number;
     /** Tiny terminals use a borderless one-line close hint. */
     compact: boolean;
 }
+/** One transcript-to-composer gutter, collapsed on short terminals. */
+export declare function layoutGutterRows(rows: number): 0 | 1;
 /**
  * Keep the inspector plus its persistent status/composer chrome below
  * `stdout.rows`: at equality Ink clears the terminal and rewrites all

package/lib/types/render/status.d.ts

@@ -38,6 +38,8 @@ export declare function cacheHitPercent(usage: TranscriptStats['usage']): number
 export interface StatusFacts {
     /** `provider/model` selection serving this session. */
     model: string;
+    /** Agent preset composing this session. */
+    mode?: string;
     /** Working-directory basename the session serves. */
     cwd: string;
     /** Git branch name, empty outside a repository or on a detached HEAD file. */

package/lib/types/render/text.d.ts

@@ -16,6 +16,15 @@
  * as a literal `\xNN` escape.
  */
 export declare function displayText(text: string): string;
+/** Collapse external text to one terminal-safe logical row. */
+export declare function singleLineText(text: string): string;
+/**
+ * Truncate one display-safe row without ever exceeding its physical-column
+ * budget. The ellipsis is included inside the budget, matching Codex's popup
+ * truncation contract; the previous app-local helper appended it after the
+ * row was already full and could force an extra terminal wrap.
+ */
+export declare function truncateColumns(text: string, columns: number): string;
 /** A display-safe suffix bounded by terminal rows and columns. */
 export interface DisplayTail {
     /** Sanitized suffix suitable for direct terminal rendering. */

package/lib/types/session-directory.d.ts

@@ -0,0 +1,54 @@
+/** Lightweight session-directory projection for the /resume picker. */
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+export interface SessionRecord {
+    readonly header: SessionHeader;
+    readonly live: boolean;
+    readonly persisted: boolean;
+}
+export interface TitleObservationResult {
+    readonly sessionId: string;
+    readonly status: 'fulfilled' | 'rejected';
+    readonly value?: {
+        readonly title?: {
+            readonly title?: string;
+            readonly text?: string;
+        };
+    };
+}
+export interface SessionLogSnapshot {
+    readonly session: SessionHeader;
+    readonly events: SessionEvent[];
+}
+/** Structural upstream SessionQuery surface used by the TUI. */
+export interface SessionQueryService {
+    listSessions(signal?: AbortSignal): Promise<SessionRecord[]>;
+    readTitleSnapshots(ids: readonly string[], signal?: AbortSignal): Promise<TitleObservationResult[]>;
+    readSession(id: string, signal?: AbortSignal): Promise<SessionLogSnapshot>;
+}
+export type SessionScope = 'roots' | 'all';
+export type CwdScope = 'all' | 'current';
+export type SessionSort = 'newest' | 'oldest';
+export interface SessionDirectoryOptions {
+    readonly sessions: SessionScope;
+    readonly cwd: CwdScope;
+    readonly sort: SessionSort;
+    readonly currentCwd: string;
+    readonly query: string;
+}
+export interface SessionRow {
+    readonly id: string;
+    readonly createdAt: number;
+    readonly cwd: string;
+    readonly workspace: string;
+    readonly parent?: string;
+    readonly subagent: boolean;
+    readonly resumable: boolean;
+    readonly live: boolean;
+    readonly persisted: boolean;
+    readonly preset: string;
+    readonly title?: string;
+}
+/** Filter/sort header-only records. No session log is loaded here. */
+export declare function projectSessionRows(records: readonly SessionRecord[], options: SessionDirectoryOptions): SessionRow[];
+/** Merge page-local title observations without disturbing directory order. */
+export declare function mergeSessionTitles(rows: readonly SessionRow[], observations: readonly TitleObservationResult[]): SessionRow[];

package/lib/types/session-switch.d.ts

@@ -0,0 +1,17 @@
+/** Latest-wins, idle-bound queue for safe Agent session changes. */
+export interface IdleActivity {
+    readonly status: 'idle' | 'running';
+    whenIdle(): Promise<void>;
+}
+export declare class SessionSwitchQueue<T> {
+    private readonly execute;
+    private readonly failed;
+    private pending;
+    private pumping;
+    constructor(execute: (value: T) => Promise<void>, failed: (error: unknown) => void);
+    /** Queue a request; a later request replaces any request still waiting. */
+    request(activity: IdleActivity, value: T): 'queued' | 'started';
+    /** Cancel only work that has not begun activation. */
+    cancel(): boolean;
+    private pump;
+}

package/lib/types/skills.d.ts

@@ -23,6 +23,8 @@ export interface SkillRow {
 export interface SkillsView {
     /** Name-sorted user-invocable rows; empty until the first load lands. */
     readonly rows: readonly SkillRow[];
+    /** Latest catalog-read failure; the help panel exposes it in place. */
+    readonly error?: string;
     /** Subscribe to catalog changes; returns the unsubscribe function. */
     subscribe(listener: () => void): () => void;
     /** Retarget the agent whose workspace the catalog is read for. */

package/lib/types/startup.d.ts

@@ -1,6 +1,6 @@
 /**
  * The interactive terminal app's command-line provider: parses `--resume`,
- * `--continue`, `--session`, and `--help`, then publishes
+ * `--continue`, `--session`, `--mode`, and `--help`, then publishes
  * {@link TUI_STARTUP_SERVICE} for the runner to consume lazily. Follows the
  * headless bundle's startup shape (a commander action publishing a service
  * through {@link parseCmdline}).
@@ -27,15 +27,25 @@ export declare const TUI_STARTUP_SERVICE = "tuiStartup";
 /** How the runner obtains its session identity. */
 export type TuiStartup = {
     readonly kind: 'fresh';
+    readonly mode?: string;
 } | {
     readonly kind: 'named';
     readonly sessionId: string;
+    readonly mode?: string;
 } | {
     readonly kind: 'resume';
     readonly sessionId: string;
 } | {
     readonly kind: 'latest';
 };
+export interface TuiStartupOptions {
+    readonly resume?: string;
+    readonly continue?: boolean;
+    readonly session?: string;
+    readonly mode?: string;
+}
+/** Pure option policy shared by Commander and tests. */
+export declare function resolveTuiStartup(options: TuiStartupOptions): TuiStartup;
 /**
  * Parse the invocation and publish the startup service. Mutual exclusions are
  * usage errors rejected from the action before anything is provided.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "dsh-code",
   "description": "Claude-Code-style interactive TUI bundle for DeepSeek Harness (dsh): DeepSeek-blue whale banner, live session transcript, and a blended status line",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
+  "bin": {
+    "deepseek": "./bin/deepseek.mjs",
+    "dsh-code": "./bin/deepseek.mjs"
+  },
   "main": "lib/index.mjs",
   "types": "lib/types/index.d.ts",
   "exports": {
@@ -52,6 +56,7 @@
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "gen:whale": "tsx scripts/gen-whale-glyph.ts",
+    "prepare": "pnpm build",
     "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
   },
   "engines": {