@allbluecn/web-app 0.12.0 → 0.12.3

package/src/server/ai-gateway/tools/plugin-lifecycle-defs.ts

@@ -0,0 +1,122 @@
+// 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/>.
+
+// ⚠ 客户端纯净性硬规则：此文件零 prisma/auth import，客户端可安全 import
+// 服务端 execute 见 plugin-lifecycle-server.ts
+
+import { toolDefinition } from "@tanstack/ai";
+import { z } from "zod";
+
+export const pluginDefineDef = toolDefinition({
+  name: "plugin_define",
+  description:
+    "定义或更新一个 dsh 兼容插件。插件源码会在用户浏览器 Worker 中求值，" +
+    "支持 host/client 双半源码、自定义工具注册。提交后需用户审批才会生效。",
+  needsApproval: true,
+  inputSchema: z.object({
+    name: z.string().min(1).max(64).describe("插件名称，唯一标识"),
+    purpose: z.string().min(1).max(512).describe("插件用途说明"),
+    codeHost: z
+      .string()
+      .max(64_000)
+      .optional()
+      .describe("服务端半源码（浏览器 Worker 内求值，ctx/harness 契约面）"),
+    codeClient: z
+      .string()
+      .max(64_000)
+      .optional()
+      .describe("客户端半源码（UI 侧交互逻辑）"),
+  }),
+  outputSchema: z.object({
+    id: z.string(),
+    version: z.number(),
+    status: z.string(),
+  }),
+});
+
+export const pluginRunDef = toolDefinition({
+  name: "plugin_run",
+  description: "启动一个已定义的插件，在浏览器 Worker 中求值源码并注册工具",
+  needsApproval: true,
+  inputSchema: z.object({
+    name: z.string().min(1).describe("插件名称"),
+  }),
+  outputSchema: z.object({
+    started: z.boolean(),
+    tools: z.array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+        inputSchema: z.any(),
+      })
+    ),
+    error: z.string().optional(),
+  }),
+});
+
+export const pluginStopDef = toolDefinition({
+  name: "plugin_stop",
+  description: "停止一个正在运行的插件",
+  inputSchema: z.object({
+    name: z.string().min(1).describe("插件名称"),
+  }),
+  outputSchema: z.object({
+    stopped: z.boolean(),
+  }),
+});
+
+export const pluginUndefineDef = toolDefinition({
+  name: "plugin_undefine",
+  description: "删除一个插件（软删除，标记 isDeleted）",
+  inputSchema: z.object({
+    name: z.string().min(1).describe("插件名称"),
+  }),
+  outputSchema: z.object({
+    deleted: z.boolean(),
+  }),
+});
+
+export const pluginInspectListDef = toolDefinition({
+  name: "plugin_inspect_list",
+  description: "列出当前用户的所有插件及其状态",
+  inputSchema: z.object({}),
+  outputSchema: z.object({
+    plugins: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        purpose: z.string(),
+        version: z.number(),
+        status: z.string(),
+        tools: z.array(
+          z.object({
+            name: z.string(),
+            description: z.string(),
+          })
+        ),
+      })
+    ),
+  }),
+});
+
+export const pluginLifecycleDefs = [
+  pluginDefineDef,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  pluginInspectListDef,
+];

package/src/server/ai-gateway/tools/plugin-lifecycle-server.ts

@@ -0,0 +1,160 @@
+// 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/>.
+
+// 服务端 execute 实现（import prisma，仅服务端装配）
+// 客户端 def 见 plugin-lifecycle-defs.ts（零 prisma import）
+
+import { prisma } from "@allbluecn/database";
+import { getCurrentSession } from "@/lib/session";
+import { precheckPluginCode } from "@/server/serverFns/plugins/plugin-precheck";
+import type { AppContext } from "../types";
+import {
+  pluginDefineDef,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  pluginInspectListDef,
+} from "./plugin-lifecycle-defs";
+
+export const pluginDefineTool = pluginDefineDef.server<AppContext>(
+  async ({ name, purpose, codeHost, codeClient }, { context }) => {
+    const userId = context.userId;
+
+    const precheck = precheckPluginCode({ name, purpose, codeHost, codeClient });
+    if (!precheck.ok) {
+      throw new Error(`Plugin precheck failed: ${precheck.errors.join("; ")}`);
+    }
+
+    const existing = await prisma.harnessPlugin.findFirst({
+      where: { userId, name, isDeleted: false },
+    });
+
+    if (existing) {
+      const updated = await prisma.harnessPlugin.update({
+        where: { id: existing.id },
+        data: {
+          purpose,
+          codeHost: codeHost ?? null,
+          codeClient: codeClient ?? null,
+          version: existing.version + 1,
+          status: "defined",
+          lastError: null,
+        },
+      });
+      return { id: updated.id, version: updated.version, status: updated.status };
+    }
+
+    const created = await prisma.harnessPlugin.create({
+      data: { userId, name, purpose, codeHost: codeHost ?? null, codeClient: codeClient ?? null },
+    });
+    return { id: created.id, version: created.version, status: created.status };
+  }
+);
+
+export const pluginRunTool = pluginRunDef.server<AppContext>(
+  async ({ name }, { context }) => {
+    const userId = context.userId;
+
+    const plugin = await prisma.harnessPlugin.findFirst({
+      where: { userId, name, isDeleted: false },
+    });
+    if (!plugin) throw new Error("Plugin not found");
+
+    if (!plugin.codeHost && !plugin.codeClient) {
+      throw new Error("Plugin has no code to run");
+    }
+
+    await prisma.harnessPlugin.update({
+      where: { id: plugin.id },
+      data: { status: "running", lastError: null },
+    });
+
+    return {
+      started: true,
+      tools: plugin.tools as any[],
+    };
+  }
+);
+
+export const pluginStopTool = pluginStopDef.server<AppContext>(
+  async ({ name }, { context }) => {
+    const userId = context.userId;
+
+    const plugin = await prisma.harnessPlugin.findFirst({
+      where: { userId, name, isDeleted: false },
+    });
+    if (!plugin) throw new Error("Plugin not found");
+
+    await prisma.harnessPlugin.update({
+      where: { id: plugin.id },
+      data: { status: "stopped" },
+    });
+
+    return { stopped: true };
+  }
+);
+
+export const pluginUndefineTool = pluginUndefineDef.server<AppContext>(
+  async ({ name }, { context }) => {
+    const userId = context.userId;
+
+    const plugin = await prisma.harnessPlugin.findFirst({
+      where: { userId, name, isDeleted: false },
+    });
+    if (!plugin) throw new Error("Plugin not found");
+
+    await prisma.harnessPlugin.update({
+      where: { id: plugin.id },
+      data: { isDeleted: true },
+    });
+
+    return { deleted: true };
+  }
+);
+
+export const pluginInspectListTool = pluginInspectListDef.server<AppContext>(
+  async (_args, { context }) => {
+    const userId = context.userId;
+
+    const plugins = await prisma.harnessPlugin.findMany({
+      where: { userId, isDeleted: false },
+      orderBy: { updatedAt: "desc" },
+    });
+
+    return {
+      plugins: plugins.map((p) => ({
+        id: p.id,
+        name: p.name,
+        purpose: p.purpose,
+        version: p.version,
+        status: p.status,
+        tools: (p.tools as any[])?.map((t) => ({
+          name: t.name,
+          description: t.description,
+        })) ?? [],
+      })),
+    };
+  }
+);
+
+export const pluginLifecycleTools = [
+  pluginDefineTool,
+  pluginRunTool,
+  pluginStopTool,
+  pluginUndefineTool,
+  pluginInspectListTool,
+];

package/src/server/ai-gateway/tools/plugin-tools.ts

@@ -0,0 +1,57 @@
+// 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/>.
+
+// 服务端动态工具池：读 running 插件 → 构造 client-executed 工具定义
+// 三段前缀：plugin__<pluginName>__<toolName>（运行期与内置工具名隔离）
+
+import { prisma } from "@allbluecn/database";
+import { toolDefinition } from "@tanstack/ai";
+
+export interface PluginToolDef {
+  name: string;
+  description: string;
+  inputSchema: any;
+}
+
+export async function buildPluginTools(userId: string): Promise<any[]> {
+  const plugins = await prisma.harnessPlugin.findMany({
+    where: { userId, status: "running", isDeleted: false },
+    select: { id: true, name: true, tools: true },
+  });
+
+  const tools: any[] = [];
+
+  for (const plugin of plugins) {
+    const pluginTools = plugin.tools as PluginToolDef[] | null;
+    if (!pluginTools || !Array.isArray(pluginTools)) continue;
+
+    for (const toolDef of pluginTools) {
+      if (!toolDef.name || !toolDef.description) continue;
+
+      const toolName = `plugin__${plugin.name}__${toolDef.name}`;
+      const tool = toolDefinition({
+        name: toolName,
+        description: `[${plugin.name}] ${toolDef.description}`,
+        inputSchema: toolDef.inputSchema || { type: "object", properties: {} },
+      });
+
+      tools.push(tool);
+    }
+  }
+
+  return tools;
+}

package/src/server/ai-gateway/tools/projection-namespace.ts

@@ -0,0 +1,28 @@
+// 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/>.
+
+/**
+ * ChatProjection 服务端权威快照 namespace 单一事实源。
+ * ADR 7 决策：复用 ChatPersistenceMeta 表，namespace 约定 `projection/<threadId>`，
+ * key 区分不同快照类型（todos / plan）。
+ *
+ * 本文件不做 threadId 兜底——调用方必须显式传 threadId；无 threadId 时
+ * 调用方应 fail-closed（不落库），避免不同 user × session 写同一行造成污染。
+ */
+export function projectionNamespace(threadId: string): string {
+  return `projection/${threadId}`;
+}

package/src/server/ai-gateway/tools/registry.ts

@@ -0,0 +1,101 @@
+// 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/>.
+
+import { createToolRegistry, type AnyTool } from "@tanstack/ai"
+import {
+  knowledgeSearchDef,
+  documentCrudDef,
+  userDataDef,
+  webSearchDef,
+  reindexKnowledgeBaseDef,
+} from "./definitions"
+import { deleteProjectDef } from "./delete-project"
+import { todoWriteDef } from "./todo-write"
+import { planSubmitDef } from "./plan-submit"
+import {
+  pluginDefineDef,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  pluginInspectListDef,
+} from "./plugin-lifecycle-defs"
+import { delegateTaskDef } from "./delegate-task"
+import { createPullRequestDef } from "./create-pr"
+import { type AgentToolKey } from "./keys"
+
+export const AGENT_TOOL_DEFS = [
+  knowledgeSearchDef,
+  documentCrudDef,
+  userDataDef,
+  webSearchDef,
+  reindexKnowledgeBaseDef,
+  deleteProjectDef,
+  todoWriteDef,
+  planSubmitDef,
+  pluginDefineDef,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  pluginInspectListDef,
+  delegateTaskDef,
+  createPullRequestDef,
+] as const
+
+export type AgentToolDef = (typeof AGENT_TOOL_DEFS)[number]
+export type { AgentToolKey } from "./keys"
+
+export function assertUniqueToolNames(tools: readonly AnyTool[]): void {
+  const seen = new Set<string>()
+  for (const tool of tools) {
+    if (seen.has(tool.name)) {
+      throw new Error(`Duplicate tool name: ${tool.name}`)
+    }
+    seen.add(tool.name)
+  }
+}
+
+export function assertToolStructureComplete(tools: readonly AgentToolDef[]): void {
+  for (const tool of tools) {
+    if (!tool.name) throw new Error("Tool missing name field")
+    if (!tool.description) {
+      throw new Error(`Tool ${tool.name} missing description field`)
+    }
+    if (!tool.inputSchema) {
+      throw new Error(`Tool ${tool.name} missing inputSchema field`)
+    }
+  }
+}
+
+export function assertExecutableToolStructure(tools: readonly AnyTool[]): void {
+  for (const tool of tools) {
+    if (!tool.name) throw new Error("Executable tool missing name field")
+    if (!tool.description) {
+      throw new Error(`Executable tool ${tool.name} missing description field`)
+    }
+    if (!tool.inputSchema) {
+      throw new Error(`Executable tool ${tool.name} missing inputSchema field`)
+    }
+    if (typeof tool.execute !== "function") {
+      throw new Error(`Executable tool ${tool.name} missing execute function`)
+    }
+  }
+}
+
+assertUniqueToolNames(AGENT_TOOL_DEFS)
+assertToolStructureComplete(AGENT_TOOL_DEFS)
+
+export const toolRegistry = createToolRegistry([...AGENT_TOOL_DEFS] as AnyTool[])

package/src/server/ai-gateway/tools/select.ts

@@ -15,16 +15,45 @@
 // 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/>.
 
-export const AGENT_TOOL_KEYS = [
-  "knowledge_search",
-  "document_action",
-  "user_data_query",
-  "web_search",
-  "reindex_knowledge_base",
-  "delete_project",
-] as const
+/**
+ * 工具风险分级（设计 §9.2 P0 底座现代化）：
+ * - read        只读：不变更用户资产，任意 agent 可自由调用
+ * - write       写业务数据：可能产生/修改用户资产，agent 白名单可控可见性
+ * - destructive 破坏型：不可逆，平台硬规则——agent 白名单只决定是否可见，
+ *                不能豁免审批。此类工具在工具定义上必须 `needsApproval: true`，
+ *                selectTools 有防御断言锁定此不变式，避免未来回归。
+ *
+ * 分级仅覆盖 agent 可见的 8 个工具；web_search 属外部检索只读。
+ * todo_write/plan_submit 归 read——它们只写投影快照（ADR 7 的
+ * projection/<threadId> namespace，非用户资产表），不产生业务副作用。
+ */
+export type ToolRisk = "read" | "write" | "destructive"
 
-export type AgentToolKey = (typeof AGENT_TOOL_KEYS)[number]
+export const TOOL_RISK: Record<string, ToolRisk> = {
+  web_search: "read",
+  knowledge_search: "read",
+  user_data_query: "read",
+  todo_write: "read",
+  plan_submit: "read",
+  plugin_inspect_list: "read",
+  delegate_task: "read",
+  create_pull_request: "write",
+  document_action: "write",
+  reindex_knowledge_base: "write",
+  plugin_run: "write",
+  plugin_stop: "write",
+  plugin_undefine: "write",
+  delete_project: "destructive",
+  plugin_define: "destructive",
+}
+
+import { AGENT_TOOL_KEYS, type AgentToolKey } from "./keys"
+
+export { AGENT_TOOL_KEYS, type AgentToolKey }
+
+export function isAgentToolKey(v: unknown): v is AgentToolKey {
+  return typeof v === "string" && (AGENT_TOOL_KEYS as readonly string[]).includes(v)
+}
 
 const DELETE_PROJECT_KEY = "delete_project"
 
@@ -36,18 +65,48 @@ function normalizeToolName(name: string): string {
   return TOOL_ALIASES[name] ?? name
 }
 
+/**
+ * 从入池工具集中挑选工具。
+ * - `allowedKeys` 为空/未传：返回全集（agent 未启用或平台默认全可见场景）。
+ * - `allowedKeys` 非空：白名单过滤，destructive 级工具（当前仅 delete_project）
+ *   无论是否在白名单中都会保留——平台硬规则，agent 无权通过白名单隐藏它
+ *   （agent 无法控制是否可见，但审批门槛恒定）。
+ *
+ * 防御断言：destructive 级工具必须显式声明 `needsApproval: true`，否则
+ * 抛出运行时错误。此断言是设计 §9.2 的回归哨兵——未来若有人给 delete_project
+ * 或其他 destructive 工具删除审批声明，selectTools 在开发期就会报错，
+ * 不会静默通过。
+ */
+function assertDestructiveNeedsApproval<T extends { name: string }>(selected: readonly T[]): void {
+  for (const tool of selected) {
+    if (
+      TOOL_RISK[tool.name] === "destructive" &&
+      (tool as T & { needsApproval?: boolean }).needsApproval !== true
+    ) {
+      throw new Error(
+        `Destructive tool ${tool.name} must declare needsApproval: true (platform invariant, ADR 16 §防后果)`,
+      )
+    }
+  }
+}
+
 export function selectTools<T extends { name: string }>(
   tools: readonly T[],
   allowedKeys?: readonly string[],
 ): T[] {
   if (!allowedKeys || allowedKeys.length === 0) {
-    return [...tools]
+    const all = [...tools]
+    assertDestructiveNeedsApproval(all)
+    return all
   }
 
   const allowed = new Set(allowedKeys)
-  return tools.filter((tool) => {
+  const selectedTools = tools.filter((tool) => {
     if (tool.name === DELETE_PROJECT_KEY) return true
     const normalized = normalizeToolName(tool.name)
     return allowed.has(tool.name) || allowed.has(normalized)
   })
+
+  assertDestructiveNeedsApproval(selectedTools)
+  return selectedTools
 }

package/src/server/ai-gateway/tools/server.ts

@@ -21,6 +21,8 @@ import { buildGuardedKbContext } from "../kb-context-guard"
 import { knowledgeSearchDef, documentCrudDef, userDataDef, webSearchDef, reindexKnowledgeBaseDef } from "./definitions"
 import { prisma } from "@allbluecn/database"
 import { constrainKnowledgeBaseId, mergeKnowledgeResults, type KnowledgeSearchInput } from "./knowledge-scope"
+import { todoWriteTool } from "./todo-write"
+import { planSubmitTool } from "./plan-submit"
 
 /**
  * knowledge_search 的执行逻辑（从 tool 定义中抽出，使返回边界可被直接单测）。
@@ -110,7 +112,7 @@ export async function executeKnowledgeSearch(
       documentId: r.documentId,
       score: r.score,
     })),
-    context: buildGuardedKbContext(
+    context: await buildGuardedKbContext(
       merged.results.map((r) => ({
         id: r.documentId,
         title: titleOf(r),
@@ -236,6 +238,6 @@ const reindexKnowledgeBaseTool = reindexKnowledgeBaseDef.server<AppContext>(
   },
 )
 
-export const baseServerTools = [knowledgeSearchTool, documentCrudTool, userDataTool, reindexKnowledgeBaseTool]
+export const baseServerTools = [knowledgeSearchTool, documentCrudTool, userDataTool, reindexKnowledgeBaseTool, todoWriteTool, planSubmitTool]
 
 export const serverTools = [...baseServerTools, webSearchTool]

package/src/server/ai-gateway/tools/todo-write.ts

@@ -0,0 +1,78 @@
+// 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/>.
+
+import { toolDefinition } from "@tanstack/ai";
+import { z } from "zod";
+import { prisma, Prisma } from "@allbluecn/database";
+import type { AppContext } from "../types";
+import { projectionNamespace } from "./projection-namespace";
+
+export type TodoItem = {
+  content: string;
+  status: "pending" | "in_progress" | "completed";
+  activeForm?: string;
+};
+
+const todoItemSchema = z.object({
+  content: z.string().describe("任务描述"),
+  status: z.enum(["pending", "in_progress", "completed"]).describe("任务状态"),
+  activeForm: z.string().optional().describe("进行中的动作描述（仅 status='in_progress' 时填写，进行态展示用）"),
+});
+
+export const todoWriteDef = toolDefinition({
+  name: "todo_write",
+  description:
+    "整表替换当前对话的待办清单。每次调用传入完整的最新 todo 列表，禁止增量补丁；" +
+    "客户端投影面板以此为准渲染。用于跟踪复杂多步任务的进度。",
+  inputSchema: z.object({
+    todos: z.array(todoItemSchema).describe("完整待办列表（整表替换语义）"),
+  }),
+  outputSchema: z.object({
+    stored: z.boolean().describe("是否已写入服务端权威快照；false 表示无 threadId 未落库"),
+    count: z.number().describe("待办项数量"),
+    updatedAt: z.string().optional().describe("服务端时间戳 ISO8601；stored=false 时缺省"),
+  }),
+});
+
+export const todoWriteTool = todoWriteDef.server<AppContext>(
+  async ({ todos }, { context }) => {
+    const threadId = context.threadId;
+    if (!threadId) {
+      return { stored: false, count: todos.length };
+    }
+
+    const namespace = projectionNamespace(threadId);
+    const value = {
+      todos,
+      updatedAt: new Date().toISOString(),
+    } satisfies { todos: TodoItem[]; updatedAt: string };
+
+    await prisma.chatPersistenceMeta.upsert({
+      where: { namespace_key: { namespace, key: "todos" } },
+      create: {
+        namespace,
+        key: "todos",
+        value: value as unknown as Prisma.InputJsonValue,
+      },
+      update: {
+        value: value as unknown as Prisma.InputJsonValue,
+      },
+    });
+
+    return { stored: true, count: todos.length, updatedAt: value.updatedAt };
+  },
+);