dsh-code 0.6.1 → 0.8.0

package/lib/types/app.d.ts

@@ -14,14 +14,19 @@
  * @module @deepseek-ai/dsh-code/app
  */
 import { type ReactElement } from 'react';
+import type { CommandDescriptor } from '@deepseek-ai/dsh-commands';
+import { type ThemeName } from './theme.ts';
 import type { TranscriptStore } from './store.ts';
+import { type TranscriptEntry } from './render/projection.ts';
 import type { ApprovalStore } from './approval.ts';
 import type { CommandsView } from './commands.ts';
 import type { ModelDirectory, ModelRow } from './models.ts';
+import type { ProviderSettingsDirectory, ProviderTargetView } from './provider-settings.ts';
 import type { QuestionStore } from './questions.ts';
-import type { SkillsView } from './skills.ts';
+import type { SkillsView, SkillRow } from './skills.ts';
 import type { MentionCandidate } from './mentions.ts';
 import type { PresetRow } from './presets.ts';
+import type { PermissionRow } from './permissions.ts';
 import type { PluginRow } from './plugin-inventory.ts';
 import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
 /** Visual priority for one bounded local notice. */
@@ -40,6 +45,8 @@ export interface AppProps {
     skills: SkillsView;
     /** `provider/model` selection serving this session (updated on /model). */
     model: string;
+    /** Effective reasoning effort in force ('' when none), for the /model picker mark. */
+    effort?: string;
     /** Working-directory basename the session serves. */
     cwd: string;
     /** Absolute working directory used by session filters and references. */
@@ -50,8 +57,10 @@ export interface AppProps {
     sessionId: string;
     /** Whether this session was resumed from persistence. */
     resumed: boolean;
-    /** Agent preset currently composing the session. */
+    /** Agent preset selected for the current or pending first session. */
     mode: string;
+    /** Permission preset selected for the current or pending first session. */
+    permission: 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. */
@@ -64,10 +73,22 @@ export interface AppProps {
     loadModels(): Promise<ModelDirectory>;
     /** Load @mention candidates for the typed query (files + sessions). */
     loadMentions(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]>;
-    /** Apply one /model selection; returns the display label. */
-    selectModel(row: ModelRow): string;
+    /** Apply one /model selection (with an advertised reasoning effort, when picked); returns the display label. */
+    selectModel(row: ModelRow, effortId?: string): string;
+    /** Load provider/settings/credential facts for the optional /model provider stage. */
+    loadModelProviders?(): Promise<ProviderSettingsDirectory>;
+    /** Subscribe to Harness credential/settings/adapter invalidations while /model is open. */
+    subscribeModelProviders?(listener: () => void): () => void;
+    /** Store or rotate one provider credential through the Harness credential service. */
+    saveModelProviderCredential?(target: ProviderTargetView, key: string): Promise<void>;
+    /** Remove one writable provider credential without removing its settings profile. */
+    unsetModelProviderCredential?(target: ProviderTargetView): Promise<void>;
+    /** Remove one user-owned provider profile and its page-managed credential. */
+    removeModelProvider?(target: ProviderTargetView): Promise<void>;
     /** Cycle to the next permission preset (Shift+Tab); returns the new label. */
     cyclePermission(): string;
+    /** Select or inspect a permission preset without requiring a pre-existing session. */
+    setPermission(id: string): string;
     /** Export the transcript to a markdown file (/export [path]); reports via notices. */
     exportTranscript(argument: string): Promise<void>;
     /** Rename the session (/title <text>); returns the outcome line for the notice. */
@@ -75,6 +96,8 @@ export interface AppProps {
     /** Preset/session/plugin kernel operations. */
     loadPresets(): Promise<readonly PresetRow[]>;
     switchMode(id: string): Promise<string>;
+    /** Load the switchable permission presets for the /permission panel. */
+    loadPermissions(): Promise<readonly PermissionRow[]>;
     createSession(mode?: string): void;
     loadSessions(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>;
     loadSessionTranscript(id: string, signal?: AbortSignal): Promise<string>;
@@ -89,6 +112,8 @@ export interface AppProps {
     statusline: readonly string[];
     /** Persist a new statusline item set; the runner surfaces IO failures as notices. */
     saveStatusline(items: readonly string[]): void;
+    /** Apply and persist one /theme selection; the runner owns the theme.json file. */
+    saveTheme?(name: ThemeName): void;
     /** Persistent cross-session input history (oldest first); the runner owns the file. */
     history: readonly string[];
     /** Persist one submitted prompt to the global history file. */
@@ -96,5 +121,84 @@ export interface AppProps {
     /** Cancel one queued inbox message by identity (Delete on the empty composer). */
     cancelQueued(messageId: string): void;
 }
+/** One completion candidate row. */
+interface CompletionCandidate {
+    /** Insertion text for the command name (with leading slash). */
+    label: string;
+    /** Human-readable description shown beside the label. */
+    description: string;
+    /** Candidate origin; skills land the same literal text but route through the prompt. */
+    origin: 'command' | 'skill' | 'mention' | 'path';
+}
+/**
+ * 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), and a
+ * later duplicate name never renders twice.
+ *
+ * A bare `/` returns the FULL merged list — Codex's command popup shows every
+ * command inside a scroll window on an empty filter, and the menu's own
+ * selection window bounds the visible rows, so no slice cap is needed.
+ */
+export declare function completionCandidates(value: string, descriptors: readonly CommandDescriptor[], skills: readonly SkillRow[]): readonly CompletionCandidate[];
+/** One cached settled row: the row Box plus its roomy-prompt spacers. */
+interface SettledRowRecord {
+    /** The row Box element (keyed by the entry's settled index). */
+    box: ReactElement;
+    /** The roomy-prompt spacer BEFORE the row, or undefined. */
+    before: ReactElement | undefined;
+    /** The roomy-prompt spacer AFTER the row, or undefined. */
+    after: ReactElement | undefined;
+    /** Whether the row's text depends on the reasoning toggle (Ctrl+R). */
+    reasonSensitive: boolean;
+    /** The toggle state the row was built with. */
+    showReasoning: boolean;
+}
+/** The incremental settled-history cache (see `computeSettledRows`). */
+interface SettledRowsCache {
+    /** The exact settled entries the cache covers (`view.entries[0..entries.length)`). */
+    entries: TranscriptEntry[];
+    /** Records keyed by entry identity; mutated in place so the append path
+     * never copies the whole map. */
+    records: Map<TranscriptEntry, SettledRowRecord>;
+    /** The header element (depends only on `resumed`). */
+    header: ReactElement;
+    /** The `resumed` the header was built with. */
+    resumed: boolean;
+    /** The toggle state the rows were built with. */
+    showReasoning: boolean;
+    /** The refreshEpoch the rows were built for; a bump forces a full rebuild. */
+    epoch: number;
+    /** The flat row list (header + per-entry before/box/after). */
+    flat: ReactElement[];
+}
+/** One step of `computeSettledRows`. */
+interface SettledRowsResult {
+    cache: SettledRowsCache;
+    /** How many rows had to be BUILT by this step (0 = pure reuse). */
+    built: number;
+}
+/**
+ * The settled `<Static>` row set as a PURE incremental state machine (App
+ * drives it from the memo; tests drive it directly and read `built`).
+ *
+ * The settled prefix is permanently final: the projection only APPENDS below
+ * the flush boundary, removes pending rows at or beyond it, and replaces
+ * running tool/retry/command rows there too. So extending the cache never
+ * rescans the old prefix — a grown boundary builds ONLY the newly settled
+ * suffix and reuses every cached element, letting React bail out of unchanged
+ * rows and keeping long histories out of the per-durable-event path (no O(N)
+ * rebuild of rows, Map, or MarkdownBody parses). `records` is mutated in place
+ * on the append/toggle paths to stay O(delta).
+ *
+ * Full rebuilds run only on the rare, deliberate paths: no cache yet, a
+ * source-backed replay (`epoch` bump: resize / Ctrl+L / Ctrl+R remounts
+ * `<Static>` and must re-flush the CURRENT rows), a `resumed` change, or a shrink
+ * (`store.reset`). A reasoning toggle rebuilds only the rows whose text
+ * depends on it, preserving the other rows' element identity.
+ */
+export declare function computeSettledRows(previous: SettledRowsCache | undefined, entries: readonly TranscriptEntry[], settled: number, showReasoning: boolean, resumed: boolean, epoch: number): SettledRowsResult;
 /** The whole terminal app; state arrives via the store, output via Ink. */
 export declare function App(props: AppProps): ReactElement;
+export {};

package/lib/types/history.d.ts

@@ -7,8 +7,8 @@
  *
  * @module @deepseek-ai/dsh-tui/history
  */
-/** Maximum entries retained in the persistent history file. */
-export declare const HISTORY_MAX_ENTRIES = 500;
+/** Maximum entries retained in the persistent history file and the local recall pool. */
+export declare const HISTORY_MAX_ENTRIES = 100;
 /** Encode one entry for the history file (JSON keeps multi-line drafts intact). */
 export declare function serializeHistoryEntry(text: string): string;
 /**
@@ -31,12 +31,23 @@ export declare function parseHistoryFile(raw: string, max?: number): readonly st
 export declare function appendHistoryContent(current: string, text: string, max?: number): string;
 /**
  * Record one in-session submission: empty text is ignored and an adjacent
- * duplicate collapses (Codex `record_local_submission` semantics).
+ * duplicate collapses (Codex `record_local_submission` semantics). The local
+ * pool shares the persistent pool's cap so the recall space stays bounded.
  * @param local - current in-session entries, oldest first.
  * @param text - the submitted prompt.
+ * @param max - the local pool cap.
  * @returns the updated local list.
  */
-export declare function recordLocalEntry(local: readonly string[], text: string): readonly string[];
+export declare function recordLocalEntry(local: readonly string[], text: string, max?: number): readonly string[];
+/**
+ * Serialize a capped entry list to the history file format (one JSON line per
+ * entry, trailing newline). The runner writes the in-memory list as the whole
+ * file, so rapid same-process submissions cannot lose entries to a
+ * read-modify-write race (the file is never read back before writing).
+ * @param entries - the entries to persist, oldest first.
+ * @returns the file content, '' for an empty list.
+ */
+export declare function serializeHistoryList(entries: readonly string[]): string;
 /**
  * Build the recall space, newest first: local entries, then persistent
  * entries whose text is not duplicated locally (the local copy wins and the

package/lib/types/index.d.ts

@@ -10,6 +10,8 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
+import type { TuiStartup } from './startup.ts';
 /** Stable Cordis plugin name. */
 export declare const name = "tui-runner";
 /** Core services required before the interactive session can start. */
@@ -21,12 +23,59 @@ export interface Config {
         kind: string;
         sessionId?: string;
         mode?: string;
+        theme?: string;
     };
 }
 export declare const Config: z<Config>;
+/** The session identity this invocation will run, plus whether it is resumed. */
+interface Target {
+    sessionId: string;
+    resume: boolean;
+    mode?: string;
+    cwd?: string;
+}
+/**
+ * Reduce a session id to a filename-safe /export default-name suffix. Session
+ * ids are normally minted `session-<uuid>`, but `--session` accepts arbitrary
+ * user text: path separators must never leak into the default export filename
+ * (which would escape the session cwd).
+ * @param id - the session id.
+ * @returns at most the last 8 filename-safe characters.
+ */
+export declare function exportSessionIdSuffix(id: string): string;
+/** One ordered step of the terminal quit cleanup. */
+export interface QuitCleanupStep {
+    /** Step label used in diagnostics and tests. */
+    readonly name: string;
+    /** The step's async work; a rejection is contained by the sequence. */
+    readonly run: () => Promise<void>;
+}
+/**
+ * Run the ordered quit cleanup, then request exit. Every step rejection is
+ * contained (reported through `onError`) so a failed flush or dispose never
+ * skips the remaining cleanup; the exit request is always reached exactly
+ * once.
+ * @param steps - the cleanup steps in dependency order (settle the visible
+ * session, await the final in-flight composition, await durable recall).
+ * @param exit - the terminal exit request (code 0).
+ * @param onError - optional failure sink; called once per failing step and
+ * itself contained, so a throwing sink cannot abort the sequence.
+ * @returns the names of the steps that started, in order (for tests).
+ */
+export declare function runQuitSequence(steps: readonly QuitCleanupStep[], exit: (code: number) => void, onError?: (name: string, error: unknown) => void): Promise<readonly string[]>;
+/**
+ * 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.
+ */
+export declare function resolveTarget(startup: TuiStartup, persistence: SessionPersistence | undefined, cwd: string): Promise<Target>;
 /**
  * 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.
  */
 export declare function apply(ctx: Context, config: Config): void;
+export {};

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

@@ -1,5 +1,7 @@
 /** Bounded, composer-safe panels for preset, session, and plugin kernel views. */
 import { type ReactElement } from 'react';
+import type { ModelRow } from './models.ts';
+import type { PermissionRow } from './permissions.ts';
 import type { PresetRow } from './presets.ts';
 import type { PluginRow } from './plugin-inventory.ts';
 import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
@@ -10,6 +12,12 @@ export declare function ModePanel({ current, load, select, close }: {
     select(id: string): void;
     close(): void;
 }): ReactElement;
+export declare function PermissionPanel({ current, load, select, close }: {
+    current: string;
+    load(): Promise<readonly PermissionRow[]>;
+    select(id: string): void;
+    close(): void;
+}): ReactElement;
 export declare function PluginPanel({ load, close, initialQuery }: {
     load(): readonly PluginRow[];
     close(): void;
@@ -46,3 +54,23 @@ export declare function StatuslinePanel({ enabled, change, close }: {
     change(items: readonly StatusItemId[]): void;
     close(): void;
 }): ReactElement;
+/**
+ * The `/model` reasoning-effort stage (the Codex model → reasoning popup
+ * contract): one bounded list over the selected model's adapter-advertised
+ * effort levels, with the effective effort and the model default marked.
+ * A model WITHOUT an adapter-declared default leads with a "Default"
+ * (provider-default) row — the web effort pane's first entry — so the user
+ * can clear a picked level back to provider behavior instead of being forced
+ * to choose an advertised one. Enter applies one level; Esc returns to the
+ * model list without applying.
+ */
+export declare function EffortPanel({ row, current, select, back }: {
+    /** The model row whose advertised levels this stage lists. */
+    row: ModelRow;
+    /** Effective effort currently in force ('' when none), for the ● mark. */
+    current: string | undefined;
+    /** Accept one advertised effort id, or '' for the provider default. */
+    select(effortId: string): void;
+    /** Return to the model list without applying. */
+    back(): void;
+}): ReactElement;

package/lib/types/mentions.d.ts

@@ -1,12 +1,17 @@
 /**
- * Workspace @mention support: file candidates from a bounded async scan of
- * the session cwd, session candidates from the opt-in `sessionReferenceResolver`
- * service, and submission preparation through its `prepare()` API. Picked
- * session mentions land as canonical `@[label](dsh-session:…)` tokens; on
- * submit the text is parsed back into readable `@label` text plus structured
- * references, snapshots are injected via `agent.inject()` before the readable
- * message wakes the driver (`followup` idle, `steer` running) — exactly the
- * upstream README's wiring.
+ * Workspace @mention support: file and directory candidates from a bounded
+ * async scan of the session cwd, session candidates from the opt-in
+ * `sessionReferenceResolver` service, and submission preparation through its
+ * `prepare()` API. Picked session mentions land as canonical
+ * `@[label](dsh-session:…)` tokens; on submit the text is parsed back into
+ * readable `@label` text plus structured references, snapshots are injected
+ * via `agent.inject()` before the readable message wakes the driver
+ * (`followup` idle, `steer` running) — exactly the upstream README's wiring.
+ *
+ * Harness exposes no workspace-file mention service (only session references
+ * plus a post-hoc produced-file linker), so the file index is the lightweight
+ * bounded scan below, kept deliberately smaller than Codex's streaming
+ * gitignore-aware walker.
  *
  * @module @deepseek-ai/dsh-code/mentions
  */
@@ -40,11 +45,17 @@ export interface PreparedMention {
     /** Aggregated snapshot for `agent.inject()`, undefined without references. */
     additionalContext?: import('@deepseek-ai/dsh-session').UserMessage;
 }
-/** Bounded async BFS scan of a workspace; unreadable entries are skipped. */
+/**
+ * Bounded async BFS scan of a workspace; unreadable entries are skipped.
+ * Both files and directories are indexed (directories insert with a trailing
+ * slash), mirroring Codex's `MatchType::{File,Directory}` index. Dotfiles and
+ * the {@link SKIP_DIRS} list are excluded, which is a coarser filter than
+ * Codex's gitignore-aware walker but stays dependency-free and bounded.
+ */
 export declare function scanWorkspaceFiles(root: string, signal?: AbortSignal): Promise<readonly FileCandidate[]>;
 /** The mention API the input editor and the runner share. */
 export interface MentionsApi {
-    /** Scanned workspace files, cached across one session. */
+    /** Scanned workspace files and directories, cached across one session. */
     files(): Promise<readonly FileCandidate[]>;
     /** Ranked menu candidates for the typed `@` query. */
     candidates(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]>;
@@ -61,10 +72,16 @@ export interface MentionsApi {
 /**
  * Create the mention API for one agent's workspace. A missing
  * session-reference service degrades to file mentions only (the scan still
- * works); `prepare` then passes text through untouched.
+ * works); `prepare` then passes text through untouched. An undefined agent
+ * (a bare launch before any session exists) also degrades to file-only
+ * mentions, so `@` file completion works before the first message.
+ *
+ * `files` is hoisted into the closure so `candidates` never reaches for
+ * `this` — the runner hands `mentions.candidates` to the input editor as a
+ * detached callback, and a `this`-bound method would throw on every `@` key.
  * @param ctx - context carrying the optional `sessionReferenceResolver`.
  * @param agent - the session owner; excluded from its own candidates.
  * @param cwd - workspace root to scan.
  */
-export declare function createMentions(ctx: Context, agent: Agent, cwd: string): MentionsApi;
+export declare function createMentions(ctx: Context, agent: Agent | undefined, cwd: string): MentionsApi;
 export {};

package/lib/types/models.d.ts

@@ -8,6 +8,24 @@
  * @module @deepseek-ai/dsh-tui/models
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { ModelSelection } from '@deepseek-ai/dsh-agent';
+import { type LlmModelReasoningInfo } from '@deepseek-ai/dsh-llm';
+/** Display metadata for one adapter-owned reasoning effort (mirrors `LlmReasoningEffortInfo`). */
+export interface ModelReasoningEffort {
+    /** Opaque value accepted by the model's `GenerateOptions.reasoningEffort`. */
+    id: string;
+    /** Human-readable effort name for selectors. */
+    name: string;
+    /** Optional user-facing distinction from otherwise similar efforts. */
+    description?: string;
+}
+/** Selectable reasoning efforts for one model (mirrors `LlmModelReasoningInfo`). */
+export interface ModelReasoning {
+    /** Supported efforts in adapter-preferred display order. */
+    efforts: readonly ModelReasoningEffort[];
+    /** Adapter-configured default materialized when callers omit an effort. */
+    defaultEffort?: string;
+}
 /** One selectable row in the `/model` panel. */
 export interface ModelRow {
     /** Registered provider route. */
@@ -18,6 +36,8 @@ export interface ModelRow {
     model: string;
     /** Human-readable model name. */
     modelName: string;
+    /** Adapter-owned selectable reasoning levels when the model exposes any. */
+    reasoning?: ModelReasoning;
 }
 /** The resolved directory: rows plus per-provider discovery failures. */
 export interface ModelDirectory {
@@ -25,12 +45,58 @@ export interface ModelDirectory {
     rows: readonly ModelRow[];
     /** Provider ids whose model listing failed; those providers contribute no rows. */
     failures: readonly string[];
+    /**
+     * `provider/model` labels whose per-model capability lookup failed. Those
+     * rows still appear (advisory degrade, mirroring the web catalog), but
+     * without an effort picker — a picker caller must not misread the absence
+     * as "this model exposes no reasoning" (e.g. deepseek-v4-flash always
+     * advertises off/high/max unless thinking is disabled). Optional for
+     * callers that shape a directory by hand; {@link loadModelDirectory}
+     * always populates it (empty when nothing failed).
+     */
+    reasoningFailures?: readonly string[];
 }
+/** Map an adapter's reasoning capability onto the panel's plain-id shape. */
+export declare function mapReasoning(reasoning: LlmModelReasoningInfo): ModelReasoning;
+/**
+ * Resolve the effective model selection for one live session, in the
+ * documented precedence: the in-process explicit pick, then the session's
+ * last `request/header` config, then the deployment default.
+ * @param picked - the explicit selection made in this process, when any.
+ * @param logged - the last logged request header config, when any.
+ * @param defaults - the deployment default selection.
+ * @returns the effective selection, carrying a reasoning effort when one is in force.
+ */
+export declare function resolveEffectiveSelection(picked: ModelSelection | undefined, logged: {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+} | undefined, defaults: ModelSelection): ModelSelection;
+/**
+ * Build the selection one `/model` pick applies, rejecting an effort the
+ * row does not advertise. The row is the picker's source of truth, so a
+ * stale directory cannot smuggle an unsupported effort into the next step
+ * (the request pipeline would reject it before network I/O regardless). The
+ * empty string is the picker's "provider default" sentinel — an explicit
+ * choice to leave the effort to the model's own default, exactly like an
+ * absent effort.
+ * @param row - the picked model row.
+ * @param effortId - the chosen advertised effort, '' or undefined for the model default.
+ * @returns the selection the runner records for the next assembled step.
+ */
+export declare function buildModelSelection(row: ModelRow, effortId?: string): ModelSelection;
+/** Display label for one applied selection: `provider/model` or `provider/model@effort`. */
+export declare function modelSelectionLabel(selection: ModelSelection): string;
 /**
  * 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).
+ * Each row's reasoning levels are resolved per exact model like the web
+ * catalog (`buildModelCatalog`); a single model's capability lookup failure
+ * degrades to that row having no effort picker rather than hiding the model,
+ * and the failure rides `reasoningFailures` so the caller can tell "no
+ * advertised reasoning" from "capability lookup failed".
  * @param ctx - context carrying the `llm` service.
  * @returns the resolved directory; empty rows when `llm` is unavailable.
  */

package/lib/types/permissions.d.ts

@@ -0,0 +1,37 @@
+/** Permission-preset policy for pending and active TUI sessions. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+/** One selectable permission preset row for the /permission panel. */
+export interface PermissionRow {
+    readonly id: string;
+    readonly description?: string;
+}
+/** Structural boundary over Harness permission presets; values stay service-owned. */
+export interface PermissionPresetsService {
+    readonly names: readonly string[];
+    readonly defaultPreset: string;
+    resolve(name: string): unknown;
+    current(events: readonly SessionEvent[]): string;
+    set(session: Session, preset: string): void;
+    /** Client presentation metadata for one preset; may reject unknown names. */
+    optionOf?(name: string): {
+        name: string;
+        description?: string;
+    } | undefined;
+}
+/** Read the optional Harness service without importing its runtime package. */
+export declare function permissionPresetsFrom(ctx: Context): PermissionPresetsService | undefined;
+/** Effective label for either an active session or the not-yet-created first one. */
+export declare function effectivePermission(service: PermissionPresetsService, session: Session | undefined, pending: string | undefined): string;
+/** Validate a preset and write it only when a durable session already exists. */
+export declare function selectPermission(service: PermissionPresetsService, session: Session | undefined, preset: string): string;
+/** Cycle table order from the active, pending, or configured-default value. */
+export declare function cyclePermission(service: PermissionPresetsService, session: Session | undefined, pending: string | undefined): string;
+/** Materialize a pre-session choice after Harness creates the first session. */
+export declare function applyPendingPermission(service: PermissionPresetsService, session: Session, pending: string | undefined): void;
+/**
+ * List every switchable preset for the /permission panel, table order kept.
+ * Description lookup failures degrade to an undocumented row, never a failed
+ * panel load — `optionOf` rejects names its table no longer knows.
+ */
+export declare function listPermissionRows(service: PermissionPresetsService): readonly PermissionRow[];

package/lib/types/presets.d.ts

@@ -26,6 +26,8 @@ export declare function agentPresetsFrom(ctx: Context): AgentPresetsService | un
 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;
+/** Resolve a pre-session choice, or recompose an active blank Agent. */
+export declare function selectPreset(service: AgentPresetsService, agent: Agent | undefined, presetId: string): Promise<PresetRow>;
 /** 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. */