@allbluecn/web-app 0.23.7 → 0.24.1

package/src/server/ai-gateway/chat-handler.ts

@@ -303,6 +303,11 @@ export const chatBodySchema = z.object({
   parentRunId: z.string().max(200).optional(),
   // resume 为 durable run 重放载荷（chunk 数组）：限条数，单条体积随 chunk 契约
   resume: z.array(z.unknown()).max(100).optional(),
+  // 执行引擎（线程级）：cloud=服务端模型；local=桌面 pi 本地 Agent。
+  // 只有 desktop 部署且后端装配 __allblueAgentService 时才允许 local。
+  engine: z.enum(["cloud", "local"]).default("cloud"),
+  /** local 引擎的授权工作目录（桌面壳 workspaces.json 精确匹配复核） */
+  cwd: z.string().min(1).max(1000).optional(),
   promptKey: z.string().max(200).optional(),
   /**
    * 附件列表：图片走 dataURL parts，非图片走服务端 BlobStore ref。
@@ -411,7 +416,12 @@ export async function* handleChatRequest(
   scheduleLazyReap()
 
   const raw = await (options?.body ?? request.json())
-  const body = { ...raw, ...(raw.forwardedProps ?? {}) }
+  // Pro 兼容窗口：旧 OSS 客户端（0.x 信封）把业务字段放在 data 里，经
+  // forwardToSaas 转发进来；forwardedProps 缺省时回落 data。窗口结束后可删。
+  const body = {
+    ...raw,
+    ...(raw.forwardedProps ?? (raw as { data?: Record<string, unknown> }).data ?? {}),
+  }
   // 服务端 overrides 最后落笔（审计 2026-10-25 🟠，原顺序 body 在后展开会把服务端
   // 值覆盖掉）：allowedTools / knowledgeBaseIds / temperature 是 serverFn/agent 侧
   // 下发的服务端约束，客户端 body 不得放宽——否则 agent 收紧的工具白名单被击穿。
@@ -426,11 +436,67 @@ export async function* handleChatRequest(
       `Invalid chat request body [${path}]: ${issue?.message ?? "validation failed"}`,
     )
   }
-  const { messages, allowedTools, knowledgeBaseIds, temperature, webSearchEnabled, codeModeEnabled, sandbox, model, provider, workspaceId, workspaceContext, threadId, runId, parentRunId, resume, attachments } = parsed.data
+  const { messages, allowedTools, knowledgeBaseIds, temperature, webSearchEnabled, codeModeEnabled, sandbox, model, provider, workspaceId, workspaceContext, threadId, runId, parentRunId, resume, attachments, engine, cwd } = parsed.data
   // 1.0 起 threadId 为必填：非 1.0 客户端缺省时由服务端兜底生成（每次请求即新会话），
   // 防 resolveUnifiedAiRoute 的 durability/memory 装配与 SaaS 转发在缺参时静默降级。
   // 空字符串已在 schema 被 min(1) 拒绝，这里只需处理 undefined。
   const effectiveThreadId = threadId ?? crypto.randomUUID()
+
+  // 桌面本地 Agent（pi）：线程级引擎与 cwd 是持久化语义的一部分——
+  // - 既有的 cloud 线程不允许中途改成本地（会让历史消息与 pi 会话错位）；
+  // - 线程必须先落 engine=local 再跑，pi 侧以 threadId 作为 session id 续接。
+  // 鉴权边界仍在桌面壳：cwd 必须精确命中 workspaces.json 授权清单。
+  if (engine === "local") {
+    if (attachments.length > 0) {
+      throw new Error("本地 Agent 不支持附件：请移除附件或切换到云端引擎")
+    }
+    const existing = await prisma.chatThread.findUnique({
+      where: { id: effectiveThreadId },
+      select: { userId: true, engine: true, localCwd: true },
+    })
+    if (existing && existing.userId !== session.user.id) {
+      throw new Error("thread not found")
+    }
+    if (existing && existing.engine !== "local") {
+      throw new Error("该会话不是本地 Agent 会话：请新建会话后选择本地工作区")
+    }
+    if (!existing) {
+      await prisma.chatThread.create({
+        data: {
+          id: effectiveThreadId,
+          userId: session.user.id,
+          engine: "local",
+          localCwd: cwd ?? null,
+        },
+      })
+    } else if (cwd && existing.localCwd !== cwd) {
+      // 同一线程固定工作目录（UI 在已有消息时禁用切换）；服务端兜底更新
+      // 只影响 pi 的 sessionId 派生，不改变历史消息归属。
+      await prisma.chatThread.update({
+        where: { id: effectiveThreadId },
+        data: { localCwd: cwd },
+      })
+    }
+    const localRoute = await resolveUnifiedAiRoute(
+      {
+        userId: session.user.id,
+        messages: messages as any[],
+        threadId: effectiveThreadId,
+        runId,
+        parentRunId,
+        engine: "local",
+        localCwd: cwd,
+        aiSourceMode: session.user.aiSourceMode ?? null,
+      },
+      request,
+    )
+    if (localRoute.kind !== "local") {
+      throw new Error("本地 Agent 路由装配失败")
+    }
+    yield* localRoute.stream
+    return
+  }
+
   // 计费闸只在请求真的启用沙箱时才走：feature 未开通或分钟配额耗尽都在这一步
   // fail-closed，不会白付一次 provider 装配与沙箱创建的成本。
   // 知识库所有权校验：过滤客户端传入的非法 KB ID（非自有/非所属工作空间共享）

package/src/server/ai-gateway/chat-stream-builder.ts

@@ -95,6 +95,13 @@ interface BuildChatStreamParams {
    * 允许 adapter 传 null（后台无 adapter 可用）；非 attach 模式 adapter 必填。
    */
   attach?: boolean
+  /**
+   * 桌面本地 Agent（pi）：true 时跳过服务端工具/技能/沙箱/系统提示装配，
+   * adapter 自己跑 agent loop（只读四件套由桌面壳强制）。
+   */
+  localAgent?: boolean
+  /** localAgent 的授权工作目录（桌面壳会再次复核 workspaces.json） */
+  localCwd?: string
 }
 
 /**
@@ -126,6 +133,51 @@ export async function buildChatStreamWithTools(
     throw new Error("buildChatStreamWithTools: 非 attach 模式必须提供 adapter")
   }
 
+  // 本地 Agent 是 harness adapter：pi 自己跑工具循环。服务端工具池、技能、
+  // Code Mode、沙箱与系统提示全部不参与（pi 的封闭 ResourceLoader 自带提示词，
+  // 且只读四件套由桌面壳的 path-guard 强制）。持久化/取消/工具卡仍走同一份
+  // chat() + withPersistence，保证 Harness 的 thread/run 语义不变。
+  if (params.localAgent) {
+    const localThreadId = params.threadId ?? randomUUID()
+    const localPersistence = createPrismaPersistence(params.userId)
+    const localContext: AppContext = {
+      userId: params.userId,
+      db: prisma,
+      threadId: localThreadId,
+      provider: 'local-pi',
+      model: 'local-pi',
+      runId: params.runId,
+      workspaceContext: params.localCwd
+        ? { type: 'local', path: params.localCwd }
+        : undefined,
+    }
+    return chat({
+      adapter: params.adapter,
+      messages: params.messages,
+      tools: [],
+      threadId: localThreadId,
+      runId: params.runId,
+      context: localContext,
+      modelOptions: {
+        cwd: params.localCwd,
+        sessionId: localThreadId,
+      },
+      // pi 自带 agent loop：单次 adapter 调用即完整运行，禁止引擎再发起模型轮次
+      agentLoopStrategy: maxIterations(1),
+      middleware: [
+        loggerMiddleware,
+        rateLimitMiddleware,
+        otelMiddleware({ tracer: otelTracer, captureContent: false }),
+        createAiOutputGuardMiddleware(),
+        withPersistence(localPersistence, {
+          snapshotStreaming: true,
+          snapshotIntervalMs: 1500,
+        }),
+        createUsageLogMiddleware({ activity: 'chat' }),
+      ] as any,
+    }) as AsyncIterable<StreamChunk>
+  }
+
   const nativeSearchTools = buildProviderWebSearchTools(
     params.providerConfigKind,
   ) as any[]

package/src/server/ai-gateway/local-agent-adapter.ts

@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+/**
+ * 桌面本地 Agent（pi）的 Harness 适配器。
+ *
+ * 为什么是 adapter 而不是另起一条 SSE：
+ * - Harness 的 thread / run / 持久化 / 取消 / 工具卡全部建立在 `chat()` 之上；
+ *   pi 作为「自带工具循环的 harness adapter」接入后，这些能力原样复用
+ *   （与 claude-code / codex adapter 同一范式）。
+ * - pi 运行时（@earendil-works/pi-coding-agent）只存在于 Pro 的桌面壳 bundle，
+ *   上游不能 import。后端 utilityProcess 在启动时把能力挂到
+ *   `globalThis.__allblueAgentService`（与 PGlite seam 同进程同模式），本适配器
+ *   只消费一个最小接口：给 cwd + 历史消息，产出 AG-UI 事件流。
+ *
+ * 安全边界不在本文件：cwd 授权（workspaces.json 精确匹配）、只读四件套、
+ * path-guard、工具结果截断全部由 Pro 的 AgentService 在每次运行前复核。
+ * 本适配器在非桌面环境直接拒绝构造，避免云端误用。
+ */
+
+import {
+  EventType,
+  type AdapterYieldChunk,
+  type AnyTextAdapter,
+  type ModelMessage,
+  type TextOptions,
+} from '@tanstack/ai'
+
+/** 桌面壳注入的本地 Agent 服务最小契约（与 Pro agent-service 的导出同形） */
+export interface LocalAgentRunInput {
+  /** 已由桌面壳授权的工作目录（服务端会再次复核） */
+  cwd: string
+  /** 会话标识：Harness threadId（Pro 侧映射为 pi session id，支持续接） */
+  sessionId: string
+  /** 全量消息（Pro 侧决定「续接会话」还是「首次运行展平历史」） */
+  messages: LocalAgentMessage[]
+  threadId: string
+  runId: string
+  signal?: AbortSignal
+}
+
+export interface LocalAgentMessage {
+  role: string
+  content: unknown
+  toolCalls?: unknown
+  toolCallId?: string
+}
+
+export interface LocalAgentService {
+  /**
+   * 运行一次本地 Agent prompt，返回 AG-UI 事件流（结构见 @ag-ui/core）。
+   * 缺失即表示当前部署没有桌面 Agent 能力。
+   */
+  runLocalAgentPrompt?: (input: LocalAgentRunInput) => AsyncIterable<unknown>
+  /** 删除线程对应的 pi 会话文件（Harness 删除会话时同步清理，防本地残留） */
+  deleteLocalAgentSession?: (input: {
+    cwd: string
+    sessionId: string
+  }) => void | Promise<void>
+}
+
+/** 后端装配时挂在 globalThis 的 seam 名（Pro backend/entry.cjs 同值） */
+export const LOCAL_AGENT_GLOBAL_KEY = '__allblueAgentService' as const
+
+export function getLocalAgentService(): LocalAgentService | null {
+  const service = (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+  if (service === null || typeof service !== 'object') return null
+  return service as LocalAgentService
+}
+
+export function hasLocalAgentService(): boolean {
+  return typeof getLocalAgentService()?.runLocalAgentPrompt === 'function'
+}
+
+/** 从 ModelMessage 中提取最后一条 user 文本（pi 的 prompt 入参） */
+export function extractLastUserText(messages: readonly ModelMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const message = messages[i]
+    if (message?.role !== 'user') continue
+    const text = extractText(message.content)
+    if (text.trim() !== '') return text
+  }
+  return ''
+}
+
+function extractText(content: ModelMessage['content']): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter(
+      (part): part is { type: 'text'; content: string } =>
+        part !== null &&
+        typeof part === 'object' &&
+        (part as { type?: unknown }).type === 'text' &&
+        typeof (part as { content?: unknown }).content === 'string',
+    )
+    .map((part) => part.content)
+    .join('')
+}
+
+/**
+ * 本地 Agent 适配器（harness adapter）：pi 自己跑 agent loop 与只读四件套，
+ * 这里只做「Harness 输入 → 本地运行时 → AG-UI 流」的搬运。
+ */
+export class LocalAgentAdapter {
+  readonly kind = 'text' as const
+  readonly name = 'allblue-local-agent'
+  readonly model = 'local-pi'
+
+  async *chatStream(options: TextOptions): AsyncIterable<AdapterYieldChunk> {
+    const service = getLocalAgentService()
+    if (typeof service?.runLocalAgentPrompt !== 'function') {
+      yield this.errorEvent('本地 Agent 不可用：当前部署未装配桌面 pi 运行时')
+      return
+    }
+
+    const modelOptions = options.modelOptions as { cwd?: unknown } | undefined
+    const cwd = typeof modelOptions?.cwd === 'string' ? modelOptions.cwd : ''
+    if (cwd === '') {
+      yield this.errorEvent('本地 Agent 缺少工作目录（cwd）')
+      return
+    }
+
+    const prompt = extractLastUserText(options.messages)
+    if (prompt === '') {
+      yield this.errorEvent('本地 Agent 需要一条非空用户消息')
+      return
+    }
+
+    const runId = options.runId ?? `local-${Date.now().toString(36)}`
+    const abort = new AbortController()
+    const upstreamSignal = options.abortController?.signal
+    const forwardAbort = () => abort.abort()
+    if (upstreamSignal?.aborted) abort.abort()
+    else upstreamSignal?.addEventListener('abort', forwardAbort, { once: true })
+
+    try {
+      for await (const raw of service.runLocalAgentPrompt({
+        cwd,
+        sessionId: options.threadId,
+        messages: toLocalMessages(options.messages),
+        threadId: options.threadId,
+        runId,
+        signal: abort.signal,
+      })) {
+        const event = normalizeEvent(raw, this.model, options.threadId, runId)
+        if (event === null) continue
+        yield event
+      }
+    } catch (error) {
+      // 客户端主动中止：引擎自己收尾，不把取消当故障
+      if (abort.signal.aborted) return
+      const message = error instanceof Error ? error.message : String(error)
+      yield this.errorEvent(message)
+    } finally {
+      upstreamSignal?.removeEventListener('abort', forwardAbort)
+    }
+  }
+
+  structuredOutput(): Promise<never> {
+    return Promise.reject(
+      new Error(
+        '本地 Agent 是 harness adapter（自带 agent loop），不支持一次性结构化抽取；请使用云端模型 adapter',
+      ),
+    )
+  }
+
+  private errorEvent(message: string): AdapterYieldChunk {
+    return {
+      type: EventType.RUN_ERROR,
+      message,
+      code: 'local_agent_failed',
+      timestamp: Date.now(),
+    } as unknown as AdapterYieldChunk
+  }
+}
+
+/** 工厂：Harness 路由按需构造（非桌面环境由 router 先拒绝，不走到这里） */
+export function createLocalAgentAdapter(): AnyTextAdapter {
+  return new LocalAgentAdapter() as unknown as AnyTextAdapter
+}
+
+function toLocalMessages(messages: readonly ModelMessage[]): LocalAgentMessage[] {
+  return messages.map((message) => ({
+    role: message.role,
+    content: message.content,
+    ...(message.toolCalls !== undefined ? { toolCalls: message.toolCalls } : {}),
+    ...(message.toolCallId !== undefined ? { toolCallId: message.toolCallId } : {}),
+  }))
+}
+
+/**
+ * AG-UI 事件归一化：桌面壳的事件已由 pi→AG-UI mapper 产出，这里只补协议必需
+ * 字段（RUN_FINISHED.finishReason 缺省会让引擎等待工具循环；harness 恒为 stop）。
+ */
+function normalizeEvent(
+  raw: unknown,
+  model: string,
+  threadId: string,
+  runId: string,
+): AdapterYieldChunk | null {
+  if (raw === null || typeof raw !== 'object') return null
+  const source = raw as Record<string, unknown>
+  if (typeof source.type !== 'string') return null
+  const event: Record<string, unknown> = { ...source }
+  if (event.model === undefined) event.model = model
+  if (event.threadId === undefined && (source.type === 'RUN_STARTED' || source.type === 'RUN_FINISHED')) {
+    event.threadId = threadId
+  }
+  if (event.runId === undefined && (source.type === 'RUN_STARTED' || source.type === 'RUN_FINISHED')) {
+    event.runId = runId
+  }
+  if (source.type === 'RUN_FINISHED' && event.finishReason === undefined) {
+    // harness adapter 自己跑完工具循环；引擎不应再发起下一轮模型调用
+    event.finishReason = 'stop'
+  }
+  return event as unknown as AdapterYieldChunk
+}

package/src/server/ai-gateway/unified-router.ts

@@ -28,6 +28,11 @@ import {
   resolveDefaultProviderConfig,
 } from './provider-router'
 import { buildChatStreamWithTools } from './chat-stream-builder'
+import {
+  createLocalAgentAdapter,
+  hasLocalAgentService,
+} from './local-agent-adapter'
+import { isDesktopServer } from '@/server/desktop-guest'
 import type { PgStreamDurabilityFactory } from './durability/pg-stream'
 import { resolveByokApiKey, resolveByokProviderMeta } from './byok'
 import { resolveSourceMode } from './source-mode'
@@ -66,6 +71,13 @@ export interface UnifiedAiRequest {
     | { type: "cloud"; workspaceId: string }
   /** 已解析的模型来源模式（由 chat-handler 从 session 注入，跳过 per-request DB findUnique） */
   aiSourceMode?: string | null
+  /**
+   * 执行引擎（线程级）：cloud=服务端模型；local=桌面 pi 本地 Agent。
+   * 只有 desktop 部署且后端装配了 __allblueAgentService 时才允许 local。
+   */
+  engine?: 'cloud' | 'local'
+  /** local 引擎的授权工作目录（桌面壳 workspaces.json 复核） */
+  localCwd?: string
 }
 
 export type UnifiedAiStream = AsyncIterable<StreamChunk>
@@ -107,10 +119,41 @@ async function tryRemoteRoute(req: UnifiedAiRequest): Promise<UnifiedAiRoute | n
   }
 }
 
+async function resolveLocalAgentRoute(req: UnifiedAiRequest): Promise<UnifiedAiRoute> {
+  if (!isDesktopServer()) {
+    throw new NoAiAvailableError('本地 Agent 仅在桌面客户端可用')
+  }
+  if (!req.localCwd) {
+    throw new NoAiAvailableError('本地 Agent 缺少授权工作目录')
+  }
+  if (!hasLocalAgentService()) {
+    throw new NoAiAvailableError(
+      '本地 Agent 运行时未装配：桌面后端未加载 pi（检查 DESKTOP_AGENT 与 agent bundle）',
+    )
+  }
+  return {
+    kind: 'local',
+    stream: await buildChatStreamWithTools({
+      ...req,
+      adapter: createLocalAgentAdapter(),
+      localAgent: true,
+      localCwd: req.localCwd,
+      usageProvider: 'local-pi',
+      usageModel: 'local-pi',
+      providerConfigKind: 'local-pi',
+    }),
+  }
+}
+
 export async function resolveUnifiedAiRoute(
   req: UnifiedAiRequest,
   request?: Request,
 ): Promise<UnifiedAiRoute> {
+  // 线程级引擎选择优先于用户级 aiSourceMode：Harness 的「本地工作区」线程
+  // 必须稳定走 pi，不能被设置里的 hosted/byok 模式劫持。
+  if (req.engine === 'local') {
+    return resolveLocalAgentRoute(req)
+  }
   // aiSourceMode 是第一优先级互斥开关：选中模式后其余路由层全部跳过
   // （P0-4 修复：客户端 byokProvider 回调使 x-byok header 常态携带，固定顺序下 BYOK 会劫持模式 2/1）
   // 优先使用 chat-handler 从 session 注入的已解析值，避免 per-request DB findUnique
@@ -125,12 +168,12 @@ export async function resolveUnifiedAiRoute(
   }
 
   if (mode === 'local-agent') {
-    // M1 阶段占位：本地 Agent 会话在 M5（AcpSession）落地前，配置了该模式的用户得到明确错误
-    // 而非静默回落 BYOK（静默回落会掩盖用户的模式选择）
-    const configured = false // TODO(M5): resolveLocalAgentConfig(req.userId, req.model)
-    if (!configured) {
-      throw new NoAiAvailableError('local-agent-unconfigured：本地 Agent 模式尚未配置可用 CLI')
-    }
+    // 用户级「本地 Agent」模式：有线程级 cwd 时走同一适配器；没有 cwd 时给出
+    // 可执行的指引，而不是静默回落 BYOK（回落会掩盖用户的模式选择）。
+    if (req.localCwd) return resolveLocalAgentRoute(req)
+    throw new NoAiAvailableError(
+      'local-agent-unconfigured：本地 Agent 需要授权工作目录，请在 Harness 选择「本地工作区」后重试',
+    )
   }
   if (mode === 'hosted') {
     const hosted = await tryHosted(req, request)

package/src/server/serverFns/chat/conversations.ts

@@ -19,6 +19,7 @@ import { getPrisma } from "@allbluecn/database/get-prisma"
 import { Prisma } from "@allbluecn/database"
 import { createServerFn } from "@tanstack/react-start"
 import { authContextMiddleware } from "@/server/middlewares/auth-context"
+import { isDesktopServer } from "@/server/desktop-guest"
 import { z } from "zod"
 
 /** 可空 Json 列的 createMany 入参收窄：null → Prisma.JsonNull（Prisma 拒绝裸 null） */
@@ -43,6 +44,8 @@ export const listConversationsFn = createServerFn({ method: "GET" })
         title: true,
         isArchived: true,
         agentId: true,
+        engine: true,
+        localCwd: true,
         updatedAt: true,
         _count: { select: { messages: true } },
         agent: { select: { name: true, avatarEmoji: true } },
@@ -61,6 +64,8 @@ export const listConversationsFn = createServerFn({ method: "GET" })
       messageCount: c._count.messages,
       isArchived: c.isArchived,
       agentId: c.agentId,
+      engine: c.engine === "local" ? ("local" as const) : ("cloud" as const),
+      localCwd: c.localCwd,
       agentName: c.agent?.name ?? null,
       agentEmoji: c.agent?.avatarEmoji ?? null,
       pendingInteraction: (c.interrupts?.length ?? 0) > 0,
@@ -69,6 +74,10 @@ export const listConversationsFn = createServerFn({ method: "GET" })
 
 const createConversationSchema = z.object({
   agentId: z.string().optional().default(""),
+  /** 执行引擎：cloud（默认）/ local（桌面 pi 本地 Agent） */
+  engine: z.enum(["cloud", "local"]).default("cloud"),
+  /** local 引擎的授权工作目录（桌面壳复核） */
+  localCwd: z.string().min(1).max(1000).optional(),
 })
 
 export const createConversationFn = createServerFn({ method: "POST" })
@@ -79,7 +88,19 @@ export const createConversationFn = createServerFn({ method: "POST" })
 
     const agentId = data.agentId || null
 
+    if (data.engine === "local") {
+      if (!isDesktopServer()) {
+        throw new Error("本地 Agent 仅在桌面客户端可用")
+      }
+      if (!data.localCwd) {
+        throw new Error("本地 Agent 需要先选择授权工作目录")
+      }
+    }
+
     if (agentId) {
+      if (data.engine === "local") {
+        throw new Error("本地 Agent 会话不能绑定云端 Agent 预设")
+      }
       const agent = await prisma.userAgent.findFirst({
         where: {
           id: agentId,
@@ -92,7 +113,12 @@ export const createConversationFn = createServerFn({ method: "POST" })
     }
 
     const conversation = await prisma.chatThread.create({
-      data: { userId: context.user.id, agentId },
+      data: {
+        userId: context.user.id,
+        agentId,
+        engine: data.engine,
+        localCwd: data.engine === "local" ? (data.localCwd ?? null) : null,
+      },
       include: { agent: { select: { name: true, avatarEmoji: true } } },
     })
 
@@ -103,15 +129,55 @@ export const createConversationFn = createServerFn({ method: "POST" })
       messageCount: 0,
       isArchived: conversation.isArchived,
       agentId: conversation.agentId,
+      engine: data.engine,
+      localCwd: conversation.localCwd,
       agentName: conversation.agent?.name ?? null,
       agentEmoji: conversation.agent?.avatarEmoji ?? null,
     }
   })
 
+const getConversationSchema = z.object({
+  id: z.string().min(1),
+})
+
+/**
+ * 单会话元数据（线程级引擎 + 本地工作目录）：$threadId 路由打开既有会话时
+ * 需要它初始化 Harness 的引擎/目录选择（消息列表本身不含这些字段）。
+ */
+export const getConversationFn = createServerFn({ method: "GET" })
+  .middleware([authContextMiddleware])
+  .validator(getConversationSchema)
+  .handler(async ({ data, context }) => {
+    const prisma = await getPrisma()
+    const thread = await prisma.chatThread.findFirst({
+      where: { id: data.id, userId: context.user.id },
+      select: {
+        id: true,
+        title: true,
+        agentId: true,
+        engine: true,
+        localCwd: true,
+        isArchived: true,
+      },
+    })
+    if (!thread) return null
+    return {
+      id: thread.id,
+      title: thread.title,
+      agentId: thread.agentId,
+      engine: thread.engine === "local" ? ("local" as const) : ("cloud" as const),
+      localCwd: thread.localCwd,
+      isArchived: thread.isArchived,
+    }
+  })
+
 const updateConversationSchema = z.object({
   id: z.string(),
   title: z.string().optional(),
   isArchived: z.boolean().optional(),
+  /** 空线程可切换引擎（有消息后锁定，客户端亦禁用） */
+  engine: z.enum(["cloud", "local"]).optional(),
+  localCwd: z.string().min(1).max(1000).nullable().optional(),
 })
 
 export const updateConversationFn = createServerFn({ method: "POST" })
@@ -124,6 +190,30 @@ export const updateConversationFn = createServerFn({ method: "POST" })
     if (data.title !== undefined) update.title = data.title
     if (data.isArchived !== undefined) update.isArchived = data.isArchived
 
+    if (data.engine !== undefined || data.localCwd !== undefined) {
+      const thread = await prisma.chatThread.findFirst({
+        where: { id: data.id, userId: context.user.id },
+        select: { engine: true, localCwd: true, _count: { select: { messages: true } } },
+      })
+      if (!thread) throw new Error("thread not found")
+      if (thread._count.messages > 0) {
+        throw new Error("该会话已有消息，不能切换执行引擎：请新建会话")
+      }
+      const nextEngine = data.engine ?? (thread.engine === "local" ? "local" : "cloud")
+      if (nextEngine === "local" && !isDesktopServer()) {
+        throw new Error("本地 Agent 仅在桌面客户端可用")
+      }
+      update.engine = nextEngine
+      update.localCwd =
+        nextEngine === "local"
+          ? (data.localCwd !== undefined ? data.localCwd : thread.localCwd)
+          : null
+      if (nextEngine === "local") {
+        // 本地 Agent 不绑定云端 Agent 预设
+        update.agentId = null
+      }
+    }
+
     await prisma.chatThread.update({
       where: { id: data.id, userId: context.user.id },
       data: update,
@@ -142,10 +232,37 @@ export const deleteConversationFn = createServerFn({ method: "POST" })
   .handler(async ({ data, context }) => {
     const prisma = await getPrisma()
 
+    const thread = await prisma.chatThread.findFirst({
+      where: { id: data.id, userId: context.user.id },
+      select: { engine: true, localCwd: true },
+    })
+    if (!thread) return { success: true }
+
     await prisma.chatThread.delete({
       where: { id: data.id, userId: context.user.id },
     })
 
+    // 本地 Agent 的 pi 会话文件与 Harness 消息是双份存储：删线程时同步清理，
+    // 否则已删除会话的本地对话仍留在 userData/agent/sessions。失败不阻塞删除。
+    if (thread.engine === "local" && thread.localCwd) {
+      try {
+        // 动态 import：serverFn 客户端 split 只重写 createServerFn 调用，顶层
+        // import 的服务端模块会被保留进客户端图；adapter 只在服务端执行。
+        const { getLocalAgentService } = await import(
+          "@/server/ai-gateway/local-agent-adapter"
+        )
+        await getLocalAgentService()?.deleteLocalAgentSession?.({
+          cwd: thread.localCwd,
+          sessionId: data.id,
+        })
+      } catch (error) {
+        console.warn(
+          "[chat] 本地 Agent 会话文件清理失败:",
+          error instanceof Error ? error.message : String(error),
+        )
+      }
+    }
+
     return { success: true }
   })
 
@@ -196,6 +313,8 @@ export const forkConversationFn = createServerFn({ method: "POST" })
           userId,
           title: source.title ? `${source.title} (fork)` : "(fork)",
           agentId: source.agentId,
+          engine: source.engine,
+          localCwd: source.localCwd,
         },
       })
 
@@ -233,6 +352,8 @@ export const forkConversationFn = createServerFn({ method: "POST" })
       messageCount: source._count.messages,
       isArchived: forked.isArchived,
       agentId: forked.agentId,
+      engine: forked.engine === "local" ? ("local" as const) : ("cloud" as const),
+      localCwd: forked.localCwd,
       agentName: source.agent?.name ?? null,
       agentEmoji: source.agent?.avatarEmoji ?? null,
     }