@rezti/dsh-rez-suite 0.1.0

package/src/mcp-host.ts

@@ -0,0 +1,418 @@
+/**
+ * In-plugin MCP host. Connects every enabled server from config.servers over
+ * stdio or streamable-http, discovers tools, filters them through the role
+ * preset, and registers the survivors on ctx.tools as \`mcp__<server>__<rawName>\`.
+ */
+
+import { createHash } from 'node:crypto'
+import { setDefaultResultOrder } from 'node:dns'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js'
+import z from 'zod'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { RezConfig, RezMcpTransport, RezRoleId, RezServerId, RezServerStatus, RezTestResult } from './protocol.ts'
+import { isToolAllowed } from './presets.ts'
+import { estimateTokens, type TokenManager } from './token-manager.ts'
+
+const MAX_PUBLIC_NAME_LENGTH = 64
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g
+const HASH_LENGTH = 12
+
+const RawCallToolResultSchema = z.record(z.string(), z.unknown())
+
+interface McpToolInfo {
+  rawName: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+interface ServerDescriptor {
+  id: RezServerId
+  serverName: string
+  transport: RezMcpTransport
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  url?: string
+  headers?: Record<string, string>
+  toolCallTimeoutMs: number
+}
+
+interface LiveConnection {
+  descriptor: ServerDescriptor
+  client: Client
+  transport: StdioClientTransport | StreamableHTTPClientTransport
+  tools: McpToolInfo[]
+  disposers: Map<string, () => void>
+  startedAt: number
+  lastError?: string
+}
+
+/** Copy of dsh-mcp-client's deterministic public-name derivation. */
+function publicToolName(serverName: string, rawName: string): string {
+  const joined = 'mcp__' + serverName + '__' + rawName
+  const normalized = joined.replace(INVALID_NAME_CHARS, '_')
+  if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized
+  const hash = createHash('sha256').update(serverName + '\0' + rawName).digest('hex').slice(0, HASH_LENGTH)
+  return normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1) + '_' + hash
+}
+
+function text(value: string): ContentBlock[] {
+  return [{ type: 'text', text: value }]
+}
+
+function extractText(mcpContent: unknown, toolName: string): string {
+  if (!Array.isArray(mcpContent)) return String(mcpContent ?? '')
+  const parts: string[] = []
+  for (const value of mcpContent) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      parts.push('[unsupported content type: unknown]')
+      continue
+    }
+    const block = value as Record<string, unknown>
+    switch (block.type) {
+      case 'text':
+        parts.push(block.text === undefined ? '' : String(block.text))
+        break
+      case 'image':
+        parts.push('[image: ' + String(block.mimeType ?? 'unknown') + ', content discarded]')
+        break
+      case 'audio':
+        parts.push('[audio: ' + String(block.mimeType ?? 'unknown') + ', content discarded]')
+        break
+      case 'resource':
+        parts.push('[resource content discarded]')
+        break
+      case 'resource_link':
+        parts.push('[resource_link: ' + String(block.uri ?? '') + ']')
+        break
+      default:
+        parts.push('[unsupported content type: ' + String(block.type ?? 'unknown') + ']')
+    }
+  }
+  if (parts.length === 0) parts.push('[tool ' + toolName + ' returned no text]')
+  return parts.join('\n')
+}
+
+/** Merge the parent process env with server overrides, dropping undefined values. */
+function childEnv(extra: Record<string, string> | undefined): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) env[key] = value
+  }
+  Object.assign(env, extra ?? {})
+  return env
+}
+
+function serverScript(name: string): string {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const fromSrc = join(here, '..', 'servers', name)
+  const fromLib = join(here, '..', '..', 'servers', name)
+  if (existsSync(fromSrc)) return fromSrc
+  if (existsSync(fromLib)) return fromLib
+  return fromSrc
+}
+
+/** Resolve config.servers to concrete transport descriptors. */
+export function resolveServers(config: RezConfig): ServerDescriptor[] {
+  const descriptors: ServerDescriptor[] = []
+  for (const [id, server] of Object.entries(config.servers)) {
+    if (!server.enabled) continue
+    const descriptor: ServerDescriptor = {
+      id,
+      serverName: id,
+      transport: server.transport,
+      command: server.command,
+      args: server.args,
+      env: server.env,
+      cwd: server.cwd,
+      url: server.url,
+      headers: server.headers,
+      toolCallTimeoutMs: server.toolCallTimeoutMs ?? 60000,
+    }
+
+    // Bundled local servers: launch our own scripts unless the user overrode args.
+    if (id === 'fs' || id === 'sqlite') {
+      descriptor.command = descriptor.command ?? process.execPath
+      const script = id === 'fs' ? 'fs-mcp-server.mjs' : 'sqlite-mcp-server.mjs'
+      descriptor.args = descriptor.args !== undefined && descriptor.args.length > 0 ? descriptor.args : [serverScript(script)]
+    }
+
+    descriptors.push(descriptor)
+  }
+  return descriptors
+}
+
+export class McpHost {
+  private connections = new Map<RezServerId, LiveConnection>()
+  private enabledIds = new Set<RezServerId>()
+  private role: RezRoleId = 'all'
+  private billing: RezConfig['billing'] = { inputCostPer1k: 0.001, outputCostPer1k: 0.002, monthlyBudget: 0 }
+  private syncChain: Promise<void> = Promise.resolve()
+  private readonly ctx: Context
+  private readonly tokenManager: TokenManager
+
+  constructor(ctx: Context, tokenManager: TokenManager) {
+    this.ctx = ctx
+    this.tokenManager = tokenManager
+  }
+
+  /** Serialize reconciliation so concurrent settings callbacks cannot double-register tools. */
+  sync(config: RezConfig): Promise<void> {
+    this.syncChain = this.syncChain.then(() => this.syncInner(config)).catch(error => {
+      console.warn('[dsh-rez-suite] MCP sync failed:', error)
+    })
+    return this.syncChain
+  }
+
+  /** Reconcile live connections with the current configuration. */
+  private async syncInner(config: RezConfig): Promise<void> {
+    const roleChanged = this.role !== config.role
+    this.role = config.role
+    this.billing = config.billing
+    const wanted = resolveServers(config)
+    const wantedIds = new Set(wanted.map(descriptor => descriptor.id))
+    this.enabledIds = new Set(wantedIds)
+
+    for (const [id] of [...this.connections]) {
+      if (!wantedIds.has(id)) {
+        await this.disposeConnection(id)
+      }
+    }
+
+    for (const descriptor of wanted) {
+      const existing = this.connections.get(descriptor.id)
+      const signature = JSON.stringify([descriptor.transport, descriptor.command, descriptor.args, descriptor.env, descriptor.cwd, descriptor.url, descriptor.headers])
+      if (existing !== undefined) {
+        const oldSignature = JSON.stringify([existing.descriptor.transport, existing.descriptor.command, existing.descriptor.args, existing.descriptor.env, existing.descriptor.cwd, existing.descriptor.url, existing.descriptor.headers])
+        if (!roleChanged && oldSignature === signature) continue
+        await this.disposeConnection(descriptor.id)
+      }
+      try {
+        await this.startConnection(descriptor)
+      } catch (error) {
+        console.warn('[dsh-rez-suite] MCP ' + descriptor.id + ' start failed:', error)
+      }
+    }
+  }
+
+  private async startConnection(descriptor: ServerDescriptor): Promise<void> {
+    const connection = await this.connect(descriptor)
+    const definitions: Array<{ definition: ToolDefinition; publicName: string }> = []
+    for (const tool of connection.tools) {
+      if (!isToolAllowed(this.role, descriptor.serverName, tool.rawName)) continue
+      const publicName = publicToolName(descriptor.serverName, tool.rawName)
+      definitions.push({ definition: this.buildDefinition(descriptor, connection, tool, publicName), publicName })
+    }
+
+    const disposers = new Map<string, () => void>()
+    try {
+      for (const { definition, publicName } of definitions) {
+        disposers.set(publicName, this.ctx.tools.register(definition))
+      }
+    } catch (error) {
+      for (const dispose of disposers.values()) dispose()
+      await this.closeConnection(connection)
+      throw error
+    }
+    connection.disposers = disposers
+    this.connections.set(descriptor.id, connection)
+    console.info('[dsh-rez-suite] MCP ' + descriptor.id + ' connected, registered ' + disposers.size + ' tools (role=' + this.role + ')')
+  }
+
+  private buildDefinition(descriptor: ServerDescriptor, connection: LiveConnection, tool: McpToolInfo, publicName: string): ToolDefinition {
+    const rawName = tool.rawName
+    const serverId = descriptor.id
+    const execute = async (args: unknown, exec: { signal: AbortSignal }): Promise<unknown> => {
+      const started = Date.now()
+      const callArgs = typeof args === 'object' && args !== null ? (args as Record<string, unknown>) : {}
+      try {
+        const result = await (connection.client as unknown as {
+          request(method: unknown, schema: unknown, options?: { signal?: AbortSignal; timeout?: number }): Promise<Record<string, unknown>>
+        }).request(
+          { method: 'tools/call', params: { name: rawName, arguments: callArgs } },
+          RawCallToolResultSchema,
+          { signal: exec.signal, timeout: descriptor.toolCallTimeoutMs },
+        )
+        const content = Array.isArray(result.content) ? result.content : []
+        const rendered = extractText(content, rawName)
+        if (result.isError === true) {
+          throw new Error(rendered)
+        }
+        this.recordUsage(serverId, rawName, true, callArgs, rendered, Date.now() - started)
+        return {
+          content,
+          ...(result.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}),
+        }
+      } catch (error) {
+        this.recordUsage(serverId, rawName, false, callArgs, error instanceof Error ? error.message : String(error), Date.now() - started)
+        throw error
+      }
+    }
+
+    return {
+      name: publicName,
+      description: tool.description,
+      parameters: tool.inputSchema,
+      output: {
+        schema: {
+          type: 'object',
+          properties: {
+            content: { type: 'array', items: {} },
+            structuredContent: {},
+          },
+          required: ['content'],
+          additionalProperties: false,
+        },
+        render: (_args: unknown, value: unknown): ContentBlock[] => {
+          const record = (value ?? {}) as Record<string, unknown>
+          return text(extractText(record.content, rawName))
+        },
+      },
+      execute,
+    } as unknown as ToolDefinition
+  }
+
+  private recordUsage(server: RezServerId, tool: string, ok: boolean, args: unknown, output: string, durationMs: number): void {
+    const inputTokens = estimateTokens(args)
+    const outputTokens = estimateTokens(output)
+    const cost = (inputTokens / 1000) * this.billing.inputCostPer1k + (outputTokens / 1000) * this.billing.outputCostPer1k
+    this.tokenManager.record({
+      server,
+      tool,
+      role: this.role,
+      inputTokens,
+      outputTokens,
+      cost,
+      durationMs,
+      ok,
+      error: ok ? undefined : output,
+    })
+  }
+
+  private async connect(descriptor: ServerDescriptor): Promise<LiveConnection> {
+    const client = new Client({ name: 'dsh-rez-suite', version: '0.1.0' })
+    const transport = descriptor.transport === 'stdio'
+      ? new StdioClientTransport({
+          command: descriptor.command ?? '',
+          args: descriptor.args ?? [],
+          env: childEnv(descriptor.env),
+          cwd: descriptor.cwd,
+          stderr: 'pipe',
+        })
+      : new StreamableHTTPClientTransport(new URL(descriptor.url ?? ''), {
+          requestInit: { headers: descriptor.headers ?? {} },
+        })
+    await client.connect(transport)
+    const tools = await listTools(client)
+    return {
+      descriptor,
+      client,
+      transport,
+      tools,
+      disposers: new Map(),
+      startedAt: Date.now(),
+    }
+  }
+
+  private async closeConnection(connection: LiveConnection): Promise<void> {
+    for (const dispose of connection.disposers.values()) {
+      try { dispose() } catch { /* ignore */ }
+    }
+    try { await connection.transport.close() } catch { /* ignore */ }
+    try { await connection.client.close() } catch { /* ignore */ }
+  }
+
+  private async disposeConnection(id: RezServerId): Promise<void> {
+    const connection = this.connections.get(id)
+    if (connection === undefined) return
+    this.connections.delete(id)
+    await this.closeConnection(connection)
+  }
+
+  /** Test every enabled server with a throwaway connection. */
+  async test(config: RezConfig): Promise<RezTestResult[]> {
+    const results: RezTestResult[] = []
+    for (const descriptor of resolveServers(config)) {
+      const started = Date.now()
+      let connection: LiveConnection | undefined
+      try {
+        connection = await this.connect(descriptor)
+        const serverInfo = (connection.client.getServerVersion?.() as { name?: string; version?: string } | undefined)
+        results.push({
+          server: descriptor.id,
+          ok: true,
+          toolCount: connection.tools.length,
+          serverInfo: serverInfo ? serverInfo.name + ' ' + serverInfo.version : undefined,
+          latencyMs: Date.now() - started,
+        })
+      } catch (error) {
+        results.push({
+          server: descriptor.id,
+          ok: false,
+          latencyMs: Date.now() - started,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      } finally {
+        if (connection !== undefined) await this.closeConnection(connection)
+      }
+    }
+    return results
+  }
+
+  status(): RezServerStatus[] {
+    const ids = new Set<string>([...this.enabledIds, ...this.connections.keys()])
+    return [...ids].sort().map(id => {
+      const connection = this.connections.get(id)
+      if (connection === undefined) {
+        return { server: id, enabled: this.enabledIds.has(id), state: 'disconnected', toolCount: 0, registeredTools: 0 }
+      }
+      return {
+        server: id,
+        enabled: true,
+        state: 'connected',
+        toolCount: connection.tools.length,
+        registeredTools: connection.disposers.size,
+        lastError: connection.lastError,
+        startedAt: connection.startedAt,
+      }
+    })
+  }
+
+  async dispose(): Promise<void> {
+    for (const id of [...this.connections.keys()]) {
+      await this.disposeConnection(id)
+    }
+  }
+}
+
+/** Drain uncached tools/list pagination (mirrors dsh-mcp-client). */
+async function listTools(client: Client): Promise<McpToolInfo[]> {
+  const tools: McpToolInfo[] = []
+  let cursor: string | undefined
+  do {
+    const response = await (client as unknown as {
+      request(method: unknown, schema: unknown): Promise<{ tools: Array<Record<string, unknown>>; nextCursor?: string }>
+    }).request(
+      { method: 'tools/list', ...(cursor === undefined ? {} : { params: { cursor } }) },
+      ListToolsResultSchema,
+    )
+    for (const raw of response.tools) {
+      tools.push({
+        rawName: String(raw.name),
+        description: raw.description === undefined ? '' : String(raw.description),
+        inputSchema: typeof raw.inputSchema === 'object' && raw.inputSchema !== null ? raw.inputSchema as Record<string, unknown> : { type: 'object' },
+      })
+    }
+    cursor = response.nextCursor
+  } while (cursor !== undefined)
+  return tools
+}

package/src/presets.ts

@@ -0,0 +1,125 @@
+/**
+ * Role-based MCP tool presets. MCP tools are registered under
+ * \`mcp__<server>__<rawName>\`; the filter matches the lowercase raw tool
+ * name against server-scoped wildcard patterns. A role with no matching rule
+ * denies the tool (fail closed); \`all\` registers everything.
+ */
+
+import type { RezRoleId, RezServerId } from './protocol.ts'
+
+interface RoleRule {
+  server: RezServerId
+  /** Case-insensitive wildcard pattern over the raw MCP tool name. */
+  pattern: string
+}
+
+const RULES: Record<Exclude<RezRoleId, 'all'>, RoleRule[]> = {
+  engineer: [
+    // Odoo lookups and reads.
+    { server: 'odoo', pattern: '*search*' },
+    { server: 'odoo', pattern: '*read*' },
+    { server: 'odoo', pattern: '*get*' },
+    { server: 'odoo', pattern: '*list*' },
+    // Home Assistant read-only state.
+    { server: 'homeassistant', pattern: '*get*' },
+    { server: 'homeassistant', pattern: '*list*' },
+    { server: 'homeassistant', pattern: '*state*' },
+    // TAPD read/query.
+    { server: 'tapd', pattern: '*query*' },
+    { server: 'tapd', pattern: '*get*' },
+    { server: 'tapd', pattern: '*list*' },
+    // Dify read/query.
+    { server: 'dify', pattern: '*query*' },
+    { server: 'dify', pattern: '*get*' },
+    // Local filesystem inspection.
+    { server: 'fs', pattern: '*read*' },
+    { server: 'fs', pattern: '*list*' },
+    { server: 'fs', pattern: '*stat*' },
+    // Local cache/log queries.
+    { server: 'sqlite', pattern: '*query*' },
+    { server: 'sqlite', pattern: '*select*' },
+    { server: 'sqlite', pattern: '*table*' },
+    // Read-only Nextcloud access for specs/documents.
+    { server: 'nextcloud', pattern: '*list*' },
+    { server: 'nextcloud', pattern: '*download*' },
+    { server: 'nextcloud', pattern: '*read*' },
+  ],
+  sales: [
+    // Odoo CRM / sales objects.
+    { server: 'odoo', pattern: '*crm*' },
+    { server: 'odoo', pattern: '*partner*' },
+    { server: 'odoo', pattern: '*lead*' },
+    { server: 'odoo', pattern: '*opportunity*' },
+    { server: 'odoo', pattern: '*sale*' },
+    { server: 'odoo', pattern: '*quotation*' },
+    // Upload / write sales collateral to Nextcloud.
+    { server: 'nextcloud', pattern: '*upload*' },
+    { server: 'nextcloud', pattern: '*write*' },
+    { server: 'nextcloud', pattern: '*mkdir*' },
+    { server: 'nextcloud', pattern: '*move*' },
+    // WeCom one-to-one / group sends.
+    { server: 'wecom', pattern: '*send*' },
+    { server: 'wecom', pattern: '*message*' },
+  ],
+  operations: [
+    // Odoo reporting and fulfilment.
+    { server: 'odoo', pattern: '*report*' },
+    { server: 'odoo', pattern: '*stock*' },
+    { server: 'odoo', pattern: '*purchase*' },
+    { server: 'odoo', pattern: '*inventory*' },
+    { server: 'odoo', pattern: '*invoice*' },
+    // Home Assistant control.
+    { server: 'homeassistant', pattern: '*call_service*' },
+    { server: 'homeassistant', pattern: '*control*' },
+    { server: 'homeassistant', pattern: '*set*' },
+    // TAPD write operations.
+    { server: 'tapd', pattern: '*create*' },
+    { server: 'tapd', pattern: '*update*' },
+    { server: 'tapd', pattern: '*delete*' },
+    // Dify workflow execution.
+    { server: 'dify', pattern: '*run*' },
+    { server: 'dify', pattern: '*workflow*' },
+    { server: 'dify', pattern: '*chat*' },
+    // Nextcloud management.
+    { server: 'nextcloud', pattern: '*list*' },
+    { server: 'nextcloud', pattern: '*delete*' },
+    { server: 'nextcloud', pattern: '*manage*' },
+    { server: 'nextcloud', pattern: '*move*' },
+    { server: 'nextcloud', pattern: '*upload*' },
+    // WeCom broadcasts.
+    { server: 'wecom', pattern: '*broadcast*' },
+    { server: 'wecom', pattern: '*send*' },
+    // Local audit cache.
+    { server: 'sqlite', pattern: '*query*' },
+    { server: 'sqlite', pattern: '*maintenance*' },
+  ],
+}
+
+/** Compile a simple \`*\` wildcard pattern to a RegExp without regex escaping. */
+function compilePattern(pattern: string): RegExp {
+  const pieces = pattern.split('*')
+  let source = '^'
+  for (let index = 0; index < pieces.length; index++) {
+    if (index > 0) source += '.*'
+    const piece = pieces[index]
+    for (const char of piece) {
+      if ('[\\]{}()^$?.+|'.includes(char)) source += '\\' + char
+      else source += char
+    }
+  }
+  source += '$'
+  return new RegExp(source, 'i')
+}
+
+const COMPILED: Record<Exclude<RezRoleId, 'all'>, { server: RezServerId; test: RegExp }[]> = {
+  engineer: RULES.engineer.map(rule => ({ server: rule.server, test: compilePattern(rule.pattern) })),
+  sales: RULES.sales.map(rule => ({ server: rule.server, test: compilePattern(rule.pattern) })),
+  operations: RULES.operations.map(rule => ({ server: rule.server, test: compilePattern(rule.pattern) })),
+}
+
+/** Whether one MCP tool may be registered for the selected role. */
+export function isToolAllowed(role: RezRoleId, server: string, rawName: string): boolean {
+  if (role === 'all') return true
+  const rules = COMPILED[role]
+  return rules.some(rule => rule.server === server && rule.test.test(rawName))
+}

package/src/protocol.ts

@@ -0,0 +1,133 @@
+/**
+ * Wire contract between the host half (routes.ts / mcp-host.ts) and the
+ * browser half (client/api.ts). Pure types only — imported by both halves,
+ * bundled into each, no runtime identity to share.
+ */
+
+/** MCP server id: arbitrary stable key, e.g. "odoo", "homeassistant". */
+export type RezServerId = string
+
+/** Agent role, the preset-loader key. */
+export type RezRoleId = 'engineer' | 'sales' | 'operations' | 'all'
+
+/** Transport kinds the in-plugin MCP host can connect. */
+export type RezMcpTransport = 'stdio' | 'streamable-http'
+
+/** One MCP server launch descriptor (standard MCP-style config). */
+export interface RezMcpServerSpec {
+  /** Master switch for this server. */
+  enabled: boolean
+  /** stdio or streamable-http. */
+  transport: RezMcpTransport
+  /** stdio executable (npx, uvx, node, absolute binary, ...). */
+  command?: string
+  /** stdio args passed without shell interpolation. */
+  args?: string[]
+  /** stdio env merged over the scrubbed parent env. */
+  env?: Record<string, string>
+  /** stdio working directory. */
+  cwd?: string
+  /** streamable-http endpoint URL. */
+  url?: string
+  /** streamable-http request headers (Authorization, ...). */
+  headers?: Record<string, string>
+  /** Per-tool-call timeout in milliseconds. */
+  toolCallTimeoutMs?: number
+}
+
+/** Full plugin configuration persisted under ~/.dsh/dsh-rez-suite.json. */
+export interface RezConfig {
+  enabled: boolean
+  announceToAgent: boolean
+  role: RezRoleId
+  servers: Record<string, RezMcpServerSpec>
+  billing: {
+    inputCostPer1k: number
+    outputCostPer1k: number
+    monthlyBudget: number
+  }
+}
+
+/** One server entry projected for the browser (secret values masked). */
+export type RezPublicServer = RezMcpServerSpec
+
+/** Config projection safe for the browser (env/header values replaced by masks). */
+export interface RezPublicConfig {
+  enabled: boolean
+  role: RezRoleId
+  servers: Record<string, RezPublicServer>
+  billing: { inputCostPer1k: number; outputCostPer1k: number; monthlyBudget: number }
+}
+
+/** One connectivity test outcome for one MCP server. */
+export interface RezTestResult {
+  server: RezServerId
+  ok: boolean
+  /** Connected, discovered tools, then closed. */
+  toolCount?: number
+  /** Server-reported name/version when available. */
+  serverInfo?: string
+  latencyMs?: number
+  error?: string
+}
+
+/** Live status of one MCP server slot. */
+export interface RezServerStatus {
+  server: RezServerId
+  enabled: boolean
+  state: 'disconnected' | 'connecting' | 'connected' | 'failed'
+  toolCount: number
+  registeredTools: number
+  lastError?: string
+  startedAt?: number
+}
+
+/** Complete /api/dsh-rez-suite/status response. */
+export interface RezStatusResponse {
+  role: RezRoleId
+  servers: RezServerStatus[]
+  totalRegisteredTools: number
+}
+
+/** One audit ledger row. */
+export interface RezAuditRecord {
+  id: number
+  ts: number
+  server: string
+  tool: string
+  role: string
+  inputTokens: number
+  outputTokens: number
+  cost: number
+  durationMs: number
+  ok: boolean
+  error?: string
+}
+
+/** /api/dsh-rez-suite/audit response. */
+export interface RezAuditResponse {
+  totalCalls: number
+  totalInputTokens: number
+  totalOutputTokens: number
+  totalCost: number
+  monthlyBudget: number
+  monthCost: number
+  byServer: Record<string, { calls: number; tokens: number; cost: number }>
+  recent: RezAuditRecord[]
+}
+
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+  error: string
+}
+
+/** Route paths the client calls (shared literals). */
+export const REZ_API_BASE = '/api/dsh-rez-suite' as const
+
+export const REZ_API = {
+  config: REZ_API_BASE + '/config',
+  test: REZ_API_BASE + '/test',
+  status: REZ_API_BASE + '/status',
+  audit: REZ_API_BASE + '/audit',
+  auditReset: REZ_API_BASE + '/audit/reset',
+} as const