ethagent 0.2.0 → 1.0.0

package/src/chat/commands.ts

@@ -0,0 +1,673 @@
+import type { EthagentConfig, ProviderId } from '../storage/config.js'
+import { getConfigPath, localProviderBaseUrlFor, saveConfig } from '../storage/config.js'
+import { detectLlamaCpp } from '../models/llamacpp.js'
+import { detectSpec } from '../models/runtimeDetection.js'
+import { hasKey } from '../storage/secrets.js'
+import {
+  clearIdentity,
+  getIdentityStatus,
+} from '../storage/identity.js'
+import { discoverProviderModels, type ModelCatalogResult } from '../models/catalog.js'
+import { getLocalHfCacheDir, loadLocalHfModels } from '../models/huggingface.js'
+import { copyToClipboard } from '../utils/clipboard.js'
+import { parseSegments } from '../utils/markdownSegments.js'
+import { exportSessionMarkdown } from '../storage/sessionExport.js'
+import { rewindWorkspaceEdits } from '../storage/rewind.js'
+import type { SessionMessage } from '../storage/sessions.js'
+import path from 'node:path'
+import { setCwd } from '../runtime/cwd.js'
+import type { SessionMode } from '../runtime/sessionMode.js'
+import type { ContextUsage } from '../runtime/compaction.js'
+import { formatModelDisplayName } from '../models/modelDisplay.js'
+import type { McpManager } from '../mcp/manager.js'
+
+export type IdentityRequestAction =
+  | 'manage'
+  | 'create'
+  | 'load'
+
+export type SlashContext = {
+  config: EthagentConfig
+  turns: number
+  approxTokens: number
+  contextUsage: ContextUsage
+  startedAt: number
+  sessionId: string
+  cwd: string
+  mode: SessionMode
+  sessionMessages: () => SessionMessage[]
+  assistantTurns: () => string[]
+  onReplaceConfig: (next: EthagentConfig) => void
+  onChangeCwd: (next: string) => void
+  onClear: () => void
+  onExit: () => void
+  onResumeRequest: () => void
+  onModelPickerRequest: () => void
+  onRewindRequest: () => void
+  onPermissionsRequest: () => void
+  onCompactRequest: () => void
+  onIdentityRequest: (action?: IdentityRequestAction) => void
+  onCopyPickerRequest: (turnText: string, turnLabel: string) => void
+  mcp?: McpManager
+}
+
+export type SlashResult =
+  | { kind: 'note'; text: string; variant?: 'info' | 'error' | 'dim' }
+  | { kind: 'submit'; text: string }
+  | { kind: 'handled' }
+
+type CommandSpec = {
+  name: string
+  aliases?: string[]
+  summary: string
+  hidden?: boolean
+  requiresArgs?: boolean
+  blockedInPlan?: boolean
+  enterBehavior?: 'execute' | 'fill'
+  run: (args: string, ctx: SlashContext) => Promise<SlashResult> | SlashResult
+}
+
+export type SlashSuggestion = {
+  name: string
+  summary: string
+  completion: string
+  executeOnEnter: boolean
+}
+
+export function parseSlash(input: string): { name: string; args: string } | null {
+  const trimmed = input.trim()
+  if (!trimmed.startsWith('/')) return null
+  const body = trimmed.slice(1)
+  const spaceIdx = body.search(/\s/)
+  if (spaceIdx === -1) return { name: body.toLowerCase(), args: '' }
+  return {
+    name: body.slice(0, spaceIdx).toLowerCase(),
+    args: body.slice(spaceIdx + 1).trim(),
+  }
+}
+
+const COMMANDS: CommandSpec[] = [
+  {
+    name: 'help',
+    summary: 'show this list',
+    run: () => ({ kind: 'note', text: renderHelp() }),
+  },
+  {
+    name: 'exit',
+    aliases: ['quit'],
+    summary: 'exit the agent',
+    run: (_args, ctx) => {
+      ctx.onExit()
+      return { kind: 'handled' }
+    },
+  },
+  {
+    name: 'new',
+    aliases: ['clear'],
+    summary: 'clear the transcript and start a new session',
+    run: (_args, ctx) => {
+      ctx.onClear()
+      return { kind: 'handled' }
+    },
+  },
+  {
+    name: 'status',
+    summary: 'provider, model, session id, turns, context, elapsed',
+    run: (_args, ctx) => ({ kind: 'note', text: renderStatus(ctx) }),
+  },
+  {
+    name: 'context',
+    summary: 'show model context usage and compaction options',
+    run: (_args, ctx) => ({ kind: 'note', text: renderContext(ctx) }),
+  },
+  {
+    name: 'cd',
+    requiresArgs: true,
+    enterBehavior: 'fill',
+    summary: 'change working directory · /cd <path>',
+    run: async (args, ctx) => {
+      const target = args.trim()
+      if (!target) return { kind: 'note', variant: 'error', text: 'usage: /cd <path>' }
+      try {
+        const next = setCwd(target, ctx.cwd)
+        ctx.onChangeCwd(next)
+        return { kind: 'note', text: `cwd: ${next}`, variant: 'dim' }
+      } catch (err: unknown) {
+        return { kind: 'note', variant: 'error', text: `cd failed: ${(err as Error).message}` }
+      }
+    },
+  },
+  {
+    name: 'config',
+    summary: 'show resolved config',
+    run: (_args, ctx) => ({
+      kind: 'note',
+      text: `${JSON.stringify(ctx.config, null, 2)}\npath: ${getConfigPath()}`,
+    }),
+  },
+  {
+    name: 'models',
+    summary: 'list models for the current provider',
+    run: async (_args, ctx) => {
+      if (ctx.config.provider === 'llamacpp') {
+        const installed = await loadLocalHfModels()
+        if (installed.length === 0) {
+          return {
+            kind: 'note',
+            text: 'no local model files downloaded. open alt+p and choose "add local model file".',
+          }
+        }
+        const lines = installed.map(m => {
+          const marker = m.id === ctx.config.model ? '*' : ' '
+          const q = m.quantization ? ` ${m.quantization}` : ''
+          const displayName = formatModelDisplayName('llamacpp', m.id, { displayName: m.displayName, maxLength: 64 })
+          return `${marker} ${displayName}${q}  ${formatBytes(m.sizeBytes)}  ${m.risk}`
+        })
+        return { kind: 'note', text: ['installed Hugging Face models:', ...lines].join('\n') }
+      }
+
+      const catalog = await discoverProviderModels(ctx.config)
+      return {
+        kind: 'note',
+        text: renderModelCatalog(catalog, ctx.config.model),
+        variant: catalog.status === 'fallback' ? 'dim' : 'info',
+      }
+    },
+  },
+  {
+    name: 'model',
+    enterBehavior: 'fill',
+    summary: 'open picker or switch model · /model [name]',
+    run: async (args, ctx) => {
+      const name = args.trim()
+      if (!name) {
+        ctx.onModelPickerRequest()
+        return { kind: 'handled' }
+      }
+      if (ctx.config.provider === 'llamacpp') {
+        const installed = await loadLocalHfModels()
+        if (!installed.some(m => m.id === name)) {
+          return {
+            kind: 'note',
+            variant: 'error',
+            text: `'${name}' is not downloaded. open alt+p and choose "view full catalog" or "add local model file".`,
+          }
+        }
+      } else {
+        const catalog = await discoverProviderModels(ctx.config)
+        if (catalog.status === 'ok' && !catalog.entries.some(entry => entry.id === name)) {
+          return {
+            kind: 'note',
+            variant: 'error',
+            text: `'${name}' was not found for ${ctx.config.provider}. use /models to inspect available models.`,
+          }
+        }
+      }
+      const next: EthagentConfig = {
+        ...ctx.config,
+        model: name,
+        baseUrl: baseUrlForModelSwitch(ctx.config),
+      }
+      await saveConfig(next)
+      ctx.onReplaceConfig(next)
+      return { kind: 'note', text: `now using ${next.provider} · ${formatModelDisplayName(next.provider, name, { maxLength: 64 })}.` }
+    },
+  },
+  {
+    name: 'hf',
+    enterBehavior: 'fill',
+    summary: 'local model files · /hf [installed|download <link>]',
+    run: async (args, ctx) => runHuggingFace(args, ctx),
+  },
+  {
+    name: 'resume',
+    summary: 'reopen a prior session',
+    run: (_args, ctx) => {
+      ctx.onResumeRequest()
+      return { kind: 'handled' }
+    },
+  },
+  {
+    name: 'rewind',
+    aliases: ['checkpoint'],
+    summary: 'restore recent managed file edits · /rewind [n]',
+    run: async (args, ctx) => {
+      const trimmed = args.trim()
+      if (!trimmed) {
+        ctx.onRewindRequest()
+        return { kind: 'handled' }
+      }
+      const steps = trimmed ? Number.parseInt(trimmed, 10) : 1
+      if (!Number.isFinite(steps) || steps < 1) {
+        return { kind: 'note', variant: 'error', text: 'usage: /rewind [n]' }
+      }
+      const result = await rewindWorkspaceEdits(ctx.cwd, steps)
+      if (result.reverted === 0) {
+        return { kind: 'note', variant: 'error', text: 'no managed edits available to rewind in this directory.' }
+      }
+      const files = result.files.map(file => path.relative(ctx.cwd, file) || path.basename(file))
+      return {
+        kind: 'note',
+        text: `rewound ${result.reverted} edit${result.reverted === 1 ? '' : 's'}.\n${files.join('\n')}`,
+        variant: 'dim',
+      }
+    },
+  },
+  {
+    name: 'compact',
+    summary: 'summarize older turns to free up context',
+    run: (_args, ctx) => {
+      ctx.onCompactRequest()
+      return { kind: 'handled' }
+    },
+  },
+  {
+    name: 'permissions',
+    summary: 'review or remove saved permission rules for this project',
+    run: (_args, ctx) => {
+      ctx.onPermissionsRequest()
+      return { kind: 'handled' }
+    },
+  },
+  {
+    name: 'copy',
+    summary: 'copy an assistant reply to the clipboard · /copy [n]',
+    run: async (args, ctx) => {
+      const assistant = ctx.assistantTurns()
+      if (assistant.length === 0) {
+        return { kind: 'note', variant: 'error', text: 'nothing to copy yet.' }
+      }
+      let offset = 1
+      const trimmed = args.trim()
+      if (trimmed) {
+        const parsed = Number.parseInt(trimmed, 10)
+        if (!Number.isFinite(parsed) || parsed < 1) {
+          return { kind: 'note', variant: 'error', text: 'usage: /copy [n]  (n counts back from the latest reply, 1 = most recent)' }
+        }
+        offset = parsed
+      }
+      const index = assistant.length - offset
+      if (index < 0) {
+        return { kind: 'note', variant: 'error', text: `only ${assistant.length} assistant reply on record.` }
+      }
+      const text = assistant[index] ?? ''
+      const label = offset === 1 ? 'latest reply' : `reply #${offset} back`
+      const segments = parseSegments(text)
+      if (segments.length <= 1) {
+        const result = await copyToClipboard(text)
+        if (!result.ok) {
+          return { kind: 'note', variant: 'error', text: `copy failed: ${result.error}` }
+        }
+        return { kind: 'note', text: `copied ${text.length} chars via ${result.method}.`, variant: 'dim' }
+      }
+      ctx.onCopyPickerRequest(text, label)
+      return { kind: 'handled' }
+    },
+  },
+  {
+    name: 'export',
+    blockedInPlan: true,
+    summary: 'write the transcript to a markdown file',
+    run: async (_args, ctx) => {
+      const messages = ctx.sessionMessages()
+      if (messages.length === 0) {
+        return { kind: 'note', variant: 'error', text: 'nothing to export yet.' }
+      }
+      try {
+        const file = await exportSessionMarkdown(ctx.sessionId, messages, {
+          model: ctx.config.model,
+          provider: ctx.config.provider,
+        })
+        return { kind: 'note', text: `exported to ${file}` }
+      } catch (err: unknown) {
+        return { kind: 'note', variant: 'error', text: `export failed: ${(err as Error).message}` }
+      }
+    },
+  },
+  {
+    name: 'mcp',
+    enterBehavior: 'fill',
+    summary: 'manage MCP servers · /mcp [status|approve|reject|reconnect|enable|disable|add-json]',
+    run: async (args, ctx) => runMcp(args, ctx),
+  },
+  {
+    name: 'identity',
+    enterBehavior: 'fill',
+    summary: 'Ethereum identity · /identity [status|create|load|remove]',
+    run: async (args, ctx) => runIdentity(args, ctx),
+  },
+  {
+    name: 'doctor',
+    summary: 'spec, config, local runtime, key presence',
+    run: async (_args, ctx) => {
+      const [spec, keys, identity, llamaCpp, hfModels] = await Promise.all([
+        detectSpec(),
+        Promise.all(
+          (['openai', 'anthropic', 'gemini'] as ProviderId[]).map(async p => [p, await hasKey(p)] as const),
+        ),
+        getIdentityStatus(ctx.config),
+        detectLlamaCpp(),
+        loadLocalHfModels(),
+      ])
+      return { kind: 'note', text: renderDoctor(spec, keys, identity, ctx, llamaCpp, hfModels.length) }
+    },
+  },
+]
+
+async function runHuggingFace(args: string, ctx: SlashContext): Promise<SlashResult> {
+  const tokens = args.trim().split(/\s+/).filter(Boolean)
+  const sub = tokens[0]?.toLowerCase() ?? ''
+
+  if (!sub || sub === 'installed') {
+    const installed = await loadLocalHfModels()
+    if (installed.length === 0) {
+      return {
+        kind: 'note',
+        variant: 'dim',
+        text: 'no local model files downloaded. press alt+p and choose "add local model file".',
+      }
+    }
+    const lines = installed.map(model => {
+      const marker = model.id === ctx.config.model && ctx.config.provider === 'llamacpp' ? '*' : ' '
+      const displayName = formatModelDisplayName('llamacpp', model.id, { displayName: model.displayName, maxLength: 64 })
+      return `${marker} ${displayName}  ${formatBytes(model.sizeBytes)}  ${model.risk}`
+    })
+    return { kind: 'note', text: ['installed Hugging Face models:', ...lines].join('\n') }
+  }
+
+  if (sub === 'download' || sub === 'model') {
+    const link = tokens.slice(1).join(' ')
+    ctx.onModelPickerRequest()
+    return {
+      kind: 'note',
+      variant: 'dim',
+      text: link
+        ? `alt+p opened. choose "add local model file" and paste: ${link}`
+        : 'alt+p opened. choose "add local model file" and paste the model URL or repo id.',
+    }
+  }
+
+  return {
+    kind: 'note',
+    variant: 'error',
+    text: 'usage: /hf [installed|download <huggingface.co link or repo id>]',
+  }
+}
+
+async function runMcp(args: string, ctx: SlashContext): Promise<SlashResult> {
+  if (!ctx.mcp) {
+    return { kind: 'note', variant: 'error', text: 'MCP runtime is not available in this session.' }
+  }
+
+  const tokens = args.trim().split(/\s+/).filter(Boolean)
+  const sub = tokens[0]?.toLowerCase() ?? ''
+  if (!sub || sub === 'status' || sub === 'list') {
+    return { kind: 'note', text: ctx.mcp.renderStatus(), variant: 'info' }
+  }
+
+  try {
+    if (sub === 'approve') {
+      const name = tokens.slice(1).join(' ')
+      if (!name) return { kind: 'note', variant: 'error', text: 'usage: /mcp approve <server>' }
+      return { kind: 'note', text: await ctx.mcp.approveServer(name), variant: 'dim' }
+    }
+    if (sub === 'reject') {
+      const name = tokens.slice(1).join(' ')
+      if (!name) return { kind: 'note', variant: 'error', text: 'usage: /mcp reject <server>' }
+      return { kind: 'note', text: await ctx.mcp.rejectServer(name), variant: 'dim' }
+    }
+    if (sub === 'reconnect') {
+      const name = tokens.slice(1).join(' ') || undefined
+      return { kind: 'note', text: await ctx.mcp.reconnect(name), variant: 'dim' }
+    }
+    if (sub === 'enable' || sub === 'disable') {
+      const name = tokens.slice(1).join(' ')
+      if (!name) return { kind: 'note', variant: 'error', text: `usage: /mcp ${sub} <server>` }
+      return { kind: 'note', text: await ctx.mcp.setEnabled(name, sub === 'enable'), variant: 'dim' }
+    }
+    if (sub === 'add-json') {
+      const project = tokens[1] === '--project'
+      const nameIndex = project ? 2 : 1
+      const name = tokens[nameIndex]
+      if (!name) return { kind: 'note', variant: 'error', text: 'usage: /mcp add-json [--project] <name> <json>' }
+      const jsonStart = nthTokenStart(args, nameIndex + 1)
+      const json = jsonStart >= 0 ? args.slice(jsonStart).trim() : ''
+      if (!json) return { kind: 'note', variant: 'error', text: 'usage: /mcp add-json [--project] <name> <json>' }
+      return { kind: 'note', text: await ctx.mcp.addJson(name, json, project ? 'project' : 'user'), variant: 'dim' }
+    }
+  } catch (err: unknown) {
+    return { kind: 'note', variant: 'error', text: `mcp failed: ${(err as Error).message}` }
+  }
+
+  return {
+    kind: 'note',
+    variant: 'error',
+    text: 'usage: /mcp [status|approve <server>|reject <server>|reconnect [server]|enable <server>|disable <server>|add-json [--project] <name> <json>]',
+  }
+}
+
+async function runIdentity(args: string, ctx: SlashContext): Promise<SlashResult> {
+  const tokens = args.trim().split(/\s+/).filter(Boolean)
+  const sub = tokens[0]?.toLowerCase() ?? ''
+  const rest = tokens.slice(1)
+
+  if (!sub) {
+    ctx.onIdentityRequest('manage')
+    return { kind: 'handled' }
+  }
+
+  if (sub === 'status') {
+    const status = await getIdentityStatus(ctx.config)
+    if (!status) {
+      return {
+        kind: 'note',
+        variant: 'dim',
+        text: 'no Ethereum identity set. run /identity create to make one.',
+      }
+    }
+    const lines = [
+      `address    ${status.address}`,
+      `created    ${status.createdAt}`,
+      `backend    ${status.backend}`,
+    ]
+    if (status.source) lines.push(`source     ${status.source}`)
+    if (status.agentId) lines.push(`token      #${status.agentId}`)
+    return { kind: 'note', text: lines.join('\n') }
+  }
+
+  if (sub === 'create') {
+    ctx.onIdentityRequest('create')
+    return { kind: 'handled' }
+  }
+
+  if (sub === 'load') {
+    ctx.onIdentityRequest('load')
+    return { kind: 'handled' }
+  }
+
+  if (sub === 'remove') {
+    if (rest[0] !== 'confirm') {
+      return {
+        kind: 'note',
+        variant: 'error',
+        text: 'remove deletes local identity metadata and any legacy stored key. re-run with: /identity remove confirm',
+      }
+    }
+    const status = await getIdentityStatus(ctx.config)
+    if (!status) {
+      return { kind: 'note', variant: 'dim', text: 'no Ethereum identity to remove.' }
+    }
+    const next = await clearIdentity(ctx.config)
+    ctx.onReplaceConfig(next)
+    return { kind: 'note', text: `removed identity ${status.address}.`, variant: 'dim' }
+  }
+
+  return {
+    kind: 'note',
+    variant: 'error',
+    text: 'usage: /identity [status|create|load|remove confirm]',
+  }
+}
+
+function renderHelp(): string {
+  const visibleCommands = COMMANDS.filter(c => !c.hidden)
+  const maxName = Math.max(...visibleCommands.map(c => commandLabel(c).length))
+  const lines = visibleCommands.map(c => {
+    const label = commandLabel(c)
+    return `  ${label.padEnd(maxName)}   ${c.summary}`
+  })
+  return [
+    'slash commands:',
+    ...lines,
+    '',
+    'shortcuts: esc cancels · ctrl+c twice exits · alt+p model · alt+i identity · shift+tab mode.',
+  ].join('\n')
+}
+
+function commandLabel(cmd: CommandSpec): string {
+  if (!cmd.aliases || cmd.aliases.length === 0) return `/${cmd.name}`
+  return `/${cmd.name} (${cmd.aliases.map(a => `/${a}`).join(', ')})`
+}
+
+function renderStatus(ctx: SlashContext): string {
+  const elapsedMs = Date.now() - ctx.startedAt
+  const minutes = Math.floor(elapsedMs / 60000)
+  const seconds = Math.floor((elapsedMs % 60000) / 1000)
+  const elapsed = minutes > 0 ? `${minutes}m${seconds.toString().padStart(2, '0')}s` : `${seconds}s`
+  const displayModel = formatModelDisplayName(ctx.config.provider, ctx.config.model, { maxLength: 72 })
+  return [
+    `provider   ${ctx.config.provider}`,
+    `model      ${displayModel}`,
+    `cwd        ${ctx.cwd}`,
+    `session    ${ctx.sessionId.slice(0, 8)}`,
+    'state      active',
+    `turns      ${ctx.turns}`,
+    `tokens     ~${ctx.approxTokens}`,
+    `context    ${ctx.contextUsage.percent}% (~${ctx.contextUsage.usedTokens}/${ctx.contextUsage.windowTokens}, ${ctx.contextUsage.source})`,
+    `elapsed    ${elapsed}`,
+  ].join('\n')
+}
+
+function renderContext(ctx: SlashContext): string {
+  const usage = ctx.contextUsage
+  const free = Math.max(0, usage.windowTokens - usage.usedTokens)
+  const action =
+    usage.percent >= 90
+      ? 'Context is near the model limit. New requests will ask you to summarize into a new conversation, switch models, ignore and send, or cancel.'
+      : usage.percent >= 75
+        ? 'Context is getting full. Consider /compact before a new task boundary.'
+        : 'Context has comfortable room.'
+  return [
+    'context usage:',
+    `  model      ${ctx.config.provider} · ${formatModelDisplayName(ctx.config.provider, ctx.config.model, { maxLength: 72 })}`,
+    `  used       ~${usage.usedTokens} / ${usage.windowTokens} tokens (${usage.percent}%)`,
+    `  free       ~${free} tokens`,
+    `  estimate   ${usage.confidence} (${usage.source})`,
+    '  session    active',
+    '',
+    action,
+  ].join('\n')
+}
+
+function renderDoctor(
+  spec: Awaited<ReturnType<typeof detectSpec>>,
+  keys: ReadonlyArray<readonly [ProviderId, boolean]>,
+  identity: Awaited<ReturnType<typeof getIdentityStatus>>,
+  ctx: SlashContext,
+  llamaCpp: Awaited<ReturnType<typeof detectLlamaCpp>>,
+  hfModelCount: number,
+): string {
+  const lines: string[] = ['diagnostics:']
+  lines.push(`  platform   ${spec.platform}/${spec.arch}${spec.isAppleSilicon ? ' (apple silicon)' : ''}`)
+  lines.push(`  ram        ${formatGB(spec.effectiveRamBytes)}${spec.gpuVramBytes ? ` · vram ${formatGB(spec.gpuVramBytes)}` : ''}`)
+  lines.push(`  local run  ${llamaCpp.binaryPresent ? 'installed' : 'not installed'} · server ${llamaCpp.serverUp ? 'up' : 'down'}`)
+  lines.push(`  hf models  ${hfModelCount} downloaded`)
+  lines.push('')
+  lines.push('config:')
+  lines.push(`  provider   ${ctx.config.provider}`)
+  lines.push(`  model      ${formatModelDisplayName(ctx.config.provider, ctx.config.model, { maxLength: 72 })}`)
+  if (ctx.config.baseUrl) lines.push(`  baseUrl    ${ctx.config.baseUrl}`)
+  if (ctx.config.provider === 'llamacpp') lines.push(`  hf cache   ${getLocalHfCacheDir()}`)
+  lines.push(`  path       ${getConfigPath()}`)
+  lines.push('')
+  lines.push('keys:')
+  for (const [provider, present] of keys) {
+    lines.push(`  ${provider.padEnd(9)}  ${present ? 'set' : 'not set'}`)
+  }
+  lines.push('')
+  lines.push('identity:')
+  if (identity) {
+    lines.push(`  address    ${identity.address}`)
+    lines.push(`  backend    ${identity.backend}`)
+    if (identity.source) lines.push(`  source     ${identity.source}`)
+    if (identity.agentId) lines.push(`  token      #${identity.agentId}`)
+  } else {
+    lines.push('  address    not set')
+  }
+  return lines.join('\n')
+}
+
+function renderModelCatalog(catalog: ModelCatalogResult, currentModel: string): string {
+  const title = catalog.status === 'fallback'
+    ? `${catalog.provider} models (fallback${catalog.error ? `: ${catalog.error}` : ''}):`
+    : `${catalog.provider} models:`
+  const lines = catalog.entries.map(entry => {
+    const marker = entry.id === currentModel ? '*' : ' '
+    const suffix = entry.source === 'fallback' ? '  fallback' : ''
+    return `${marker} ${formatModelDisplayName(catalog.provider, entry.id, { maxLength: 72 })}${suffix}`
+  })
+  return [title, ...lines].join('\n')
+}
+
+function baseUrlForModelSwitch(config: EthagentConfig): string | undefined {
+  if (config.provider === 'llamacpp') return localProviderBaseUrlFor('llamacpp', config.baseUrl)
+  if (config.provider === 'openai') return config.baseUrl
+  return undefined
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes <= 0) return '—'
+  const gb = bytes / (1024 * 1024 * 1024)
+  if (gb >= 1) return `${gb.toFixed(1)}GB`
+  const mb = bytes / (1024 * 1024)
+  return `${mb.toFixed(0)}MB`
+}
+
+function formatGB(bytes: number): string {
+  const gb = bytes / (1024 * 1024 * 1024)
+  if (gb >= 10) return `${Math.round(gb)}GB`
+  return `${gb.toFixed(1)}GB`
+}
+
+export async function dispatchSlash(input: string, ctx: SlashContext): Promise<SlashResult | null> {
+  const parsed = parseSlash(input)
+  if (!parsed) return null
+  const cmd = COMMANDS.find(c => c.name === parsed.name || c.aliases?.includes(parsed.name))
+  if (!cmd) {
+    try {
+      const promptText = await ctx.mcp?.runPromptSlash(parsed.name, parsed.args)
+      if (promptText !== null && promptText !== undefined) return { kind: 'submit', text: promptText }
+    } catch (err: unknown) {
+      return { kind: 'note', variant: 'error', text: `mcp prompt failed: ${(err as Error).message}` }
+    }
+    return { kind: 'note', variant: 'error', text: `unknown command: /${parsed.name}. try /help` }
+  }
+  if (ctx.mode === 'plan' && cmd.blockedInPlan) {
+    return { kind: 'note', variant: 'error', text: `/${cmd.name} is blocked in plan mode.` }
+  }
+  return cmd.run(parsed.args, ctx)
+}
+
+export function getSlashSuggestions(extra: SlashSuggestion[] = []): SlashSuggestion[] {
+  return [...COMMANDS.filter(c => !c.hidden).map(c => ({
+    name: c.name,
+    summary: c.summary,
+    completion: c.requiresArgs || c.enterBehavior === 'fill' ? `/${c.name} ` : `/${c.name}`,
+    executeOnEnter: !c.requiresArgs && c.enterBehavior !== 'fill',
+  })), ...extra]
+}
+
+function nthTokenStart(value: string, tokenIndex: number): number {
+  const matches = [...value.matchAll(/\S+/g)]
+  return matches[tokenIndex]?.index ?? -1
+}