tower-studio 0.1.2 → 0.1.5

package/.next/standalone/tower/docs/ai/cli-abstraction-plan.md

@@ -1,1345 +0,0 @@
-# CLI 抽象层 Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Extract Claude Code CLI hardcoded logic into a provider-agnostic adapter layer, preserving all existing functionality.
-
-**Architecture:** Strategy pattern for CLI adapters (PTY execution) + generic adapters for AI queries. A ProviderRegistry maps provider names to adapters. A capability-resolver reads DB config to route each AI slot to the correct adapter.
-
-**Tech Stack:** TypeScript, Prisma (SQLite), Next.js 16 server actions, node-pty, @anthropic-ai/claude-agent-sdk
-
-**Spec:** `docs/ai/cli-abstraction-design.md`
-
----
-
-### Task 1: Define types and error classes
-
-**Files:**
-- Create: `src/lib/ai/types.ts`
-
-- [ ] **Step 1: Create the types file with all interfaces**
-
-```typescript
-// src/lib/ai/types.ts
-
-// ---------------------------------------------------------------------------
-// CLI Adapter — PTY execution layer
-// ---------------------------------------------------------------------------
-
-export interface CliSpawnOptions {
-  taskId: string;
-  prompt: string;
-  cwd: string;
-  envOverrides?: Record<string, string>;
-  resumeSessionId?: string;
-  continueLatest?: boolean;
-  worktreePath?: string;
-  profileArgs?: string[];
-  profileEnvVars?: Record<string, string>;
-}
-
-export interface CliSpawnResult {
-  command: string;
-  args: string[];
-  env: Record<string, string>;
-  /** Gemini: spawn 后通过 PTY write 发送初始 prompt */
-  initialInput?: string;
-}
-
-export interface CliAdapter {
-  buildSpawnArgs(opts: CliSpawnOptions): CliSpawnResult;
-
-  buildEnvOverrides(opts: {
-    taskId: string;
-    taskTitle: string;
-    apiUrl: string;
-    callbackUrl?: string;
-  }): Record<string, string>;
-
-  installHooks(apiUrl: string): Promise<void>;
-  uninstallHooks(): Promise<void>;
-  isHooksInstalled(): Promise<boolean>;
-
-  isAvailable(): Promise<boolean>;
-  getVersion(): Promise<string | null>;
-  getModels(): Promise<string[]>;
-
-  getConfigDir(): string;
-  getSettingsPath(): string;
-  getSessionsDir(): string;
-}
-
-// ---------------------------------------------------------------------------
-// AI Query Adapter — single-turn and streaming queries
-// ---------------------------------------------------------------------------
-
-export interface AiQueryOptions {
-  prompt: string;
-  cwd?: string;
-  systemPrompt?: string;
-  model?: string;
-  maxTurns?: number;
-  tools?: string[];
-  allowedTools?: string[];
-}
-
-export interface AiQueryResult {
-  content: string | null;
-  usage?: { inputTokens: number; outputTokens: number };
-}
-
-export interface AiQueryChunk {
-  type: "text" | "tool_use" | "tool_result" | "error";
-  content: string;
-}
-
-export interface AiQueryAdapter {
-  query(opts: AiQueryOptions): Promise<AiQueryResult>;
-  queryStream?(opts: AiQueryOptions): AsyncIterable<AiQueryChunk>;
-
-  isAvailable(): Promise<boolean>;
-  getModels(): Promise<string[]>;
-}
-
-// ---------------------------------------------------------------------------
-// Provider definition & registry types
-// ---------------------------------------------------------------------------
-
-export interface ProviderDefinition {
-  name: string;
-  displayName: string;
-  agentFieldValue: string;
-
-  cli?: {
-    command: string;
-    adapter: CliAdapter;
-  };
-  api?: {
-    keyEnvVar: string;
-    adapter: AiQueryAdapter;
-  };
-  cliQuery?: {
-    adapter: AiQueryAdapter;
-  };
-
-  models: {
-    cli: string[];
-    api: string[];
-  };
-}
-
-export interface ProviderAvailability {
-  name: string;
-  displayName: string;
-  cli: { available: boolean; version: string | null };
-  api: { available: boolean; keyConfigured: boolean };
-}
-
-// ---------------------------------------------------------------------------
-// Capability slot config (mirrors Prisma model)
-// ---------------------------------------------------------------------------
-
-export type AiSlot = "terminal" | "summary" | "dreaming" | "analysis" | "assistant";
-
-export interface AiSlotConfig {
-  slot: AiSlot;
-  provider: string;
-  mode: "cli" | "api";
-  model?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Errors
-// ---------------------------------------------------------------------------
-
-export type AiProviderErrorCode =
-  | "CLI_NOT_FOUND"
-  | "API_KEY_MISSING"
-  | "MODEL_NOT_AVAILABLE"
-  | "RATE_LIMITED"
-  | "NETWORK_ERROR"
-  | "UNSUPPORTED_MODE"
-  | "SPAWN_FAILED";
-
-export class AiProviderError extends Error {
-  constructor(
-    public code: AiProviderErrorCode,
-    public provider: string,
-    message: string,
-  ) {
-    super(message);
-    this.name = "AiProviderError";
-  }
-}
-```
-
-- [ ] **Step 2: Verify TypeScript compiles**
-
-Run: `cd /Users/liujunping/project/f/tower && npx tsc --noEmit src/lib/ai/types.ts 2>&1 | head -20`
-Expected: No errors (file is self-contained, no imports needed)
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/lib/ai/types.ts
-git commit -m "feat(ai): define CLI adapter and AI query adapter interfaces"
-```
-
----
-
-### Task 2: Implement ClaudeCliAdapter
-
-**Files:**
-- Create: `src/lib/ai/adapters/cli/claude-cli-adapter.ts`
-- Reference: `src/actions/agent-actions.ts:194-236` (resume args), `src/actions/agent-actions.ts:598-620` (env + args), `src/app/api/internal/hooks/install/route.ts` (hook install)
-
-- [ ] **Step 1: Write the failing test**
-
-Create: `src/lib/ai/__tests__/claude-cli-adapter.test.ts`
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { ClaudeCliAdapter } from "../adapters/cli/claude-cli-adapter";
-import type { CliSpawnOptions } from "../types";
-
-describe("ClaudeCliAdapter", () => {
-  let adapter: ClaudeCliAdapter;
-
-  beforeEach(() => {
-    adapter = new ClaudeCliAdapter();
-  });
-
-  describe("buildSpawnArgs", () => {
-    const baseOpts: CliSpawnOptions = {
-      taskId: "ctask123456789012345678",
-      prompt: "Fix the bug",
-      cwd: "/project",
-    };
-
-    it("builds fresh start args with prompt as last argument", () => {
-      const result = adapter.buildSpawnArgs(baseOpts);
-      expect(result.command).toBe("claude");
-      expect(result.args[result.args.length - 1]).toBe("Fix the bug");
-      expect(result.initialInput).toBeUndefined();
-    });
-
-    it("builds resume args with --resume flag", () => {
-      const result = adapter.buildSpawnArgs({
-        ...baseOpts,
-        resumeSessionId: "session-abc-123",
-      });
-      expect(result.args).toContain("--resume");
-      expect(result.args).toContain("session-abc-123");
-      // resume mode should NOT include prompt as argument
-      expect(result.args[result.args.length - 1]).not.toBe("Fix the bug");
-    });
-
-    it("builds continue args with --continue flag and no prompt", () => {
-      const result = adapter.buildSpawnArgs({
-        ...baseOpts,
-        continueLatest: true,
-      });
-      expect(result.args).toContain("--continue");
-      // continue mode should NOT include prompt as argument
-      expect(result.args).not.toContain("Fix the bug");
-    });
-
-    it("merges profileArgs into args", () => {
-      const result = adapter.buildSpawnArgs({
-        ...baseOpts,
-        profileArgs: ["--model", "opus"],
-      });
-      expect(result.args).toContain("--model");
-      expect(result.args).toContain("opus");
-    });
-
-    it("merges profileEnvVars into env", () => {
-      const result = adapter.buildSpawnArgs({
-        ...baseOpts,
-        profileEnvVars: { CUSTOM_VAR: "value" },
-      });
-      expect(result.env.CUSTOM_VAR).toBe("value");
-    });
-  });
-
-  describe("buildEnvOverrides", () => {
-    it("returns TOWER_* env vars", () => {
-      const env = adapter.buildEnvOverrides({
-        taskId: "ctask123",
-        taskTitle: "Test task",
-        apiUrl: "http://localhost:3000",
-      });
-      expect(env.TOWER_TASK_ID).toBe("ctask123");
-      expect(env.TOWER_TASK_TITLE).toBe("Test task");
-      expect(env.TOWER_API_URL).toBe("http://localhost:3000");
-      expect(env.TOWER_STARTED_AT).toBeDefined();
-    });
-
-    it("includes CALLBACK_URL when provided", () => {
-      const env = adapter.buildEnvOverrides({
-        taskId: "ctask123",
-        taskTitle: "Test",
-        apiUrl: "http://localhost:3000",
-        callbackUrl: "http://external/callback",
-      });
-      expect(env.CALLBACK_URL).toBe("http://external/callback");
-    });
-
-    it("omits CALLBACK_URL when not provided", () => {
-      const env = adapter.buildEnvOverrides({
-        taskId: "ctask123",
-        taskTitle: "Test",
-        apiUrl: "http://localhost:3000",
-      });
-      expect(env.CALLBACK_URL).toBeUndefined();
-    });
-  });
-
-  describe("metadata", () => {
-    it("returns correct config paths", () => {
-      expect(adapter.getConfigDir()).toContain(".claude");
-      expect(adapter.getSettingsPath()).toContain("settings.json");
-      expect(adapter.getSessionsDir()).toContain("projects");
-    });
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/lib/ai/__tests__/claude-cli-adapter.test.ts 2>&1 | tail -20`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement ClaudeCliAdapter**
-
-```typescript
-// src/lib/ai/adapters/cli/claude-cli-adapter.ts
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { resolveCommandPathSync } from "@/lib/platform";
-import type { CliAdapter, CliSpawnOptions, CliSpawnResult } from "../../types";
-
-/** Known Claude Code model aliases (static — CLI has no list command) */
-const CLAUDE_MODELS = ["sonnet", "opus", "haiku", "claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5-20251001"];
-
-export class ClaudeCliAdapter implements CliAdapter {
-
-  // -- spawn args ----------------------------------------------------------
-
-  buildSpawnArgs(opts: CliSpawnOptions): CliSpawnResult {
-    const args: string[] = [];
-
-    // Profile args first (e.g. --model, --dangerously-skip-permissions)
-    if (opts.profileArgs?.length) {
-      args.push(...opts.profileArgs);
-    }
-
-    // Mode: resume / continue / fresh
-    if (opts.resumeSessionId) {
-      args.push("--resume", opts.resumeSessionId);
-    } else if (opts.continueLatest) {
-      args.push("--continue");
-    } else {
-      // Fresh start: prompt as last argument
-      if (opts.prompt) {
-        args.push(opts.prompt);
-      }
-    }
-
-    // Env: merge profile vars (adapter env built separately via buildEnvOverrides)
-    const env: Record<string, string> = {
-      ...(opts.profileEnvVars ?? {}),
-      ...(opts.envOverrides ?? {}),
-    };
-
-    return {
-      command: this.resolveCommand(),
-      args,
-      env,
-    };
-  }
-
-  // -- env overrides -------------------------------------------------------
-
-  buildEnvOverrides(opts: {
-    taskId: string;
-    taskTitle: string;
-    apiUrl: string;
-    callbackUrl?: string;
-  }): Record<string, string> {
-    const env: Record<string, string> = {
-      TOWER_TASK_ID: opts.taskId,
-      TOWER_TASK_TITLE: opts.taskTitle,
-      TOWER_STARTED_AT: new Date().toISOString(),
-      TOWER_API_URL: opts.apiUrl,
-    };
-    if (opts.callbackUrl) {
-      env.CALLBACK_URL = opts.callbackUrl;
-    }
-    return env;
-  }
-
-  // -- hooks ---------------------------------------------------------------
-
-  async installHooks(apiUrl: string): Promise<void> {
-    const settings = this.readSettings();
-    const hooks = (settings["hooks"] as Record<string, unknown>) ?? {};
-    const entries = this.getPostToolUseArray(settings);
-
-    if (this.findTowerHookIndex(entries) >= 0) return; // already installed
-
-    const hookPath = path.join(process.cwd(), "scripts", "post-tool-hook.js");
-    const newEntry = {
-      hooks: [{ command: `node "${hookPath}"`, timeout: 10, type: "command" }],
-      matcher: "Write|Edit|MultiEdit",
-    };
-
-    settings["hooks"] = { ...hooks, PostToolUse: [...entries, newEntry] };
-    this.writeSettings(settings);
-  }
-
-  async uninstallHooks(): Promise<void> {
-    const settings = this.readSettings();
-    const hooks = (settings["hooks"] as Record<string, unknown>) ?? {};
-    const entries = this.getPostToolUseArray(settings);
-    const filtered = entries.filter(
-      (e) => !e.hooks?.some((h: { command?: string }) => h.command?.includes("post-tool-hook.js"))
-    );
-    settings["hooks"] = { ...hooks, PostToolUse: filtered };
-    this.writeSettings(settings);
-  }
-
-  async isHooksInstalled(): Promise<boolean> {
-    const settings = this.readSettings();
-    const entries = this.getPostToolUseArray(settings);
-    return this.findTowerHookIndex(entries) >= 0;
-  }
-
-  // -- capability detection ------------------------------------------------
-
-  async isAvailable(): Promise<boolean> {
-    const version = await this.getVersion();
-    return version !== null;
-  }
-
-  async getVersion(): Promise<string | null> {
-    try {
-      const { execFile } = await import("child_process");
-      const { promisify } = await import("util");
-      const execFileAsync = promisify(execFile);
-      const cmd = this.resolveCommand();
-      const { stdout } = await execFileAsync(cmd, ["--version"], { timeout: 5000 });
-      return stdout.trim() || null;
-    } catch {
-      return null;
-    }
-  }
-
-  async getModels(): Promise<string[]> {
-    return CLAUDE_MODELS;
-  }
-
-  // -- paths ---------------------------------------------------------------
-
-  getConfigDir(): string {
-    return path.join(os.homedir(), ".claude");
-  }
-
-  getSettingsPath(): string {
-    return path.join(this.getConfigDir(), "settings.json");
-  }
-
-  getSessionsDir(): string {
-    return path.join(this.getConfigDir(), "projects");
-  }
-
-  // -- private helpers -----------------------------------------------------
-
-  /** Resolve claude binary — env var > platform-aware resolution.
-   *  Consolidates duplicate findClaudeBinary() from claude-session.ts + assistant route. */
-  /** Resolve claude binary — env var > platform-aware resolution.
-   *  Public so claude-session.ts can reuse instead of duplicating findClaudeBinary(). */
-  resolveCommand(): string {
-    if (process.env.CLAUDE_CODE_PATH) return process.env.CLAUDE_CODE_PATH;
-    if (process.platform === "win32") {
-      const native = resolveCommandPathSync("claude-code");
-      if (native !== "claude-code") return native;
-    }
-    return resolveCommandPathSync("claude");
-  }
-
-  private readSettings(): Record<string, unknown> {
-    try {
-      return JSON.parse(fs.readFileSync(this.getSettingsPath(), "utf-8")) as Record<string, unknown>;
-    } catch {
-      return {};
-    }
-  }
-
-  private writeSettings(data: Record<string, unknown>): void {
-    const dir = this.getConfigDir();
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(this.getSettingsPath(), JSON.stringify(data, null, 2), "utf-8");
-  }
-
-  private getPostToolUseArray(settings: Record<string, unknown>): Array<{
-    hooks: Array<{ command: string; timeout: number; type: string }>;
-    matcher: string;
-  }> {
-    const hooks = settings["hooks"] as Record<string, unknown> | undefined;
-    if (!hooks) return [];
-    const arr = hooks["PostToolUse"];
-    return Array.isArray(arr) ? arr : [];
-  }
-
-  private findTowerHookIndex(entries: Array<{ hooks: Array<{ command?: string }> }>): number {
-    return entries.findIndex((e) =>
-      e.hooks?.some((h) => h.command?.includes("post-tool-hook.js"))
-    );
-  }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/lib/ai/__tests__/claude-cli-adapter.test.ts 2>&1 | tail -20`
-Expected: All tests PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/lib/ai/adapters/cli/claude-cli-adapter.ts src/lib/ai/__tests__/claude-cli-adapter.test.ts
-git commit -m "feat(ai): implement ClaudeCliAdapter with tests"
-```
-
----
-
-### Task 3: Implement ProviderRegistry
-
-**Files:**
-- Create: `src/lib/ai/provider-registry.ts`
-- Create: `src/lib/ai/providers/claude.ts`
-- Create: `src/lib/ai/providers/index.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-Create: `src/lib/ai/__tests__/provider-registry.test.ts`
-
-```typescript
-import { describe, it, expect, beforeEach } from "vitest";
-import { ProviderRegistry } from "../provider-registry";
-import type { ProviderDefinition } from "../types";
-import { ClaudeCliAdapter } from "../adapters/cli/claude-cli-adapter";
-
-function makeClaudeProvider(): ProviderDefinition {
-  return {
-    name: "claude",
-    displayName: "Claude Code",
-    agentFieldValue: "CLAUDE_CODE",
-    cli: {
-      command: "claude",
-      adapter: new ClaudeCliAdapter(),
-    },
-    models: {
-      cli: ["sonnet", "opus", "haiku"],
-      api: [],
-    },
-  };
-}
-
-describe("ProviderRegistry", () => {
-  let registry: ProviderRegistry;
-
-  beforeEach(() => {
-    registry = new ProviderRegistry();
-  });
-
-  it("registers and retrieves a provider", () => {
-    registry.register(makeClaudeProvider());
-    const provider = registry.get("claude");
-    expect(provider).toBeDefined();
-    expect(provider!.displayName).toBe("Claude Code");
-  });
-
-  it("returns undefined for unknown provider", () => {
-    expect(registry.get("unknown")).toBeUndefined();
-  });
-
-  it("returns CLI adapter for registered provider", () => {
-    registry.register(makeClaudeProvider());
-    const adapter = registry.getCliAdapter("claude");
-    expect(adapter).toBeDefined();
-  });
-
-  it("returns null CLI adapter for provider without CLI", () => {
-    registry.register({
-      ...makeClaudeProvider(),
-      name: "api-only",
-      cli: undefined,
-    });
-    expect(registry.getCliAdapter("api-only")).toBeNull();
-  });
-
-  it("returns all allowed commands from registered CLI providers", () => {
-    registry.register(makeClaudeProvider());
-    expect(registry.getAllowedCommands()).toContain("claude");
-  });
-
-  it("lists all providers", () => {
-    registry.register(makeClaudeProvider());
-    expect(registry.getAll()).toHaveLength(1);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/lib/ai/__tests__/provider-registry.test.ts 2>&1 | tail -20`
-Expected: FAIL
-
-- [ ] **Step 3: Implement ProviderRegistry**
-
-```typescript
-// src/lib/ai/provider-registry.ts
-
-import type { CliAdapter, AiQueryAdapter, ProviderDefinition, ProviderAvailability } from "./types";
-
-export class ProviderRegistry {
-  private providers = new Map<string, ProviderDefinition>();
-
-  register(provider: ProviderDefinition): void {
-    this.providers.set(provider.name, provider);
-  }
-
-  get(name: string): ProviderDefinition | undefined {
-    return this.providers.get(name);
-  }
-
-  getAll(): ProviderDefinition[] {
-    return Array.from(this.providers.values());
-  }
-
-  getCliAdapter(name: string): CliAdapter | null {
-    return this.providers.get(name)?.cli?.adapter ?? null;
-  }
-
-  getQueryAdapter(name: string, mode: "api" | "cli"): AiQueryAdapter | null {
-    const provider = this.providers.get(name);
-    if (!provider) return null;
-    if (mode === "api") return provider.api?.adapter ?? null;
-    return provider.cliQuery?.adapter ?? null;
-  }
-
-  /** Returns all CLI command names from registered providers (for security allowlist). */
-  getAllowedCommands(): string[] {
-    const commands: string[] = [];
-    for (const p of this.providers.values()) {
-      if (p.cli?.command) commands.push(p.cli.command);
-    }
-    return commands;
-  }
-
-  async getAvailableProviders(): Promise<ProviderAvailability[]> {
-    const results: ProviderAvailability[] = [];
-    for (const p of this.providers.values()) {
-      const cliAvailable = p.cli ? await p.cli.adapter.isAvailable() : false;
-      const cliVersion = cliAvailable && p.cli ? await p.cli.adapter.getVersion() : null;
-      const apiKeyConfigured = p.api ? !!process.env[p.api.keyEnvVar] : false;
-      const apiAvailable = p.api ? apiKeyConfigured : false;
-
-      results.push({
-        name: p.name,
-        displayName: p.displayName,
-        cli: { available: cliAvailable, version: cliVersion },
-        api: { available: apiAvailable, keyConfigured: apiKeyConfigured },
-      });
-    }
-    return results;
-  }
-}
-```
-
-- [ ] **Step 4: Implement Claude provider definition + registration**
-
-```typescript
-// src/lib/ai/providers/claude.ts
-
-import type { ProviderDefinition } from "../types";
-import { ClaudeCliAdapter } from "../adapters/cli/claude-cli-adapter";
-
-export function createClaudeProvider(): ProviderDefinition {
-  return {
-    name: "claude",
-    displayName: "Claude Code",
-    agentFieldValue: "CLAUDE_CODE",
-    cli: {
-      command: "claude",
-      adapter: new ClaudeCliAdapter(),
-    },
-    // api and cliQuery adapters will be added in Phase 2
-    models: {
-      cli: ["sonnet", "opus", "haiku", "claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5-20251001"],
-      api: [],
-    },
-  };
-}
-```
-
-```typescript
-// src/lib/ai/providers/index.ts
-
-import { ProviderRegistry } from "../provider-registry";
-import { createClaudeProvider } from "./claude";
-
-// Singleton registry — survives HMR via globalThis
-const g = globalThis as typeof globalThis & { __providerRegistry?: ProviderRegistry };
-if (!g.__providerRegistry) {
-  const registry = new ProviderRegistry();
-  registry.register(createClaudeProvider());
-  g.__providerRegistry = registry;
-}
-
-export const providerRegistry = g.__providerRegistry;
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/lib/ai/__tests__/provider-registry.test.ts 2>&1 | tail -20`
-Expected: All tests PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/lib/ai/provider-registry.ts src/lib/ai/providers/claude.ts src/lib/ai/providers/index.ts src/lib/ai/__tests__/provider-registry.test.ts
-git commit -m "feat(ai): implement ProviderRegistry with Claude provider"
-```
-
----
-
-### Task 4: Add AiCapabilityConfig Prisma model
-
-**Files:**
-- Modify: `prisma/schema.prisma`
-
-- [ ] **Step 1: Add AiCapabilityConfig model to schema**
-
-Add after the `CliProfile` model block (after line 218 of `prisma/schema.prisma`):
-
-```prisma
-model AiCapabilityConfig {
-  id        String   @id @default(cuid())
-  slot      String   @unique
-  provider  String   @default("claude")
-  mode      String   @default("cli")
-  model     String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-}
-```
-
-- [ ] **Step 2: Push schema to DB**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm db:push 2>&1 | tail -10`
-Expected: "Your database is now in sync with your Prisma schema"
-
-- [ ] **Step 3: Verify Prisma client generated**
-
-Run: `cd /Users/liujunping/project/f/tower && npx prisma generate 2>&1 | tail -5`
-Expected: "Generated Prisma Client"
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add prisma/schema.prisma
-git commit -m "feat(ai): add AiCapabilityConfig model for capability slot routing"
-```
-
----
-
-### Task 5: Implement capability-resolver
-
-**Files:**
-- Create: `src/lib/ai/capability-resolver.ts`
-- Create: `src/actions/ai-config-actions.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-Create: `src/lib/ai/__tests__/capability-resolver.test.ts`
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-// Mock DB before importing
-vi.mock("@/lib/db", () => ({
-  db: {
-    aiCapabilityConfig: {
-      findUnique: vi.fn(),
-    },
-  },
-}));
-
-import { resolveCliAdapter, resolveQueryAdapter } from "../capability-resolver";
-import { providerRegistry } from "../providers";
-import { db } from "@/lib/db";
-import { AiProviderError } from "../types";
-
-describe("capability-resolver", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  describe("resolveCliAdapter", () => {
-    it("returns Claude adapter when no config exists (default)", async () => {
-      vi.mocked(db.aiCapabilityConfig.findUnique).mockResolvedValue(null);
-      const result = await resolveCliAdapter("terminal");
-      expect(result.provider.name).toBe("claude");
-      expect(result.adapter).toBeDefined();
-    });
-
-    it("returns configured provider adapter", async () => {
-      vi.mocked(db.aiCapabilityConfig.findUnique).mockResolvedValue({
-        id: "1", slot: "terminal", provider: "claude", mode: "cli", model: "opus",
-        createdAt: new Date(), updatedAt: new Date(),
-      });
-      const result = await resolveCliAdapter("terminal");
-      expect(result.provider.name).toBe("claude");
-      expect(result.model).toBe("opus");
-    });
-
-    it("throws AiProviderError for unknown provider", async () => {
-      vi.mocked(db.aiCapabilityConfig.findUnique).mockResolvedValue({
-        id: "1", slot: "terminal", provider: "nonexistent", mode: "cli", model: null,
-        createdAt: new Date(), updatedAt: new Date(),
-      });
-      await expect(resolveCliAdapter("terminal")).rejects.toThrow(AiProviderError);
-    });
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/lib/ai/__tests__/capability-resolver.test.ts 2>&1 | tail -20`
-Expected: FAIL
-
-- [ ] **Step 3: Implement capability-resolver**
-
-```typescript
-// src/lib/ai/capability-resolver.ts
-
-import { db } from "@/lib/db";
-import { providerRegistry } from "./providers";
-import { AiProviderError } from "./types";
-import type { CliAdapter, AiQueryAdapter, ProviderDefinition, AiSlot } from "./types";
-
-const DEFAULT_PROVIDER = "claude";
-const DEFAULT_MODE = "cli";
-
-interface ResolvedCliAdapter {
-  adapter: CliAdapter;
-  provider: ProviderDefinition;
-  model?: string;
-}
-
-interface ResolvedQueryAdapter {
-  adapter: AiQueryAdapter;
-  provider: ProviderDefinition;
-  model?: string;
-}
-
-async function loadSlotConfig(slot: AiSlot) {
-  return db.aiCapabilityConfig.findUnique({ where: { slot } });
-}
-
-export async function resolveCliAdapter(slot: "terminal"): Promise<ResolvedCliAdapter> {
-  const config = await loadSlotConfig(slot);
-  const providerName = config?.provider ?? DEFAULT_PROVIDER;
-  const model = config?.model ?? undefined;
-
-  const providerDef = providerRegistry.get(providerName);
-  if (!providerDef) {
-    throw new AiProviderError("CLI_NOT_FOUND", providerName, `Provider "${providerName}" 未注册`);
-  }
-
-  const adapter = providerDef.cli?.adapter;
-  if (!adapter) {
-    throw new AiProviderError("UNSUPPORTED_MODE", providerName, `Provider "${providerName}" 不支持 CLI 模式`);
-  }
-
-  return { adapter, provider: providerDef, model };
-}
-
-export async function resolveQueryAdapter(
-  slot: "summary" | "dreaming" | "analysis" | "assistant"
-): Promise<ResolvedQueryAdapter> {
-  const config = await loadSlotConfig(slot);
-  const providerName = config?.provider ?? DEFAULT_PROVIDER;
-  const mode = config?.mode ?? DEFAULT_MODE;
-  const model = config?.model ?? undefined;
-
-  const providerDef = providerRegistry.get(providerName);
-  if (!providerDef) {
-    throw new AiProviderError("CLI_NOT_FOUND", providerName, `Provider "${providerName}" 未注册`);
-  }
-
-  const adapter = providerRegistry.getQueryAdapter(providerName, mode as "api" | "cli");
-  if (!adapter) {
-    throw new AiProviderError(
-      "UNSUPPORTED_MODE",
-      providerName,
-      `Provider "${providerName}" 不支持 ${mode} 查询模式`
-    );
-  }
-
-  // Validate model against provider's model list for this mode
-  if (model) {
-    const availableModels = providerDef.models[mode as "cli" | "api"] ?? [];
-    if (availableModels.length > 0 && !availableModels.includes(model)) {
-      throw new AiProviderError(
-        "MODEL_NOT_AVAILABLE",
-        providerName,
-        `模型 "${model}" 在 ${providerName} ${mode} 模式下不可用`
-      );
-    }
-  }
-
-  return { adapter, provider: providerDef, model };
-}
-```
-
-- [ ] **Step 4: Implement ai-config-actions (server actions for Settings UI)**
-
-```typescript
-// src/actions/ai-config-actions.ts
-"use server";
-
-import { db } from "@/lib/db";
-import { revalidatePath } from "next/cache";
-import { providerRegistry } from "@/lib/ai/providers";
-import type { AiSlot } from "@/lib/ai/types";
-
-const VALID_SLOTS: AiSlot[] = ["terminal", "summary", "dreaming", "analysis", "assistant"];
-
-export async function getAiCapabilityConfigs() {
-  return db.aiCapabilityConfig.findMany({ orderBy: { slot: "asc" } });
-}
-
-export async function updateAiCapabilityConfig(
-  slot: string,
-  data: { provider: string; mode: string; model?: string | null }
-) {
-  if (!VALID_SLOTS.includes(slot as AiSlot)) {
-    throw new Error(`无效的插槽: ${slot}`);
-  }
-
-  // Validate provider exists
-  const providerDef = providerRegistry.get(data.provider);
-  if (!providerDef) {
-    throw new Error(`未知的 Provider: ${data.provider}`);
-  }
-
-  // Terminal slot must be CLI mode
-  if (slot === "terminal" && data.mode !== "cli") {
-    throw new Error("终端执行只支持 CLI 模式");
-  }
-
-  await db.aiCapabilityConfig.upsert({
-    where: { slot },
-    create: {
-      slot,
-      provider: data.provider,
-      mode: data.mode,
-      model: data.model ?? null,
-    },
-    update: {
-      provider: data.provider,
-      mode: data.mode,
-      model: data.model ?? null,
-    },
-  });
-
-  revalidatePath("/settings");
-}
-
-export async function getAvailableProviders() {
-  return providerRegistry.getAvailableProviders();
-}
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/lib/ai/__tests__/capability-resolver.test.ts 2>&1 | tail -20`
-Expected: All tests PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/lib/ai/capability-resolver.ts src/actions/ai-config-actions.ts src/lib/ai/__tests__/capability-resolver.test.ts
-git commit -m "feat(ai): implement capability-resolver and ai-config actions"
-```
-
----
-
-### Task 6: Migrate agent-actions.ts to use CliAdapter
-
-This is the critical task — rewire the existing PTY execution functions to use the adapter layer while preserving exact behavior.
-
-**Files:**
-- Modify: `src/actions/agent-actions.ts`
-- Reference: `src/lib/ai/adapters/cli/claude-cli-adapter.ts`, `src/lib/ai/capability-resolver.ts`
-
-- [ ] **Step 1: Add imports at top of agent-actions.ts**
-
-Replace lines 6-8 of `src/actions/agent-actions.ts`:
-
-```typescript
-// Before:
-import { createSession } from "@/lib/pty/session-store";
-import { logger } from "@/lib/logger";
-import { readConfigValue } from "@/lib/config-reader";
-
-// After:
-import { createSession } from "@/lib/pty/session-store";
-import { logger } from "@/lib/logger";
-import { readConfigValue } from "@/lib/config-reader";
-import { resolveCliAdapter } from "@/lib/ai/capability-resolver";
-```
-
-- [ ] **Step 2: Resolve adapter + build spawn result (replaces lines 597-620)**
-
-Replace the hardcoded env + args blocks with a single adapter flow. The adapter owns both args and env construction — the caller passes `spawnResult.env` directly to `createSession`.
-
-```typescript
-// ---- Replace lines 597-620 with: ----
-
-const { adapter: cliAdapter, provider: providerDef, model: configuredModel } = await resolveCliAdapter("terminal");
-
-// Build system prompt additions (instructions file + username)
-let appendSystemPrompt = "";
-if (instructionsFile) {
-  const { readFile } = await import("fs/promises");
-  appendSystemPrompt += await readFile(instructionsFile, "utf-8");
-}
-const usernameVal = await readConfigValue<string>("onboarding.username", "");
-if (usernameVal) {
-  appendSystemPrompt += (appendSystemPrompt ? "\n" : "") + `The user's name is ${usernameVal}.`;
-}
-
-// Adapter produces COMPLETE command + args + env
-const spawnResult = cliAdapter.buildSpawnArgs({
-  taskId,
-  prompt: fullPrompt,
-  cwd,
-  profileArgs: [
-    ...profileBaseArgs,
-    ...(appendSystemPrompt ? ["--append-system-prompt", appendSystemPrompt] : []),
-    ...(configuredModel ? ["--model", configuredModel] : []),
-  ],
-  profileEnvVars,
-  envOverrides: cliAdapter.buildEnvOverrides({
-    taskId,
-    taskTitle: task.title,
-    apiUrl: `http://localhost:${process.env.PORT || "3000"}`,
-    callbackUrl: callbackUrl ?? undefined,
-  }),
-});
-```
-
-- [ ] **Step 3: Update createSession call to use spawnResult (line 624)**
-
-```typescript
-// Before:
-createSession(
-  taskId,
-  profileCommand,
-  claudeArgs,
-  cwd,
-  () => {},
-  async (exitCode) => { ... },
-  envOverrides,
-  ...
-
-// After — spawnResult.env replaces the separate envOverrides variable:
-createSession(
-  taskId,
-  spawnResult.command,
-  spawnResult.args,
-  cwd,
-  () => {},
-  async (exitCode) => { ... },
-  spawnResult.env,
-  ...
-```
-
-- [ ] **Step 4: Update TaskExecution agent field (line 559)**
-
-```typescript
-// Before:
-agent: "CLAUDE_CODE",
-
-// After:
-agent: providerDef.agentFieldValue,
-```
-
-- [ ] **Step 6: Apply same pattern to resumePtyExecution**
-
-Apply the same adapter-based refactor to `resumePtyExecution` (lines 164-306):
-- Add `resolveCliAdapter("terminal")` at the top
-- Replace env overrides (lines 204-213) with `cliAdapter.buildEnvOverrides()`
-- Replace Claude args (lines 229-236) with `cliAdapter.buildSpawnArgs({ resumeSessionId })`
-- Replace `createSession(taskId, profileCommand, claudeArgs, ..., envOverrides, ...)` with `createSession(taskId, spawnResult.command, spawnResult.args, ..., spawnResult.env, ...)`
-- `spawnResult.env` is the single source of truth — no separate `envOverrides`
-
-- [ ] **Step 7: Apply same pattern to continueLatestPtyExecution**
-
-Apply the same adapter-based refactor to `continueLatestPtyExecution` (lines 313-437):
-- Same approach: `resolveCliAdapter` → `buildEnvOverrides` → `buildSpawnArgs({ continueLatest: true })` → pass `spawnResult.env` to `createSession`
-
-- [ ] **Step 8: Run existing tests**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm test:run 2>&1 | tail -30`
-Expected: All existing tests PASS
-
-- [ ] **Step 9: Manual smoke test**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm dev`
-Test: Create a task, start execution, verify Claude CLI spawns correctly, verify terminal works, verify stop/resume works.
-
-- [ ] **Step 10: Commit**
-
-```bash
-git add src/actions/agent-actions.ts
-git commit -m "refactor(ai): migrate agent-actions to use CliAdapter"
-```
-
----
-
-### Task 7: Update ALLOWED_COMMANDS to use registry
-
-**Files:**
-- Modify: `src/actions/cli-profile-actions.ts`
-
-- [ ] **Step 1: Replace hardcoded ALLOWED_COMMANDS**
-
-```typescript
-// Before (line 7):
-const ALLOWED_COMMANDS = ["claude", "claude-code"];
-
-// After:
-import { providerRegistry } from "@/lib/ai/providers";
-
-function getAllowedCommands(): string[] {
-  const fromRegistry = providerRegistry.getAllowedCommands();
-  // Always include claude-code as alias
-  return [...new Set([...fromRegistry, "claude-code"])];
-}
-```
-
-- [ ] **Step 2: Update validation to use function**
-
-```typescript
-// Before (line 34):
-if (!ALLOWED_COMMANDS.includes(basename)) {
-  throw new Error(
-    `command must be one of: ${ALLOWED_COMMANDS.join(", ")} (got: ${basename})`
-  );
-}
-
-// After:
-const allowed = getAllowedCommands();
-if (!allowed.includes(basename)) {
-  throw new Error(
-    `command must be one of: ${allowed.join(", ")} (got: ${basename})`
-  );
-}
-```
-
-- [ ] **Step 3: Run existing cli-profile tests**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm vitest run src/actions/__tests__/cli-profile-actions.test.ts 2>&1 | tail -20`
-Expected: PASS
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/actions/cli-profile-actions.ts
-git commit -m "refactor(ai): derive ALLOWED_COMMANDS from ProviderRegistry"
-```
-
----
-
-### Task 8: Consolidate findClaudeBinary + migrate hooks route to adapter
-
-**Files:**
-- Modify: `src/lib/claude-session.ts`
-- Modify: `src/app/api/internal/assistant/chat/route.ts` (has duplicate findClaudeBinary)
-- Modify: `src/app/api/internal/hooks/install/route.ts` (delegate to adapter)
-
-- [ ] **Step 1: Check for duplicate findClaudeBinary**
-
-Run: `cd /Users/liujunping/project/f/tower && grep -rn "findClaudeBinary\|resolveCommandPathSync.*claude" src/ --include="*.ts" | grep -v node_modules | grep -v __tests__`
-
-- [ ] **Step 2: Replace findClaudeBinary in claude-session.ts**
-
-```typescript
-// Before (lines 1-21):
-import { resolveCommandPathSync } from "@/lib/platform";
-// ...
-function findClaudeBinary(): string { ... }
-
-// After:
-import { ClaudeCliAdapter } from "@/lib/ai/adapters/cli/claude-cli-adapter";
-
-// Adapter resolves binary — single source of truth
-const claudeAdapter = new ClaudeCliAdapter();
-```
-
-Then in `aiQuery()` (line 51), replace:
-```typescript
-// Before:
-pathToClaudeCodeExecutable: claudePath,
-
-// After (use adapter method — expose via public getter):
-pathToClaudeCodeExecutable: claudeAdapter.resolveCommand(),
-```
-
-Note: `resolveCommand()` was already defined as public in Task 2.
-
-- [ ] **Step 3: Migrate assistant/chat/route.ts findClaudeBinary**
-
-Replace the duplicate `findClaudeBinary()` in `src/app/api/internal/assistant/chat/route.ts` with:
-```typescript
-import { ClaudeCliAdapter } from "@/lib/ai/adapters/cli/claude-cli-adapter";
-const claudeAdapter = new ClaudeCliAdapter();
-// Replace findClaudeBinary() calls with claudeAdapter.resolveCommand()
-```
-
-- [ ] **Step 4: Migrate hooks/install/route.ts to delegate to adapter**
-
-Refactor `src/app/api/internal/hooks/install/route.ts` to use `ClaudeCliAdapter` for hook management:
-```typescript
-import { ClaudeCliAdapter } from "@/lib/ai/adapters/cli/claude-cli-adapter";
-const claudeAdapter = new ClaudeCliAdapter();
-
-// GET: return claudeAdapter.isHooksInstalled()
-// POST: call claudeAdapter.installHooks(apiUrl)
-// DELETE: call claudeAdapter.uninstallHooks()
-```
-
-This eliminates duplicate readSettings/writeSettings/getPostToolUseArray logic — adapter is single source of truth.
-
-- [ ] **Step 5: Run tests**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm test:run 2>&1 | tail -20`
-Expected: PASS
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/lib/claude-session.ts src/lib/ai/adapters/cli/claude-cli-adapter.ts src/app/api/internal/assistant/chat/route.ts src/app/api/internal/hooks/install/route.ts
-git commit -m "refactor(ai): consolidate findClaudeBinary and hooks into ClaudeCliAdapter"
-```
-
----
-
-### Task 9: Add i18n keys for AI capability config
-
-**Files:**
-- Modify: `src/lib/i18n/zh.ts`
-- Modify: `src/lib/i18n/en.ts`
-
-Note: i18n uses flat key format (`"section.key": "value"`), not nested JSON.
-
-- [ ] **Step 1: Check existing i18n structure for settings**
-
-Run: `cd /Users/liujunping/project/f/tower && grep "settings\." src/lib/i18n/zh.ts | head -10`
-
-- [ ] **Step 2: Add zh keys**
-
-Add to the flat export object in `src/lib/i18n/zh.ts`:
-
-```typescript
-"aiConfig.title": "AI 能力配置",
-"aiConfig.description": "为每个 AI 功能场景独立配置 Provider 和模型",
-"aiConfig.terminal": "终端执行",
-"aiConfig.summary": "会话总结",
-"aiConfig.dreaming": "知识沉淀",
-"aiConfig.analysis": "项目分析",
-"aiConfig.assistant": "助手聊天",
-"aiConfig.provider": "Provider",
-"aiConfig.mode": "模式",
-"aiConfig.model": "模型",
-"aiConfig.cli": "CLI（订阅）",
-"aiConfig.api": "API（按量）",
-"aiConfig.default": "默认",
-"aiConfig.notConfigured": "未配置",
-"aiConfig.cliNotFound": "CLI 未安装",
-"aiConfig.apiKeyMissing": "API Key 未配置",
-"aiConfig.saved": "已保存",
-```
-
-- [ ] **Step 3: Add en keys**
-
-Add to the flat export object in `src/lib/i18n/en.ts`:
-
-```typescript
-"aiConfig.title": "AI Capability Config",
-"aiConfig.description": "Configure provider and model for each AI feature independently",
-"aiConfig.terminal": "Terminal Execution",
-"aiConfig.summary": "Session Summary",
-"aiConfig.dreaming": "Knowledge Distillation",
-"aiConfig.analysis": "Project Analysis",
-"aiConfig.assistant": "Assistant Chat",
-"aiConfig.provider": "Provider",
-"aiConfig.mode": "Mode",
-"aiConfig.model": "Model",
-"aiConfig.cli": "CLI (Subscription)",
-"aiConfig.api": "API (Pay-per-use)",
-"aiConfig.default": "Default",
-"aiConfig.notConfigured": "Not configured",
-"aiConfig.cliNotFound": "CLI not installed",
-"aiConfig.apiKeyMissing": "API key not configured",
-"aiConfig.saved": "Saved",
-```
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/i18n/locales/zh.json src/i18n/locales/en.json
-git commit -m "feat(i18n): add AI capability config translation keys"
-```
-
----
-
-### Task 10: Full regression test
-
-- [ ] **Step 1: Run all unit tests**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm test:run 2>&1 | tail -30`
-Expected: All PASS
-
-- [ ] **Step 2: TypeScript type check**
-
-Run: `cd /Users/liujunping/project/f/tower && npx tsc --noEmit 2>&1 | tail -20`
-Expected: No errors
-
-- [ ] **Step 3: Start dev server and smoke test**
-
-Run: `cd /Users/liujunping/project/f/tower && pnpm dev`
-
-Manual checks:
-1. Create task → Start execution → Claude CLI spawns in terminal ✓
-2. Stop execution → Summary generates ✓
-3. Resume execution → `--resume` works ✓
-4. Continue execution → `--continue` works ✓
-5. Settings page → CLI Profile still editable ✓
-6. Hook install/uninstall still works ✓
-
-- [ ] **Step 4: Final commit with all clean-up**
-
-```bash
-git add -A
-git commit -m "chore(ai): Phase 1 complete — CLI adapter layer with Claude migration"
-```