@fonlan/dsh-quick-commands 0.1.0

package/src/server/runner.ts

@@ -0,0 +1,471 @@
+/**
+ * Quick-command execution engine.
+ *
+ * Owns one subprocess per run (serial per workspace id), keeps bounded
+ * in-memory output tails with offset-based readers for incremental client
+ * polls, resolves the {workspace}/{cwd}/{title} placeholders against the
+ * session-bound execution context, and terminates the whole process tree on
+ * kill / popup close.
+ *
+ * Two backends:
+ *   - local: DSH's `subprocess` service (`bash -c`/`pwsh -c`, workspace cwd).
+ *   - remote: when the workspace path is a dsh-ssh placeholder directory and
+ *     the `sshPool` service is present, the command streams over SSH with the
+ *     workspace's remote path as cwd. The client-visible behaviour (tail +
+ *     offset polls) is identical for both backends.
+ */
+import { randomUUID } from 'node:crypto'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import type { QuickCommandsSettings } from '../shared/contract.js'
+import {
+  localPathToRemoteRef,
+  resolveRemoteCwd,
+  RemoteStreamExecutor,
+  type SshPoolLike,
+} from './remote.js'
+
+/** Bounded in-memory tail window per output stream (bytes). */
+const TAIL_MAX_BYTES = 256 * 1024
+
+/** Optional SSH backend (duck-typed over the @dsh-ssh/dsh-ssh plugin). */
+export interface RemoteBackend {
+  pool: SshPoolLike
+  /** Resolve one hostId to its connection config (settings `dsh-ssh-hosts`). */
+  resolveHost: (hostId: string) => { id: string; [key: string]: unknown } | undefined
+}
+
+/** Lazily-resolved SSH backend: resolved per run, so load order is irrelevant. */
+export type RemoteBackendResolver = () => RemoteBackend | undefined
+
+/** One live process entry owned by the runner. */
+interface LiveRun {
+  runId: string
+  workspaceId: string
+  commandName: string
+  /** Command line after placeholder substitution (display currency). */
+  resolvedCommand: string
+  /** Execution kind (also selects the kill strategy). */
+  kind: 'local' | 'remote'
+  handle: SubprocessHandle | RemoteStreamExecutor
+  /** Whole-stream byte counters (offset currency for delta reads). */
+  stdoutBytes: number
+  stderrBytes: number
+  /** In-memory tail windows (keep the TAIL on overflow). */
+  stdoutTail: string
+  stderrTail: string
+  /** Thrown when the tail was clipped (lossy reads report it). */
+  stdoutClipped: boolean
+  stderrClipped: boolean
+  /** Terminal exit facts; present once the process closed. */
+  outcome: { exitCode: number | null; signal: string | null } | null
+  /** True when kill was requested but the stream has not settled yet. */
+  killRequested: boolean
+  startedAt: number
+}
+
+/** A snapshot reader over one run's captured output (delta + offsets). */
+export interface RunPollResult {
+  kind: 'poll'
+  status: 'running' | 'exited'
+  exitCode: number | null
+  signal: string | null
+  stdoutEnd: number
+  stderrEnd: number
+  stdoutDelta: string
+  stderrDelta: string
+  stdoutLossy: boolean
+  stderrLossy: boolean
+}
+
+/** The runner's exported operations. */
+export interface QuickRunner {
+  /**
+   * Start one command for a workspace (serial: rejects when one is live).
+   * Async: a remote run acquires its SSH connection before returning.
+   */
+  start(input: {
+    workspaceId: string
+    workspacePath: string
+    workspaceTitle: string
+    commandName: string
+    command: string
+    sessionCwd: string
+    popupAnchor: QuickCommandsSettings['popupAnchor']
+  }): Promise<{ ok: true; runId: string; remoteHost?: string; resolvedCommand: string } | { ok: false; error: string }>
+  /** Read output deltas since the caller's offsets. */
+  poll(runId: string, stdoutFrom: number, stderrFrom: number): RunPollResult | null
+  /** Terminate the live process tree (idempotent). */
+  kill(runId: string): 'ok' | 'not-found' | 'already-exited'
+  /** List live runs for the workspace (for reattach / run list). */
+  forWorkspace(workspaceId: string): Array<{ runId: string; commandName: string; startedAt: number; status: 'running' | 'exited' }>
+}
+
+/** Substitute supported placeholders in the command string. */
+export function resolvePlaceholders(command: string, vars: {
+  workspace: string
+  cwd: string
+  title: string
+}): string {
+  return command
+    .replaceAll('{workspace}', vars.workspace)
+    .replaceAll('{cwd}', vars.cwd)
+    .replaceAll('{title}', vars.title)
+}
+
+/** Pick the shell executable for the current platform. */
+export function shellCmd(): string {
+  return process.platform === 'win32' ? 'pwsh' : 'bash'
+}
+
+/** Pick the `-c` inclusive switch for the current platform. */
+export function shellFlag(): '-c' {
+  return '-c'
+}
+
+interface SubprocessServiceLike {
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+}
+
+export class QuickCommandRunner implements QuickRunner {
+  private readonly runs = new Map<string, LiveRun>()
+  private readonly liveByWorkspace = new Map<string, string>()
+
+  constructor(
+    private readonly subprocess: SubprocessServiceLike,
+    private readonly resolveRemote?: RemoteBackendResolver,
+  ) {}
+
+  /** Resolve the remote reference lazily so SSH availability is re-checked per run. */
+  private resolveRemoteBackend(): RemoteBackend | undefined {
+    try {
+      return this.resolveRemote?.()
+    } catch {
+      return undefined
+    }
+  }
+
+  async start(input: {
+    workspaceId: string
+    workspacePath: string
+    workspaceTitle: string
+    commandName: string
+    command: string
+    sessionCwd: string
+    popupAnchor: QuickCommandsSettings['popupAnchor']
+  }): Promise<{ ok: true; runId: string; remoteHost?: string; resolvedCommand: string } | { ok: false; error: string }> {
+    const liveId = this.liveByWorkspace.get(input.workspaceId)
+    if (liveId !== undefined) {
+      const live = this.runs.get(liveId)
+      if (live !== undefined && live.outcome === null) {
+        return { ok: false, error: `a command is already running for this workspace (${live.commandName})` }
+      }
+      this.liveByWorkspace.delete(input.workspaceId)
+    }
+
+    // Workspace path is a dsh-ssh placeholder → remote execution.
+    const ref = localPathToRemoteRef(input.workspacePath)
+    if (ref !== null) {
+      const backend = this.resolveRemoteBackend()
+      if (backend === undefined) {
+        return {
+          ok: false,
+          error: `workspace ${input.workspaceId} is an SSH remote workspace (host ${ref.hostId}), but the @dsh-ssh/dsh-ssh plugin (sshPool service) is not loaded`,
+        }
+      }
+      return this.startRemote(input, ref.hostId, ref.remotePath, backend)
+    }
+
+    return this.startLocal(input)
+  }
+
+  private async startLocal(input: {
+    workspaceId: string
+    workspacePath: string
+    workspaceTitle: string
+    commandName: string
+    command: string
+    sessionCwd: string
+    popupAnchor: QuickCommandsSettings['popupAnchor']
+  }): Promise<{ ok: true; runId: string; resolvedCommand: string }> {
+    const resolved = resolvePlaceholders(input.command, {
+      workspace: input.workspacePath,
+      cwd: input.sessionCwd,
+      title: input.workspaceTitle,
+    })
+
+    const runId = randomUUID()
+    const handle = this.subprocess.spawn({
+      argv: [shellCmd(), shellFlag(), resolved],
+      cwd: input.workspacePath,
+      graceMs: 3000,
+      stdio: {
+        stdin: 'ignore',
+        stdout: { maxBytes: TAIL_MAX_BYTES },
+        stderr: { maxBytes: TAIL_MAX_BYTES },
+      },
+      env: {
+        ...process.env,
+        DSH_WORKSPACE: input.workspacePath,
+        DSH_WORKSPACE_ID: input.workspaceId,
+        DSH_WORKSPACE_TITLE: input.workspaceTitle,
+      },
+    })
+
+    const live: LiveRun = {
+      runId,
+      workspaceId: input.workspaceId,
+      commandName: input.commandName,
+      resolvedCommand: resolved,
+      kind: 'local',
+      handle,
+      stdoutBytes: 0,
+      stderrBytes: 0,
+      stdoutTail: '',
+      stderrTail: '',
+      stdoutClipped: false,
+      stderrClipped: false,
+      outcome: null,
+      killRequested: false,
+      startedAt: Date.now(),
+    }
+    this.runs.set(runId, live)
+    this.liveByWorkspace.set(input.workspaceId, runId)
+
+    // Collect stdout deltas as they arrive (offset-based; reader sees the tail).
+    const stdoutReader = handle.collected?.stdout
+    const stderrReader = handle.collected?.stderr
+    const drain = (): void => {
+      if (stdoutReader !== undefined) {
+        const read = stdoutReader.readFrom(live.stdoutBytes)
+        live.stdoutBytes = read.nextOffset
+        live.stdoutTail += read.text
+        if (live.stdoutTail.length > TAIL_MAX_BYTES) {
+          live.stdoutTail = live.stdoutTail.slice(-TAIL_MAX_BYTES)
+          live.stdoutClipped = true
+        }
+      }
+      if (stderrReader !== undefined) {
+        const read = stderrReader.readFrom(live.stderrBytes)
+        live.stderrBytes = read.nextOffset
+        live.stderrTail += read.text
+        if (live.stderrTail.length > TAIL_MAX_BYTES) {
+          live.stderrTail = live.stderrTail.slice(-TAIL_MAX_BYTES)
+          live.stderrClipped = true
+        }
+      }
+    }
+    // Read on a short cadence while live; final drain at exit.
+    const interval = setInterval(drain, 150)
+    void handle.done.then((outcome) => {
+      clearInterval(interval)
+      drain()
+      live.outcome = { exitCode: outcome.exitCode, signal: outcome.signal }
+    }).catch(() => {
+      clearInterval(interval)
+      live.outcome = { exitCode: null, signal: null }
+    })
+
+    return { ok: true, runId, resolvedCommand: resolved }
+  }
+
+  private async startRemote(
+    input: {
+      workspaceId: string
+      workspacePath: string
+      workspaceTitle: string
+      commandName: string
+      command: string
+      sessionCwd: string
+      popupAnchor: QuickCommandsSettings['popupAnchor']
+    },
+    hostId: string,
+    remotePath: string,
+    backend: RemoteBackend,
+  ): Promise<{ ok: true; runId: string; remoteHost?: string; resolvedCommand: string } | { ok: false; error: string }> {
+    const cfg = backend.resolveHost(hostId)
+    if (cfg === undefined) {
+      return {
+        ok: false,
+        error: `remote host ${hostId} is not configured in dsh-ssh-hosts — add it in Settings → SSH hosts`,
+      }
+    }
+
+    let conn
+    try {
+      conn = await backend.pool.acquire(cfg)
+    } catch (error) {
+      const e = error as { stage?: string; message?: string }
+      return {
+        ok: false,
+        error: `ssh connect to host ${hostId} failed: ${e?.message ?? String(error)}`
+          + (e?.stage ? ` (stage: ${e.stage})` : ''),
+      }
+    }
+
+    // Remote placeholder substitution: {workspace}/{cwd} are remote paths; the
+    // session cwd is re-anchored onto the remote filesystem when it sits inside
+    // the placeholder workspace.
+    const remoteCwd = resolveRemoteCwd(input.sessionCwd, input.workspacePath, remotePath)
+    const resolved = resolvePlaceholders(input.command, {
+      workspace: remotePath,
+      cwd: remoteCwd,
+      title: input.workspaceTitle,
+    })
+
+    const runId = randomUUID()
+    const executor = new RemoteStreamExecutor(conn, backend.pool)
+    const live: LiveRun = {
+      runId,
+      workspaceId: input.workspaceId,
+      commandName: input.commandName,
+      resolvedCommand: resolved,
+      kind: 'remote',
+      handle: executor,
+      stdoutBytes: 0,
+      stderrBytes: 0,
+      stdoutTail: '',
+      stderrTail: '',
+      stdoutClipped: false,
+      stderrClipped: false,
+      outcome: null,
+      killRequested: false,
+      startedAt: Date.now(),
+    }
+    this.runs.set(runId, live)
+    this.liveByWorkspace.set(input.workspaceId, runId)
+
+    const append = (stream: 'stdout' | 'stderr', text: string): void => {
+      if (stream === 'stdout') {
+        live.stdoutBytes += Buffer.byteLength(text, 'utf8')
+        live.stdoutTail += text
+        if (live.stdoutTail.length > TAIL_MAX_BYTES) {
+          live.stdoutTail = live.stdoutTail.slice(-TAIL_MAX_BYTES)
+          live.stdoutClipped = true
+        }
+      } else {
+        live.stderrBytes += Buffer.byteLength(text, 'utf8')
+        live.stderrTail += text
+        if (live.stderrTail.length > TAIL_MAX_BYTES) {
+          live.stderrTail = live.stderrTail.slice(-TAIL_MAX_BYTES)
+          live.stderrClipped = true
+        }
+      }
+    }
+
+    void executor.start(
+      resolved,
+      remoteCwd,
+      append,
+      (exit) => {
+        if (exit.error !== undefined && exit.error !== '') {
+          append('stderr', `\n[ssh] ${exit.error}\n`)
+        }
+        live.outcome = {
+          exitCode: exit.exitCode,
+          signal: live.killRequested ? 'TERM' : exit.signal,
+        }
+        backend.pool.release()
+      },
+    )
+
+    return { ok: true, runId, remoteHost: hostId, resolvedCommand: resolved }
+  }
+
+  poll(runId: string, stdoutFrom: number, stderrFrom: number): RunPollResult | null {
+    const live = this.runs.get(runId)
+    if (live === undefined) return null
+
+    // Drain pending tail first so the poll sees the freshest state.
+    if (live.kind === 'local') {
+      const handle = live.handle as SubprocessHandle
+      const stdoutReader = handle.collected?.stdout
+      const stderrReader = handle.collected?.stderr
+      if (stdoutReader !== undefined) {
+        const read = stdoutReader.readFrom(live.stdoutBytes)
+        live.stdoutBytes = read.nextOffset
+        live.stdoutTail += read.text
+        if (live.stdoutTail.length > TAIL_MAX_BYTES) {
+          live.stdoutTail = live.stdoutTail.slice(-TAIL_MAX_BYTES)
+          live.stdoutClipped = true
+        }
+      }
+      if (stderrReader !== undefined) {
+        const read = stderrReader.readFrom(live.stderrBytes)
+        live.stderrBytes = read.nextOffset
+        live.stderrTail += read.text
+        if (live.stderrTail.length > TAIL_MAX_BYTES) {
+          live.stderrTail = live.stderrTail.slice(-TAIL_MAX_BYTES)
+          live.stderrClipped = true
+        }
+      }
+    }
+
+    // Delta from the caller's offset; lossy when the offset slid out of the tail.
+    let stdoutDelta = live.stdoutTail
+    let stdoutLossy = live.stdoutClipped
+    if (stdoutFrom > 0 && stdoutFrom <= live.stdoutBytes) {
+      const tailStart = live.stdoutBytes - live.stdoutTail.length
+      if (stdoutFrom < tailStart) {
+        stdoutLossy = true
+      } else {
+        stdoutDelta = live.stdoutTail.slice(stdoutFrom - tailStart)
+      }
+    }
+    let stderrDelta = live.stderrTail
+    let stderrLossy = live.stderrClipped
+    if (stderrFrom > 0 && stderrFrom <= live.stderrBytes) {
+      const tailStart = live.stderrBytes - live.stderrTail.length
+      if (stderrFrom < tailStart) {
+        stderrLossy = true
+      } else {
+        stderrDelta = live.stderrTail.slice(stderrFrom - tailStart)
+      }
+    }
+
+    const exited = live.outcome !== null
+    return {
+      kind: 'poll',
+      status: exited ? 'exited' : 'running',
+      exitCode: exited ? live.outcome!.exitCode : null,
+      signal: exited ? live.outcome!.signal : null,
+      stdoutEnd: live.stdoutBytes,
+      stderrEnd: live.stderrBytes,
+      stdoutDelta,
+      stderrDelta,
+      stdoutLossy,
+      stderrLossy,
+    }
+  }
+
+  kill(runId: string): 'ok' | 'not-found' | 'already-exited' {
+    const live = this.runs.get(runId)
+    if (live === undefined) return 'not-found'
+    if (live.outcome !== null) return 'already-exited'
+    if (live.kind === 'local') {
+      // Tree-scoped termination: SIGTERM → grace → SIGKILL escalation.
+      void (live.handle as SubprocessHandle).terminate()
+    } else {
+      live.killRequested = true
+      void (live.handle as RemoteStreamExecutor).kill()
+    }
+    return 'ok'
+  }
+
+  forWorkspace(workspaceId: string): Array<{ runId: string; commandName: string; startedAt: number; status: 'running' | 'exited' }> {
+    const ids = this.liveByWorkspace.get(workspaceId)
+    if (ids === undefined) return []
+    const live = this.runs.get(ids)
+    if (live === undefined) return []
+    return [{
+      runId: live.runId,
+      commandName: live.commandName,
+      startedAt: live.startedAt,
+      status: live.outcome === null ? 'running' : 'exited',
+    }]
+  }
+
+  /** Every live run id (terminal and running) for fiber cleanup. */
+  listAll(): string[] {
+    return [...this.runs.keys()]
+  }
+}

package/src/server/settings.ts

@@ -0,0 +1,106 @@
+/**
+ * User-facing plugin settings (per-workspace command sets + popup anchor),
+ * persisted through the settings service namespace `quick-commands`.
+ * The DSH settings service requires a lowercase kebab-case namespace
+ * (/^[a-z][a-z0-9-]*$/), so the scoped package name cannot be used here.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { QuickCommandsSettings, QuickCommandEntry, QuickPopupSize, WorkspaceCommands } from '../shared/contract.js'
+
+export const QUICK_COMMANDS_NS = settingsNamespace('quick-commands')
+
+/**
+ * One command entry schema. name/command may be EMPTY: the settings card edits
+ * rows field-by-field (instant save per keystroke), so a partially-typed row
+ * is a legitimate persisted state. Runnable validation happens at run.start.
+ */
+const CommandSchema = z.object({
+  name: z.string(),
+  command: z.string(),
+})
+
+/** One workspace command set. */
+const WorkspaceCommandsSchema = z.object({
+  workspaceId: z.string().min(1),
+  commands: z.array(CommandSchema).max(200),
+})
+
+export const QuickCommandsSettingsSchema: z<QuickCommandsSettings> = z.object({
+  workspaces: z.array(WorkspaceCommandsSchema).max(500),
+  popupAnchor: z.union([z.const('corner'), z.const('button')]).default('corner'),
+  // No default on purpose: a missing popupSize stays ABSENT in the resolved
+  // document, so the client can distinguish "never resized" (per-anchor
+  // default size) from a user-chosen size.
+  popupSize: z.object({
+    width: z.number().min(320).max(8192),
+    height: z.number().min(200).max(8192),
+  }),
+})
+
+const DEFAULT_SETTINGS: QuickCommandsSettings = {
+  workspaces: [],
+  popupAnchor: 'corner',
+}
+
+/** Structural settings-service subset; the real service resolves the schema. */
+interface SettingsServiceLike {
+  register(ns: unknown, schema: unknown): unknown
+  update(ns: unknown, patch: Record<string, unknown>, expectedRevision?: number): Promise<unknown>
+  mutate?(ns: unknown, ops: readonly unknown[], expectedRevision?: number): Promise<unknown>
+}
+
+/** Settings service face for the quick-commands engine. */
+export interface QuickCommandsSettingsFace {
+  get(): QuickCommandsSettings
+  /** Read the command set bound to one workspace id. */
+  commandsOf(workspaceId: string): QuickCommandEntry[]
+  /** Replace the whole command set for one workspace id (instant-save). */
+  setCommands(workspaceId: string, commands: QuickCommandEntry[]): Promise<void>
+  /** Set the popup anchor preference. */
+  setAnchor(anchor: QuickCommandsSettings['popupAnchor']): Promise<void>
+  /** Persist the output popup size (drag-resize). */
+  setPopupSize(size: QuickPopupSize): Promise<void>
+}
+
+export function registerSettings(ctx: Context): QuickCommandsSettingsFace {
+  let current: QuickCommandsSettings = { ...DEFAULT_SETTINGS, workspaces: [] }
+  let service: SettingsServiceLike | undefined
+
+  ctx.inject(['settings'], (sctx) => {
+    service = sctx.settings as unknown as SettingsServiceLike
+    const scope = service.register(QUICK_COMMANDS_NS, QuickCommandsSettingsSchema) as {
+      get(): QuickCommandsSettings
+      watch(callback: (next: QuickCommandsSettings) => void): () => void
+    }
+    current = scope.get()
+    scope.watch((next) => { current = next })
+  })
+
+  async function persist(patch: Record<string, unknown>): Promise<void> {
+    if (service === undefined) {
+      throw new Error('@fonlan/dsh-quick-commands: settings service is not available in this profile')
+    }
+    await service.update(QUICK_COMMANDS_NS, patch)
+  }
+
+  return {
+    get: () => current,
+    commandsOf: (workspaceId) => {
+      const set = current.workspaces.find((w) => w.workspaceId === workspaceId)
+      return set === undefined ? [] : set.commands
+    },
+    setCommands: async (workspaceId, commands) => {
+      const next: WorkspaceCommands[] = current.workspaces.filter((w) => w.workspaceId !== workspaceId)
+      if (commands.length > 0) next.push({ workspaceId, commands })
+      await persist({ workspaces: next })
+    },
+    setAnchor: async (anchor) => {
+      await persist({ popupAnchor: anchor })
+    },
+    setPopupSize: async (size) => {
+      await persist({ popupSize: size })
+    },
+  }
+}

package/src/shared/contract.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared wire contracts for @fonlan/dsh-quick-commands.
+ *
+ * Browser-safe: no host-only imports live here. The client bundle imports
+ * these shapes (type-only + runtime constants), so anything that must cross
+ * the fenced JSON API keeps its plain-Object shape here.
+ */
+
+/** One configured quick command inside a workspace. */
+export interface QuickCommandEntry {
+  /** Human-facing command name (unique within the workspace). */
+  name: string
+  /** Shell command line, executed through bash -c / pwsh -c. */
+  command: string
+}
+
+/** Config slice bound to one workspace (keyed by workspaceId). */
+export interface WorkspaceCommands {
+  /** DSH workspace registry id this command set belongs to. */
+  workspaceId: string
+  /** Ordered command entries. */
+  commands: QuickCommandEntry[]
+}
+
+/** Output popup dimensions in CSS pixels (user drag-resize state). */
+export interface QuickPopupSize {
+  width: number
+  height: number
+}
+
+/** Full user-facing plugin settings document (settings namespace value). */
+export interface QuickCommandsSettings {
+  /** Command sets; a workspace may be absent (no commands configured). */
+  workspaces: WorkspaceCommands[]
+  /** Output popup anchor preference: fixed bottom-right or anchored at the button. */
+  popupAnchor: 'corner' | 'button'
+  /** Output popup size; absent until the user drags the resize handle (then per-anchor defaults apply). */
+  popupSize?: QuickPopupSize
+}
+
+/** Placeholder substitution values resolved for one execution. */
+export interface QuickRunPlaceholders {
+  /** Workspace root path (also the execution cwd). */
+  workspace: string
+  /** Session actual cwd (may be a subdirectory of the workspace). */
+  cwd: string
+  /** Workspace display title. */
+  title: string
+}
+
+/** One live run view returned by `run.start`. */
+export interface QuickRunView {
+  runId: string
+  workspaceId: string
+  commandName: string
+  /** Command line after placeholder substitution (display only). */
+  resolvedCommand: string
+  /** Non-empty when the command executes over SSH on a remote workspace host. */
+  remoteHost?: string
+  status: 'running' | 'exited'
+  exitCode: number | null
+  signal: string | null
+  startedAt: number
+  /** Total stdout bytes captured so far (offset currency). */
+  stdoutEnd: number
+  /** Total stderr bytes captured so far (offset currency). */
+  stderrEnd: number
+  /** stdout tail appended since `stdoutFrom` (whole tail when lossy). */
+  stdoutDelta: string
+  /** stderr tail appended since `stderrFrom` (whole tail when lossy). */
+  stderrDelta: string
+  /** True when the in-memory tail lost its head for this stream. */
+  stdoutLossy: boolean
+  stderrLossy: boolean
+}
+
+/** API response envelope (mirrors task-kanban's fenced fetch wrapper). */
+export interface ApiEnvelope<T> {
+  ok: boolean
+  value?: T
+  error?: { code: string; message: string }
+}
+
+/** Settings card view: command sets plus the workspace roster for display. */
+export interface QuickRosterEntry {
+  workspaceId: string
+  path: string
+  title: string
+  /** SSH host id when the workspace runs remotely through dsh-ssh (else absent). */
+  remoteHost?: string
+  commands: QuickCommandEntry[]
+}