dictum-cli 0.1.0

package/src/mcp/server.ts

@@ -0,0 +1,363 @@
+/**
+ * mcp/server.ts — expose Dictum's engine over MCP.
+ *
+ * Any MCP client (Claude Code, Cursor, Windsurf, Claude Desktop, Codex) can
+ * use Dictum without installing the CLI. Text-only — voice has no place in
+ * the MCP protocol (no microphone access).
+ *
+ * Prompts (the flagship, host-brain: the HOST model rewrites, using the
+ * session's project context — see prompts.ts):
+ *   - polish(draft?)    — draft → clear, structured prompt
+ *   - spec(draft?)      — draft → task spec with acceptance criteria
+ *   - decompose(draft?) — draft → ordered, dependency-tracked subtasks
+ *
+ * Tools:
+ *   - polish_brief(text, mode?) — the same host-brain brief as a tool result,
+ *                                 for hosts without MCP Prompts (Codex CLI)
+ *   - polish_prompt(text, mode?) — server-side polish with Dictum's own model
+ *   - analyze_prompt(text)      — deterministic 0–100 score + weak spots (offline)
+ *   - build_spec(text)          — server-side spec via the "spec" template
+ *
+ * This is an assembly-layer entry point (like cli.ts): it reuses createPolisher
+ * + resolveTemplate and never touches recorder/stt/sink. Started via `dictum mcp`.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js"
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
+import { ErrorCode, GetPromptRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js"
+import { z } from "zod"
+import pkg from "../../package.json" with { type: "json" }
+import { type Config, loadConfig, templatesDir } from "../config.ts"
+import { createPolisher } from "../polisher/factory.ts"
+import { analyzePrompt } from "../polisher/rules.ts"
+import { availableTemplateNames, resolveTemplate } from "../polisher/templates.ts"
+import {
+  HOST_PROMPT_KINDS,
+  HOST_PROMPT_META,
+  PROVIDER_FAMILIES,
+  type ProviderFamily,
+  buildHostBrief,
+  buildHostPrompt,
+  detectProviderFamily,
+  isHostPromptKind,
+  isProviderFamily,
+} from "./prompts.ts"
+
+/** Refines `text` with the given template `mode`; resolves to the polished text. */
+export type PolishFn = (text: string, mode?: string) => Promise<string>
+
+export type McpDeps = {
+  /** Polishing backend (real one from config, or a stub in tests). */
+  polish: PolishFn
+  /** Template names advertised in the tool description. */
+  modes: string[]
+}
+
+/** Build a text CallToolResult. */
+function textResult(text: string, isError = false): CallToolResult {
+  return { content: [{ type: "text", text }], isError }
+}
+
+// ── In-flight request tracking ──────────────────────────────────────────────
+// stdin EOF must not kill responses still being computed (an async tool like
+// polish_prompt awaits a subprocess). Handlers are wrapped in track(); the
+// EOF path awaits waitForIdle() before letting the process exit.
+
+let inflight = 0
+
+/** Wrap a handler so the in-flight counter reflects it. */
+export function track<A extends unknown[], R>(
+  fn: (...args: A) => R | Promise<R>,
+): (...args: A) => Promise<R> {
+  return async (...args: A): Promise<R> => {
+    inflight++
+    try {
+      return await fn(...args)
+    } finally {
+      inflight--
+    }
+  }
+}
+
+// The SDK hands a parsed request to its handler on a later microtask; on
+// Bun 1.2 stdin 'end' lands inside that gap, when no handler has started yet
+// and inflight is still 0. Idle is therefore also judged at the wire level:
+// every request the transport parsed must get its response before exit.
+const pendingWire = new Set<string | number>()
+
+/** Record a client→server wire message; requests (id + method) become pending. */
+export function noteWireMessage(message: unknown): void {
+  const m = message as { id?: unknown; method?: unknown } | null
+  if (m && typeof m.method === "string" && (typeof m.id === "string" || typeof m.id === "number")) {
+    pendingWire.add(m.id)
+  }
+}
+
+/** Record a server→client wire message; responses (id, no method) settle requests. */
+export function noteWireReply(message: unknown): void {
+  const m = message as { id?: unknown; method?: unknown } | null
+  if (m && m.method === undefined && (typeof m.id === "string" || typeof m.id === "number")) {
+    pendingWire.delete(m.id)
+  }
+}
+
+/**
+ * Wrap a connected transport so pendingWire mirrors the actual traffic.
+ * Must run after connect() — that is when the protocol assigns onmessage.
+ */
+export function instrumentWireTracking(transport: Transport): void {
+  const dispatch = transport.onmessage
+  transport.onmessage = (message, extra) => {
+    noteWireMessage(message)
+    dispatch?.(message, extra)
+  }
+  const sendRaw = transport.send.bind(transport)
+  transport.send = (message, options) => {
+    noteWireReply(message)
+    return sendRaw(message, options)
+  }
+}
+
+/** Resolve once no request is in flight or awaiting dispatch (or the drain timeout elapses). */
+export async function waitForIdle(timeoutMs = 15000): Promise<void> {
+  const deadline = Date.now() + timeoutMs
+  while ((inflight > 0 || pendingWire.size > 0) && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 25))
+  }
+}
+
+/**
+ * Core polish_prompt logic, decoupled from the transport for direct testing.
+ * Validates input and maps provider failures to a human-readable error result
+ * (isError) rather than throwing across the protocol boundary.
+ */
+export async function handlePolishPrompt(
+  args: { text?: unknown; mode?: unknown },
+  deps: McpDeps,
+): Promise<CallToolResult> {
+  const text = typeof args.text === "string" ? args.text.trim() : ""
+  if (!text) {
+    return textResult("Error: 'text' must be a non-empty string.", true)
+  }
+  const mode = typeof args.mode === "string" && args.mode.length > 0 ? args.mode : undefined
+  // Defense in depth on top of resolveTemplate's name validation: MCP callers
+  // may only pick from the advertised template list.
+  if (mode !== undefined && !deps.modes.includes(mode)) {
+    return textResult(`Error: unknown mode '${mode}'. Valid: ${deps.modes.join(", ")}.`, true)
+  }
+  try {
+    const polished = await deps.polish(text, mode)
+    return textResult(polished)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    return textResult(`Polishing failed: ${reason}`, true)
+  }
+}
+
+/**
+ * analyze_prompt logic: deterministic offline scoring — no LLM call, so it
+ * never fails on provider problems. Returns the analysis as a JSON string
+ * ({score, dimensions, issues}) for the client to reason over.
+ */
+export function handleAnalyzePrompt(args: { text?: unknown }): CallToolResult {
+  const text = typeof args.text === "string" ? args.text.trim() : ""
+  if (!text) {
+    return textResult("Error: 'text' must be a non-empty string.", true)
+  }
+  return textResult(JSON.stringify(analyzePrompt(text)))
+}
+
+/** build_spec logic: polish_prompt fixed to the "spec" template. */
+export async function handleBuildSpec(
+  args: { text?: unknown },
+  deps: McpDeps,
+): Promise<CallToolResult> {
+  return handlePolishPrompt({ text: args.text, mode: "spec" }, deps)
+}
+
+/**
+ * polish_brief logic: return the host-brain brief as a tool result, so hosts
+ * without MCP Prompts (Codex CLI) still get the flagship flow — the HOST model
+ * executes the brief with its own session context. Offline, no LLM call.
+ */
+export function handlePolishBrief(
+  args: { text?: unknown; mode?: unknown; provider?: unknown },
+  detected: ProviderFamily = "generic",
+): CallToolResult {
+  const text = typeof args.text === "string" ? args.text.trim() : ""
+  if (!text) {
+    return textResult("Error: 'text' must be a non-empty string.", true)
+  }
+  const mode = typeof args.mode === "string" && args.mode.length > 0 ? args.mode : "polish"
+  if (!isHostPromptKind(mode)) {
+    return textResult(
+      `Error: unknown brief mode '${mode}'. Valid: ${HOST_PROMPT_KINDS.join(", ")}.`,
+      true,
+    )
+  }
+  const provider =
+    typeof args.provider === "string" && args.provider.length > 0 ? args.provider : detected
+  if (!isProviderFamily(provider)) {
+    return textResult(
+      `Error: unknown provider '${provider}'. Valid: ${PROVIDER_FAMILIES.join(", ")}.`,
+      true,
+    )
+  }
+  return textResult(buildHostBrief(mode, text, provider))
+}
+
+/**
+ * Build a PolishFn from configuration. Constructs the polisher once and resolves
+ * the template per call (so different `mode` values work). Reuses the exact same
+ * createPolisher + resolveTemplate the CLI uses — no duplicated logic.
+ */
+export function polishFromConfig(config: Config): PolishFn {
+  const polisher = createPolisher(config.polisher)
+  return async (text, mode) => {
+    const template = await resolveTemplate(mode ?? config.polisher.template, templatesDir())
+    return polisher.polish(text, template)
+  }
+}
+
+/**
+ * Construct the MCP server: host-brain prompts (polish / spec / decompose,
+ * the flagship surface) plus the polish_brief / polish_prompt / analyze_prompt
+ * / build_spec tools.
+ */
+export function createMcpServer(deps: McpDeps): McpServer {
+  const server = new McpServer({ name: "dictum", version: pkg.version })
+  const modeList = deps.modes.join(", ")
+  const modeHelp = `Polishing template (one of: ${modeList}). Defaults to the configured template.`
+
+  // Model family of the connected host (known after `initialize`), so briefs
+  // can carry that vendor's own prompting advice — the polished prompt will
+  // be executed by the very model the client runs on.
+  const clientFamily = () => detectProviderFamily(server.server.getClientVersion()?.name)
+
+  // Host-brain prompts: the host model executes the brief with its own
+  // context. Surfaced as e.g. /mcp__dictum__polish in Claude Code.
+  for (const kind of HOST_PROMPT_KINDS) {
+    server.registerPrompt(
+      kind,
+      {
+        title: HOST_PROMPT_META[kind].title,
+        description: HOST_PROMPT_META[kind].description,
+        argsSchema: {
+          draft: z
+            .string()
+            .optional()
+            .describe("The rough draft to refine. If omitted, the host asks the user for it."),
+        },
+      },
+      ({ draft }) => buildHostPrompt(kind, draft ?? "", clientFamily()),
+    )
+  }
+
+  // The MCP spec makes `params.arguments` optional, but the SDK's generated
+  // prompts/get handler rejects a request that omits it (-32602) — which
+  // would kill our "no draft → ask the user" flow on spec-compliant clients.
+  // Override just the get handler; registerPrompt above still owns
+  // prompts/list (names, titles, argument advertising).
+  server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
+    const { name } = request.params
+    if (!isHostPromptKind(name)) {
+      throw new McpError(ErrorCode.InvalidParams, `Prompt ${name} not found`)
+    }
+    const draft = request.params.arguments?.draft
+    return buildHostPrompt(name, typeof draft === "string" ? draft : "", clientFamily())
+  })
+
+  server.registerTool(
+    "polish_brief",
+    {
+      title: "Get a polishing brief (host-executed)",
+      description:
+        "Return Dictum's rewriting brief for YOU to execute: canon rules plus a deterministic pre-analysis of the user's rough draft. Follow the brief yourself, using your session's project context — do not expect polished text back from this tool. Prefer this over polish_prompt when the user wants their draft refined and you have the context. Offline, no LLM call. Modes: polish (default), spec, decompose.",
+      inputSchema: {
+        text: z.string().describe("The rough draft to build the brief for."),
+        mode: z.string().optional().describe("Brief kind: polish (default), spec, or decompose."),
+        provider: z
+          .string()
+          .optional()
+          .describe(
+            "Model family for vendor prompting tips: anthropic, openai, or generic. Auto-detected from the connected client when omitted.",
+          ),
+      },
+    },
+    track((args) => handlePolishBrief(args, clientFamily())),
+  )
+
+  server.registerTool(
+    "polish_prompt",
+    {
+      title: "Polish a prompt",
+      description: `Refine a rough thought or draft into a clear, well-structured prompt using Dictum's OWN model, server-side (it does not see this session's context — prefer polish_brief when you have context). Text in, polished text out (no voice). Available modes: ${modeList}.`,
+      inputSchema: {
+        text: z.string().describe("The rough thought or draft prompt to refine."),
+        mode: z.string().optional().describe(modeHelp),
+      },
+    },
+    track((args) => handlePolishPrompt(args, deps)),
+  )
+
+  server.registerTool(
+    "analyze_prompt",
+    {
+      title: "Analyze a prompt",
+      description:
+        "Score a prompt draft 0–100 across five dimensions (clarity, specificity, structure, actionability, context) and list its weak spots. Deterministic and offline — no LLM call. Returns JSON: {score, dimensions, issues}. Use it to decide whether a draft needs polishing.",
+      inputSchema: {
+        text: z.string().describe("The prompt draft to analyze."),
+      },
+    },
+    track((args) => handleAnalyzePrompt(args)),
+  )
+
+  server.registerTool(
+    "build_spec",
+    {
+      title: "Build a task spec",
+      description:
+        "Expand a rough thought into a compact task spec with requirements and acceptance criteria (Dictum's 'spec' template). Text in, Markdown spec out.",
+      inputSchema: {
+        text: z.string().describe("The rough task description to expand into a spec."),
+      },
+    },
+    track((args) => handleBuildSpec(args, deps)),
+  )
+
+  return server
+}
+
+/**
+ * Load config, wire the real polisher, and serve over stdio. Stays alive until
+ * the client disconnects (stdin EOF) or the process is signalled. stdout is the
+ * protocol channel, so all logging goes to stderr.
+ */
+export async function startMcpServer(): Promise<void> {
+  const config = await loadConfig()
+  const modes = await availableTemplateNames(templatesDir())
+  const server = createMcpServer({ polish: polishFromConfig(config), modes })
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+  instrumentWireTracking(transport)
+  process.stderr.write("dictum mcp: host-brain prompts + tools ready on stdio\n")
+
+  await new Promise<void>((resolve) => {
+    const done = () => resolve()
+    transport.onclose = done
+    // The SDK transport does not surface stdin EOF as onclose — watch the
+    // stream directly so `printf … | dictum mcp` exits when the pipe closes.
+    // Drain in-flight requests first: killing a response mid-computation
+    // would return exit 0 with no output.
+    const drainThenDone = () => {
+      waitForIdle().then(done)
+    }
+    process.stdin.once("end", drainThenDone)
+    process.stdin.once("close", drainThenDone)
+    process.once("SIGINT", done)
+    process.once("SIGTERM", done)
+  })
+}

package/src/modules.d.ts

@@ -0,0 +1,7 @@
+// Ambient declarations for non-code imports embedded by Bun.
+
+// Markdown templates imported as text: `import x from "./t.md" with { type: "text" }`
+declare module "*.md" {
+  const content: string
+  export default content
+}

package/src/polisher/anthropic.ts

@@ -0,0 +1,90 @@
+/**
+ * polisher/anthropic.ts — Polisher backed by the Claude Messages API.
+ *
+ * Raw HTTP (fetch) to keep dependencies minimal, mirroring stt/openai_compat.ts.
+ *   POST {base}/v1/messages
+ *   headers: x-api-key, anthropic-version: 2023-06-01, content-type
+ *   body: { model, max_tokens, system, messages: [{role:"user", content}] }
+ *   response: { content: [{type:"text", text}], stop_reason, ... }
+ */
+
+import type { Polisher, Template } from "../core/types.ts"
+
+const ANTHROPIC_VERSION = "2023-06-01"
+
+export type AnthropicOptions = {
+  apiKey: string
+  model: string
+  baseUrl: string
+  /** Max output tokens; polished prompts are short. */
+  maxTokens?: number
+  /** Request timeout in milliseconds. */
+  timeoutMs?: number
+}
+
+type AnthropicResponse = {
+  content?: Array<{ type?: string; text?: string }>
+  stop_reason?: string
+  error?: { message?: string }
+}
+
+export class AnthropicPolisher implements Polisher {
+  private readonly apiKey: string
+  private readonly model: string
+  private readonly baseUrl: string
+  private readonly maxTokens: number
+  private readonly timeoutMs: number
+
+  constructor(opts: AnthropicOptions) {
+    this.apiKey = opts.apiKey
+    this.model = opts.model
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "")
+    this.maxTokens = opts.maxTokens ?? 2048
+    this.timeoutMs = opts.timeoutMs ?? 60000
+  }
+
+  async polish(text: string, template: Template): Promise<string> {
+    if (!this.apiKey) {
+      throw new Error("Anthropic polisher needs an API key — set ANTHROPIC_API_KEY")
+    }
+
+    let res: Response
+    try {
+      res = await fetch(`${this.baseUrl}/v1/messages`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-api-key": this.apiKey,
+          "anthropic-version": ANTHROPIC_VERSION,
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: this.maxTokens,
+          system: template.instruction,
+          messages: [{ role: "user", content: text }],
+        }),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      })
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      throw new Error(`Anthropic request failed: ${reason}`)
+    }
+
+    const body = (await res.json().catch(() => ({}))) as AnthropicResponse
+    if (!res.ok) {
+      const detail = body.error?.message ?? (await res.text().catch(() => "")).trim()
+      throw new Error(`Anthropic API returned ${res.status}${detail ? `: ${detail}` : ""}`)
+    }
+    if (body.stop_reason === "refusal") {
+      throw new Error("Anthropic declined to polish this transcript (safety refusal)")
+    }
+
+    const out = (body.content ?? [])
+      .filter((b) => b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text)
+      .join("")
+      .trim()
+    if (!out) throw new Error("Anthropic returned an empty response")
+    return out
+  }
+}

package/src/polisher/claude_cli.ts

@@ -0,0 +1,128 @@
+/**
+ * polisher/claude_cli.ts — Polisher that shells out to the `claude` CLI.
+ *
+ * Runs `claude -p --output-format text` with the instruction + transcript
+ * piped via stdin (never argv: transcripts must not leak into the process
+ * list — /proc/<pid>/cmdline is world-readable on the same host). Uses the
+ * user's existing Claude Code auth (subscription), so no API key is needed.
+ * The instruction comes from the selected Template.
+ *
+ * Least privilege: the polisher is a pure text-in/text-out call, so the CLI
+ * runs with --safe-mode (no CLAUDE.md, hooks, plugins, MCP servers, skills),
+ * --no-session-persistence (no transcript saved to disk) and all standard
+ * tools denied. Project-aware polishing is the host-brain MCP path's job,
+ * not this subprocess's.
+ */
+
+import type { Polisher, Template } from "../core/types.ts"
+
+/**
+ * Oldest Claude Code that understands every safety flag below (--safe-mode
+ * shipped in 2.1.169). doctor checks the installed CLI against this.
+ */
+export const CLAUDE_CLI_MIN_VERSION = "2.1.169"
+
+/** Compare dotted numeric versions; true when `a >= b`. Pure, for testing. */
+export function versionAtLeast(a: string, b: string): boolean {
+  const pa = a.split(".").map(Number)
+  const pb = b.split(".").map(Number)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] ?? 0
+    const y = pb[i] ?? 0
+    if (x !== y) return x > y
+  }
+  return true
+}
+
+/**
+ * Hardening flags every polisher invocation carries (pinned by tests).
+ * `--tools ""` disables ALL tools (future-proof); the denylist stays as a
+ * second belt for CLI versions where the empty allowlist is advisory.
+ */
+export const CLAUDE_CLI_SAFETY_ARGS = [
+  "--safe-mode",
+  "--no-session-persistence",
+  "--tools",
+  "",
+  "--disallowedTools",
+  "Bash,Edit,Write,Read,Glob,Grep,WebFetch,WebSearch,Task,NotebookEdit",
+] as const
+
+export type ClaudeCliOptions = {
+  /** Binary name/path; defaults to "claude". */
+  bin?: string
+  /** Optional model override (empty = CLI default). */
+  model?: string
+  /** Timeout in milliseconds. */
+  timeoutMs?: number
+}
+
+export class ClaudeCliPolisher implements Polisher {
+  private readonly bin: string
+  private readonly model: string
+  private readonly timeoutMs: number
+
+  constructor(opts: ClaudeCliOptions = {}) {
+    this.bin = opts.bin ?? "claude"
+    this.model = opts.model ?? ""
+    this.timeoutMs = opts.timeoutMs ?? 60000
+  }
+
+  async polish(text: string, template: Template): Promise<string> {
+    const prompt = `${template.instruction}\n${text}`
+    const args = ["-p", "--output-format", "text", ...CLAUDE_CLI_SAFETY_ARGS]
+    if (this.model) args.push("--model", this.model)
+
+    const spawn = () => {
+      try {
+        return Bun.spawn([this.bin, ...args], {
+          stdin: new TextEncoder().encode(prompt),
+          stdout: "pipe",
+          stderr: "pipe",
+        })
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err)
+        throw new Error(
+          `Cannot launch '${this.bin}': ${reason}. Is the Claude CLI installed and on PATH?`,
+        )
+      }
+    }
+    const proc = spawn()
+
+    // Manual timeout: SIGTERM at the deadline, SIGKILL after a grace, so a
+    // child that holds the stdout/stderr pipes open can't make us hang. We
+    // never block on pipe EOF past the process exit (bounded reads below).
+    let timedOut = false
+    const sigtermTimer = setTimeout(() => {
+      timedOut = true
+      proc.kill("SIGTERM")
+    }, this.timeoutMs)
+    const sigkillTimer = setTimeout(() => proc.kill("SIGKILL"), this.timeoutMs + 2000)
+
+    const stdoutText = new Response(proc.stdout).text().catch(() => "")
+    const stderrText = new Response(proc.stderr).text().catch(() => "")
+
+    const code = await proc.exited
+    clearTimeout(sigtermTimer)
+    clearTimeout(sigkillTimer)
+
+    // Don't let a lingering grandchild's open pipe hang us: cap the reads.
+    const bounded = (p: Promise<string>): Promise<string> =>
+      Promise.race([p, new Promise<string>((resolve) => setTimeout(() => resolve(""), 1000))])
+    const stdout = await bounded(stdoutText)
+    const stderr = await bounded(stderrText)
+
+    if (timedOut) {
+      throw new Error(`claude polishing timed out after ${this.timeoutMs / 1000}s`)
+    }
+    if (code !== 0) {
+      throw new Error(
+        `claude exited with code ${code}: ${stderr.trim() || stdout.trim() || "no output"}`,
+      )
+    }
+
+    const result = stdout.trim()
+    if (!result) throw new Error("claude returned an empty response")
+    return result
+  }
+}

package/src/polisher/factory.ts

@@ -0,0 +1,89 @@
+/**
+ * polisher/factory.ts — build a Polisher from configuration.
+ *
+ * Validates the provider name (human-readable error on a bad config/env value)
+ * and constructs the matching backend. Imports only core/types.ts and sibling
+ * polisher files (own module).
+ */
+
+import type { Polisher } from "../core/types.ts"
+import { AnthropicPolisher } from "./anthropic.ts"
+import { ClaudeCliPolisher } from "./claude_cli.ts"
+import { LayeredPolisher, RulesPolisher } from "./layered.ts"
+import { OpenAiCompatPolisher } from "./openai_compat.ts"
+
+export const VALID_POLISHERS = ["claude_cli", "anthropic", "openai_compat"] as const
+export type PolisherName = (typeof VALID_POLISHERS)[number]
+
+export const VALID_POLISHER_MODES = ["llm", "rules", "layered"] as const
+export type PolisherMode = (typeof VALID_POLISHER_MODES)[number]
+
+/** Layered mode: skip the LLM when the draft scores ≥ this (0–100). */
+const DEFAULT_SCORE_THRESHOLD = 80
+
+/** Structural config the factory needs (mirrors Config["polisher"], no import). */
+export type PolisherFactoryConfig = {
+  provider: string
+  /** Polishing mode; optional for back-compat, defaults to "llm". */
+  mode?: string
+  /** Layered-mode gate (0–100); defaults to 80. */
+  scoreThreshold?: number
+  claude_cli: { bin: string; model: string; timeout: number }
+  anthropic: { apiKey: string; model: string; baseUrl: string }
+  openai_compat: { apiKey: string; model: string; baseUrl: string }
+}
+
+function isValidName(name: string): name is PolisherName {
+  return (VALID_POLISHERS as readonly string[]).includes(name)
+}
+
+function isValidMode(mode: string): mode is PolisherMode {
+  return (VALID_POLISHER_MODES as readonly string[]).includes(mode)
+}
+
+/**
+ * Construct the configured Polisher; throws on an unknown provider or mode.
+ * Mode "rules" is fully offline and needs no provider at all; "layered" wraps
+ * the configured provider behind the rule-based score gate.
+ */
+export function createPolisher(cfg: PolisherFactoryConfig): Polisher {
+  const mode = cfg.mode ?? "llm"
+  if (!isValidMode(mode)) {
+    throw new Error(`Unknown polisher mode '${mode}'. Valid: ${VALID_POLISHER_MODES.join(", ")}`)
+  }
+  if (mode === "rules") return new RulesPolisher()
+
+  if (!isValidName(cfg.provider)) {
+    throw new Error(`Unknown polisher '${cfg.provider}'. Valid: ${VALID_POLISHERS.join(", ")}`)
+  }
+  const base = createProvider(cfg, cfg.provider)
+  if (mode === "layered") {
+    return new LayeredPolisher(base, {
+      scoreThreshold: cfg.scoreThreshold ?? DEFAULT_SCORE_THRESHOLD,
+    })
+  }
+  return base
+}
+
+function createProvider(cfg: PolisherFactoryConfig, provider: PolisherName): Polisher {
+  switch (provider) {
+    case "claude_cli":
+      return new ClaudeCliPolisher({
+        bin: cfg.claude_cli.bin,
+        model: cfg.claude_cli.model,
+        timeoutMs: cfg.claude_cli.timeout * 1000,
+      })
+    case "anthropic":
+      return new AnthropicPolisher({
+        apiKey: cfg.anthropic.apiKey,
+        model: cfg.anthropic.model,
+        baseUrl: cfg.anthropic.baseUrl,
+      })
+    case "openai_compat":
+      return new OpenAiCompatPolisher({
+        apiKey: cfg.openai_compat.apiKey,
+        model: cfg.openai_compat.model,
+        baseUrl: cfg.openai_compat.baseUrl,
+      })
+  }
+}