@turingflow/agent-kit 0.0.0-stage → 0.1.0

package/dist/server/auth/db.js

@@ -0,0 +1,680 @@
+/**
+ * agent-kit · 用户数据库层（PostgreSQL）
+ *
+ * 职责：
+ *   - 从 env（POSTGRES_*）懒加载连接池（进程级单例）；
+ *   - 幂等执行 schema.sql 建表（migrate）；
+ *   - 提供用户仓储：upsertUser（认证后落库/更新）、findUserByProvider、
+ *     touchLastLogin。
+ *
+ * 仅放"公共、可复用"的代码；具体调用方（web 的路由）在 app 侧。
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { Pool } from "pg";
+import { parseSessionKey } from "./session.js";
+import { randomUUID } from "node:crypto";
+import { copyBranchFiles, mergeBranchSnapshot, nextBranchTitle, selectBranchMessages } from "../session-fork.js";
+/** 运行期可用的 DDL（与 schema.sql 内容一致，作为读不到文件时的兜底）。 */
+const SCHEMA_FALLBACK = `
+CREATE TABLE IF NOT EXISTS users (
+  id BIGSERIAL PRIMARY KEY,
+  provider VARCHAR(16) NOT NULL,
+  union_id VARCHAR(128) NOT NULL,
+  open_id VARCHAR(128),
+  user_code VARCHAR(128),
+  name VARCHAR(128) NOT NULL DEFAULT '',
+  avatar TEXT,
+  email VARCHAR(256),
+  mobile VARCHAR(64),
+  dept_name VARCHAR(256),
+  raw_profile JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  last_login_at TIMESTAMPTZ
+);
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'uq_users_provider_union_id') THEN
+    ALTER TABLE users ADD CONSTRAINT uq_users_provider_union_id UNIQUE (provider, union_id);
+  END IF;
+END $$;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS fs_user_token TEXT;
+ALTER TABLE users ADD COLUMN IF NOT EXISTS fs_refresh_token TEXT;
+CREATE INDEX IF NOT EXISTS idx_users_provider_open_id ON users (provider, open_id);
+CREATE INDEX IF NOT EXISTS idx_users_provider_user_code ON users (provider, user_code);
+
+CREATE TABLE IF NOT EXISTS agent_sessions (
+  id         TEXT         PRIMARY KEY,
+  user_id    VARCHAR(160) NOT NULL,
+  title      VARCHAR(256) NOT NULL DEFAULT '新对话',
+  workspace_dir TEXT,
+  created_at TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS workspace_dir TEXT;
+ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS user_renamed BOOLEAN NOT NULL DEFAULT false;
+DO $$ BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_name = 'agent_sessions' AND column_name = 'user_id' AND data_type = 'bigint'
+  ) THEN
+    ALTER TABLE agent_sessions ADD COLUMN IF NOT EXISTS user_key VARCHAR(160);
+    UPDATE agent_sessions s SET user_key = u.provider || ':' || u.union_id
+      FROM users u WHERE s.user_id = u.id AND s.user_key IS NULL;
+    DELETE FROM agent_sessions WHERE user_key IS NULL;  -- 孤儿会话（FK ON DELETE CASCADE 理论无残留）安全删除，避免 SET NOT NULL 失败
+    ALTER TABLE agent_sessions DROP COLUMN user_id;
+    ALTER TABLE agent_sessions RENAME COLUMN user_key TO user_id;
+    ALTER TABLE agent_sessions ALTER COLUMN user_id SET NOT NULL;
+  END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_user ON agent_sessions (user_id, updated_at DESC);
+CREATE TABLE IF NOT EXISTS agent_messages (
+  id         BIGSERIAL   PRIMARY KEY,
+  session_id TEXT        NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+  role       VARCHAR(16) NOT NULL,
+  content    TEXT        NOT NULL DEFAULT '',
+  images     JSONB,
+  steps      JSONB,
+  thinking_secs INTEGER,
+  elapsed_secs INTEGER,
+  model_info JSONB,
+  artifacts  JSONB,
+  attachment JSONB,
+  cost_info  JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS steps JSONB;
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS thinking_secs INTEGER;
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS elapsed_secs INTEGER;
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS model_info JSONB;
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS artifacts JSONB;
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS attachment JSONB;
+ALTER TABLE agent_messages ADD COLUMN IF NOT EXISTS cost_info JSONB;
+CREATE INDEX IF NOT EXISTS idx_agent_messages_session ON agent_messages (session_id, id);
+
+CREATE TABLE IF NOT EXISTS agent_shares (
+  token      TEXT         PRIMARY KEY,
+  session_id TEXT         NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+  created_by VARCHAR(160) NOT NULL,
+  created_at TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+DO $$ BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_name = 'agent_shares' AND column_name = 'created_by' AND data_type = 'bigint'
+  ) THEN
+    ALTER TABLE agent_shares ADD COLUMN IF NOT EXISTS created_by_key VARCHAR(160);
+    UPDATE agent_shares s SET created_by_key = u.provider || ':' || u.union_id
+      FROM users u WHERE s.created_by = u.id AND s.created_by_key IS NULL;
+    DELETE FROM agent_shares WHERE created_by_key IS NULL;  -- 孤儿分享安全删除，避免 SET NOT NULL 失败
+    ALTER TABLE agent_shares DROP COLUMN created_by;
+    ALTER TABLE agent_shares RENAME COLUMN created_by_key TO created_by;
+    ALTER TABLE agent_shares ALTER COLUMN created_by SET NOT NULL;
+  END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS idx_agent_shares_session ON agent_shares (session_id);
+`;
+let pool = null;
+function buildPool() {
+    const host = process.env.POSTGRES_HOST;
+    const user = process.env.POSTGRES_USER;
+    const db = process.env.POSTGRES_DB;
+    if (!host || !user || !db)
+        return null; // 未配置数据库：认证仍可仅存于会话
+    return new Pool({
+        host,
+        port: Number(process.env.POSTGRES_PORT || 5432),
+        user,
+        password: process.env.POSTGRES_PASSWORD || "",
+        database: db,
+        max: 5,
+        idleTimeoutMillis: 30_000,
+        connectionTimeoutMillis: 10_000,
+    });
+}
+/**
+ * 进程级一次性自动迁移（幂等 schema.sql）：
+ * 首次使用数据库时后台执行一次，避免「schema.sql / db.ts 新增列后忘记手动跑
+ * npm run db:migrate，导致 INSERT 引用不存在的列而静默失败、会话历史丢空」。
+ * 幂等（全部 IF NOT EXISTS）可安全重复；失败只记日志，不影响本次连接使用。
+ */
+let migrateOnce = null;
+export function ensureMigrated() {
+    if (!migrateOnce) {
+        migrateOnce = migrate().catch((e) => {
+            console.error("[agent-kit auth/db] 自动迁移失败（不影响本次连接）:", e instanceof Error ? e.message : e);
+        });
+    }
+    return migrateOnce;
+}
+// 进程启动即触发迁移（不等首次 DB 调用）：新列/新表在第一个请求到达前大概率就绪，
+// 避免「首次 INSERT 与后台迁移竞态 → 列缺失 → 消息落库失败、历史丢空」。
+if (isDbEnabled())
+    void ensureMigrated();
+/** 进程级连接池单例；未配置 Postgres 时返回 null。 */
+export function getPool() {
+    if (pool)
+        return pool;
+    pool = buildPool();
+    if (pool)
+        void ensureMigrated();
+    return pool;
+}
+/** 是否已启用数据库（配置了 Postgres 即启用；无开关，数据强制落库）。 */
+export function isDbEnabled() {
+    return Boolean(process.env.POSTGRES_HOST && process.env.POSTGRES_DB);
+}
+function loadSchemaSql() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        return readFileSync(path.join(here, "schema.sql"), "utf8");
+    }
+    catch {
+        return SCHEMA_FALLBACK;
+    }
+}
+/** 幂等建表；无数据库配置时静默跳过。 */
+export async function migrate() {
+    const p = getPool();
+    if (!p) {
+        console.warn("[agent-kit auth/db] 未配置 Postgres，跳过 migrate（用户仅存于会话）。");
+        return;
+    }
+    const client = await p.connect();
+    try {
+        // 幂等建表（全部 IF NOT EXISTS），成功属预期常态，不打日志；
+        // 仅失败时由 ensureMigrated 的 catch 打印错误（见下方 console.error）
+        await client.query(loadSchemaSql());
+    }
+    finally {
+        client.release();
+    }
+}
+function rowToDbUser(row) {
+    return {
+        id: Number(row.id),
+        provider: String(row.provider),
+        unionId: String(row.union_id),
+        openId: row.open_id ?? null,
+        userCode: row.user_code ?? null,
+        name: String(row.name ?? ""),
+        avatar: row.avatar ?? null,
+        email: row.email ?? null,
+        mobile: row.mobile ?? null,
+        deptName: row.dept_name ?? null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        lastLoginAt: row.last_login_at ?? null,
+    };
+}
+/**
+ * 将认证用户 upsert 到 users 表：按 (provider, union_id) 匹配，存在则更新档案与
+ * last_login_at，不存在则插入。返回数据库行（含内部 id）。
+ */
+export async function upsertUser(user, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return null;
+    const sql = `
+    INSERT INTO users
+      (provider, union_id, open_id, user_code, name, avatar, email, mobile, dept_name, raw_profile,
+       fs_user_token, fs_refresh_token, last_login_at, updated_at)
+    VALUES
+      ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, now(), now())
+    ON CONFLICT (provider, union_id) DO UPDATE SET
+      open_id     = COALESCE(EXCLUDED.open_id, users.open_id),
+      user_code   = COALESCE(EXCLUDED.user_code, users.user_code),
+      name        = COALESCE(NULLIF(EXCLUDED.name, ''), users.name),
+      avatar      = COALESCE(EXCLUDED.avatar, users.avatar),
+      email       = COALESCE(EXCLUDED.email, users.email),
+      mobile      = COALESCE(EXCLUDED.mobile, users.mobile),
+      dept_name   = COALESCE(EXCLUDED.dept_name, users.dept_name),
+      raw_profile = COALESCE(EXCLUDED.raw_profile, users.raw_profile),
+      fs_user_token     = COALESCE(EXCLUDED.fs_user_token, users.fs_user_token),
+      fs_refresh_token  = COALESCE(EXCLUDED.fs_refresh_token, users.fs_refresh_token),
+      last_login_at = now(),
+      updated_at  = now()
+    RETURNING *;
+  `;
+    const values = [
+        user.provider,
+        user.unionId,
+        user.openId || null,
+        user.userCode || null,
+        user.name || "",
+        user.avatar || null,
+        user.email || null,
+        user.mobile || null,
+        user.deptName || null,
+        user.raw ? JSON.parse(JSON.stringify(user.raw)) : null,
+        user.oauthToken?.accessToken || null,
+        user.oauthToken?.refreshToken || null,
+    ];
+    const runner = client ?? p;
+    const result = await runner.query(sql, values);
+    return result.rows[0] ? rowToDbUser(result.rows[0]) : null;
+}
+/** 按 (provider, union_id) 查用户；不存在返回 null。 */
+export async function findUserByProvider(provider, unionId, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return null;
+    const runner = client ?? p;
+    const result = await runner.query("SELECT * FROM users WHERE provider = $1 AND union_id = $2 LIMIT 1", [provider, unionId]);
+    return result.rows[0] ? rowToDbUser(result.rows[0]) : null;
+}
+/** 仅刷新 last_login_at（登录成功时调用）。 */
+export async function touchLastLogin(id, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return;
+    const runner = client ?? p;
+    await runner.query("UPDATE users SET last_login_at = now() WHERE id = $1", [id]);
+}
+/** 取飞书 OAuth 令牌（用户身份发消息用）；无令牌或非飞书用户返回 null。 */
+export async function getUserOauthTokenByKey(userId) {
+    const p = getPool();
+    if (!p)
+        return null;
+    const { provider, unionId } = parseSessionKey(userId);
+    if (!provider || !unionId)
+        return null;
+    const result = await p.query("SELECT provider, fs_user_token, fs_refresh_token FROM users WHERE provider = $1 AND union_id = $2 LIMIT 1", [provider, unionId]);
+    const row = result.rows[0];
+    if (!row || row.provider !== "feishu")
+        return null;
+    return {
+        accessToken: row.fs_user_token || null,
+        refreshToken: row.fs_refresh_token || null,
+    };
+}
+/** 回写飞书 OAuth 令牌（刷新续期后调用；refreshToken 为空时保留原值）。 */
+export async function updateUserOauthToken(userId, token) {
+    const p = getPool();
+    if (!p)
+        return;
+    const { provider, unionId } = parseSessionKey(userId);
+    if (!provider || !unionId)
+        return;
+    await p.query("UPDATE users SET fs_user_token = $3, fs_refresh_token = COALESCE($4, fs_refresh_token), updated_at = now() WHERE provider = $1 AND union_id = $2", [provider, unionId, token.accessToken, token.refreshToken || null]);
+}
+function rowToSession(row) {
+    return {
+        id: String(row.id),
+        userId: String(row.user_id),
+        title: String(row.title ?? "新任务"),
+        workspaceDir: row.workspace_dir || null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        messageCount: Number(row.message_count ?? 0),
+        lastPreview: row.last_preview ?? null,
+    };
+}
+function rowToMessage(row) {
+    return {
+        id: Number(row.id),
+        sessionId: String(row.session_id),
+        role: String(row.role),
+        content: String(row.content ?? ""),
+        images: row.images ?? null,
+        steps: row.steps ?? null,
+        thinkingSecs: row.thinking_secs != null ? Number(row.thinking_secs) : null,
+        elapsedSecs: row.elapsed_secs != null ? Number(row.elapsed_secs) : null,
+        modelInfo: row.model_info ?? null,
+        artifacts: row.artifacts ?? null,
+        attachment: row.attachment ?? null,
+        costInfo: row.cost_info ?? null,
+        createdAt: row.created_at,
+    };
+}
+/** 注册/复用会话：已存在则返回现有行，不存在则插入。workspaceDir 仅首建时生效（复用不改）。 */
+export async function createAgentSession(userId, sessionId, title = "新任务", workspaceDir, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return null;
+    const runner = client ?? p;
+    const result = await runner.query(`INSERT INTO agent_sessions (id, user_id, title, workspace_dir)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (id) DO UPDATE SET updated_at = now()
+     RETURNING *`, [sessionId, userId, title.slice(0, 250), workspaceDir ? workspaceDir.slice(0, 1024) : null]);
+    return result.rows[0] ? rowToSession(result.rows[0]) : null;
+}
+/** 当前用户的会话列表（按最近更新倒序），附带消息数与最后一条消息预览。 */
+export async function listAgentSessions(userId, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return [];
+    const runner = client ?? p;
+    const result = await runner.query(`SELECT s.*,
+            (SELECT count(*) FROM agent_messages m WHERE m.session_id = s.id) AS message_count,
+            (SELECT m.content FROM agent_messages m WHERE m.session_id = s.id ORDER BY m.id DESC LIMIT 1) AS last_preview
+     FROM agent_sessions s
+     WHERE s.user_id = $1
+     ORDER BY s.updated_at DESC
+     LIMIT 200`, [userId]);
+    return result.rows.map(rowToSession);
+}
+/** 校验会话归属并返回该会话；不属于当前用户或不存在时返回 null。 */
+export async function getAgentSession(userId, sessionId, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return null;
+    const runner = client ?? p;
+    const result = await runner.query(`SELECT s.*,
+            (SELECT count(*) FROM agent_messages m WHERE m.session_id = s.id) AS message_count,
+            (SELECT m.content FROM agent_messages m WHERE m.session_id = s.id ORDER BY m.id DESC LIMIT 1) AS last_preview
+     FROM agent_sessions s
+     WHERE s.user_id = $1 AND s.id = $2
+     LIMIT 1`, [userId, sessionId]);
+    return result.rows[0] ? rowToSession(result.rows[0]) : null;
+}
+/** 重命名会话（仅限归属用户）。 */
+export async function renameAgentSession(userId, sessionId, title, userRenamed = false, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return false;
+    const runner = client ?? p;
+    const result = await runner.query(`UPDATE agent_sessions SET title = $3, user_renamed = $4, updated_at = now()
+     WHERE user_id = $1 AND id = $2`, [userId, sessionId, title.slice(0, 250), userRenamed]);
+    return (result.rowCount ?? 0) > 0;
+}
+/** SDK 自动命名（topic / ai-title）落库：仅当用户从未手动改过标题时覆盖（user_renamed=false），
+ *  否则跳过，保护用户手动编辑的标题不被自动命名替换。 */
+export async function setSessionTitleIfNotUserRenamed(userId, sessionId, title, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return false;
+    const runner = client ?? p;
+    const result = await runner.query(`UPDATE agent_sessions SET title = $3, updated_at = now()
+     WHERE user_id = $1 AND id = $2 AND NOT user_renamed`, [userId, sessionId, title.slice(0, 250)]);
+    return (result.rowCount ?? 0) > 0;
+}
+/** 更新会话工作目录（沙箱范围；传 null 表示清除限定）。仅限归属用户。 */
+export async function updateAgentSessionWorkspace(userId, sessionId, workspaceDir, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return false;
+    const runner = client ?? p;
+    const result = await runner.query(`UPDATE agent_sessions SET workspace_dir = $3, updated_at = now()
+     WHERE user_id = $1 AND id = $2`, [userId, sessionId, workspaceDir ? workspaceDir.slice(0, 1024) : null]);
+    return (result.rowCount ?? 0) > 0;
+}
+/** 删除会话（消息级联删除）。 */
+export async function deleteAgentSession(userId, sessionId, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return false;
+    const runner = client ?? p;
+    const result = await runner.query("DELETE FROM agent_sessions WHERE user_id = $1 AND id = $2", [userId, sessionId]);
+    return (result.rowCount ?? 0) > 0;
+}
+/** admin 用量聚合（暂不鉴权）：summary 总量 + 按模型 / 按会话 / 单条消息 Top 消耗。
+ *  数据源：agent_messages.cost_info JSONB { costUsd, usage: { input_tokens, output_tokens } }。 */
+export async function queryAdminUsage(limit = 100) {
+    const p = getPool();
+    if (!p)
+        return null;
+    const [sum, byModel, bySession, details] = await Promise.all([
+        p.query(`SELECT
+         COALESCE(SUM((m.cost_info->'usage'->>'input_tokens')::bigint), 0)::bigint AS input_tokens,
+         COALESCE(SUM((m.cost_info->'usage'->>'output_tokens')::bigint), 0)::bigint AS output_tokens,
+         COALESCE(SUM((m.cost_info->>'costUsd')::double precision), 0)::double precision AS cost_usd,
+         COUNT(*) FILTER (WHERE m.cost_info IS NOT NULL) AS costed_msgs,
+         COUNT(DISTINCT m.session_id) AS sessions
+       FROM agent_messages m WHERE (m.cost_info->>'inherited') IS DISTINCT FROM 'true'`),
+        p.query(`SELECT
+         COALESCE(m.model_info->'models'->>0, '?') AS model,
+         COALESCE(SUM((m.cost_info->'usage'->>'input_tokens')::bigint), 0)::bigint AS input_tokens,
+         COALESCE(SUM((m.cost_info->'usage'->>'output_tokens')::bigint), 0)::bigint AS output_tokens,
+         COUNT(*) AS msgs
+       FROM agent_messages m
+       WHERE m.cost_info IS NOT NULL AND (m.cost_info->>'inherited') IS DISTINCT FROM 'true'
+       GROUP BY 1
+       ORDER BY input_tokens DESC`),
+        p.query(`SELECT
+         s.id AS session_id, s.title, s.created_at,
+         COALESCE(SUM((m.cost_info->'usage'->>'input_tokens')::bigint), 0)::bigint AS input_tokens,
+         COALESCE(SUM((m.cost_info->'usage'->>'output_tokens')::bigint), 0)::bigint AS output_tokens,
+         COALESCE(SUM((m.cost_info->>'costUsd')::double precision), 0)::double precision AS cost_usd,
+         COUNT(*) FILTER (WHERE m.cost_info IS NOT NULL) AS costed_msgs
+       FROM agent_sessions s
+       JOIN agent_messages m ON m.session_id = s.id
+       WHERE m.cost_info IS NOT NULL AND (m.cost_info->>'inherited') IS DISTINCT FROM 'true'
+       GROUP BY s.id, s.title, s.created_at
+       ORDER BY input_tokens DESC`),
+        p.query(`SELECT
+         m.id, m.session_id, s.title AS session_title, s.user_id,
+         u.name AS user_name,
+         m.created_at,
+         (m.cost_info->'usage'->>'input_tokens')::bigint AS input_tokens,
+         (m.cost_info->'usage'->>'output_tokens')::bigint AS output_tokens,
+         (m.cost_info->>'costUsd')::double precision AS cost_usd,
+         COALESCE(m.model_info->'models'->>0, '?') AS model,
+         left(m.content, 200) AS content_preview,
+         -- 该轮的用户提问：同一会话中、本条消息之前最近的一条 user 消息内容
+         (
+           SELECT left(u2.content, 200)
+           FROM agent_messages u2
+           WHERE u2.session_id = m.session_id AND u2.role = 'user' AND u2.id < m.id
+           ORDER BY u2.id DESC
+           LIMIT 1
+         ) AS user_content
+       FROM agent_messages m
+       JOIN agent_sessions s ON s.id = m.session_id
+       LEFT JOIN users u ON u.provider || ':' || u.union_id = s.user_id
+       WHERE m.cost_info IS NOT NULL AND (m.cost_info->>'inherited') IS DISTINCT FROM 'true'
+       ORDER BY (m.cost_info->'usage'->>'input_tokens')::bigint DESC
+       LIMIT $1`, [Math.max(1, Math.min(500, limit))]),
+    ]);
+    const num = (v) => Number(v ?? 0);
+    const summary = {
+        inputTokens: num(sum.rows[0]?.input_tokens),
+        outputTokens: num(sum.rows[0]?.output_tokens),
+        costUsd: num(sum.rows[0]?.cost_usd),
+        costedMsgs: num(sum.rows[0]?.costed_msgs),
+        sessions: num(sum.rows[0]?.sessions),
+    };
+    return {
+        summary,
+        byModel: byModel.rows.map((r) => ({
+            model: String(r.model ?? "?"),
+            inputTokens: num(r.input_tokens),
+            outputTokens: num(r.output_tokens),
+            msgs: num(r.msgs),
+        })),
+        bySession: bySession.rows.map((r) => ({
+            sessionId: String(r.session_id),
+            title: String(r.title ?? ""),
+            createdAt: r.created_at,
+            inputTokens: num(r.input_tokens),
+            outputTokens: num(r.output_tokens),
+            costUsd: num(r.cost_usd),
+            costedMsgs: num(r.costed_msgs),
+        })),
+        details: details.rows.map((r) => ({
+            id: num(r.id),
+            sessionId: String(r.session_id),
+            sessionTitle: String(r.session_title ?? ""),
+            createdAt: r.created_at,
+            inputTokens: num(r.input_tokens),
+            outputTokens: num(r.output_tokens),
+            costUsd: num(r.cost_usd),
+            model: String(r.model ?? "?"),
+            contentPreview: String(r.content_preview ?? ""),
+            userContent: r.user_content != null ? String(r.user_content) : "",
+            user: r.user_name != null ? String(r.user_name) : (r.user_id != null ? String(r.user_id) : ""),
+        })),
+    };
+}
+/** 追加一条消息并刷新会话更新时间。 */
+export async function addAgentMessage(sessionId, role, content, images, steps, thinkingSecs, modelInfo, artifacts, attachment, elapsedSecs, costInfo, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return false;
+    // 写入前等待迁移完成（幂等，毫秒级；防止新列在引擎刚启动的首条消息上缺失）
+    await ensureMigrated();
+    const runner = client ?? p;
+    const result = await runner.query(`INSERT INTO agent_messages (session_id, role, content, images, steps, thinking_secs, model_info, artifacts, attachment, elapsed_secs, cost_info)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+     ON CONFLICT DO NOTHING`, [
+        sessionId,
+        role,
+        content,
+        images ? JSON.stringify(images) : null,
+        steps ? JSON.stringify(steps) : null,
+        thinkingSecs != null ? Math.round(thinkingSecs) : null,
+        modelInfo ? JSON.stringify(modelInfo) : null,
+        artifacts && Array.isArray(artifacts) && artifacts.length ? JSON.stringify(artifacts) : null,
+        attachment && typeof attachment === "object" ? JSON.stringify(attachment) : null,
+        elapsedSecs != null ? Math.round(elapsedSecs) : null,
+        costInfo && typeof costInfo === "object" ? JSON.stringify(costInfo) : null,
+    ]);
+    await runner.query("UPDATE agent_sessions SET updated_at = now() WHERE id = $1", [sessionId]);
+    return true;
+}
+/** 会话内全部消息（按时间正序）；不属于当前用户返回空数组。 */
+export async function listAgentMessages(userId, sessionId, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return [];
+    const runner = client ?? p;
+    const result = await runner.query(`SELECT m.*
+     FROM agent_messages m
+     JOIN agent_sessions s ON s.id = m.session_id
+     WHERE s.user_id = $1 AND m.session_id = $2
+     ORDER BY m.id ASC`, [userId, sessionId]);
+    return result.rows.map(rowToMessage);
+}
+/** Copy a bounded history in one transaction; serialize suffix allocation per owner. */
+export async function forkAgentSession(userId, sourceId, messageIndex, messageId, snapshot) {
+    const pool = getPool();
+    if (!pool)
+        throw new Error("数据库不可用");
+    await ensureMigrated();
+    const client = await pool.connect();
+    let cleanup;
+    try {
+        await client.query("BEGIN");
+        await client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [userId]);
+        const source = await client.query("SELECT * FROM agent_sessions WHERE id = $1 AND user_id = $2 FOR UPDATE", [sourceId, userId]);
+        if (!source.rows[0])
+            throw new Error("会话不存在或无权访问");
+        const history = await listAgentMessages(userId, sourceId, client);
+        const selected = mergeBranchSnapshot(selectBranchMessages(history, messageIndex, messageId), snapshot);
+        const titles = await client.query("SELECT title FROM agent_sessions WHERE user_id = $1", [userId]);
+        const title = nextBranchTitle(String(source.rows[0].title), titles.rows.map((row) => String(row.title)));
+        const id = randomUUID();
+        const workspace = source.rows[0].workspace_dir;
+        const prepared = await copyBranchFiles(sourceId, id, selected, workspace);
+        cleanup = prepared.cleanup;
+        const inserted = await client.query("INSERT INTO agent_sessions (id, user_id, title, workspace_dir, user_renamed) VALUES ($1, $2, $3, $4, true) RETURNING *", [id, userId, title, workspace ?? null]);
+        for (const message of prepared.messages) {
+            await client.query(`INSERT INTO agent_messages (session_id, role, content, images, steps, thinking_secs, elapsed_secs, model_info, artifacts, attachment, cost_info, created_at)
+        VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12)`, [id, message.role, message.content,
+                JSON.stringify(message.images), JSON.stringify(message.steps), message.thinkingSecs, message.elapsedSecs,
+                JSON.stringify(message.modelInfo), JSON.stringify(message.artifacts), JSON.stringify(message.attachment), JSON.stringify(message.costInfo && typeof message.costInfo === "object" ? { ...message.costInfo, inherited: true } : null), message.createdAt]);
+        }
+        await client.query("COMMIT");
+        return { ...rowToSession(inserted.rows[0]), messageCount: selected.length, lastPreview: selected.at(-1)?.content ?? null };
+    }
+    catch (error) {
+        await client.query("ROLLBACK").catch(() => { });
+        await cleanup?.();
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+/** 会话内所有用户消息的附件 url 列表（删会话清理磁盘文件前收集，须在删除会话前调用）。 */
+export async function listSessionAttachmentUrls(userId, sessionId, client) {
+    const p = client ?? getPool();
+    if (!p)
+        return [];
+    const runner = client ?? p;
+    const result = await runner.query(`SELECT m.attachment
+     FROM agent_messages m
+     JOIN agent_sessions s ON s.id = m.session_id
+     WHERE s.user_id = $1 AND m.session_id = $2 AND m.role = 'user' AND m.attachment IS NOT NULL`, [userId, sessionId]);
+    const urls = [];
+    for (const row of result.rows) {
+        const att = row.attachment;
+        if (att && typeof att.url === "string" && att.url)
+            urls.push(att.url);
+    }
+    return urls;
+}
+/** 截断会话：删除指定 id（含）之后的所有消息（编辑重发时调用，让刷新后不出现旧消息）。 */
+export async function truncateAgentMessages(userId, sessionId, upToId) {
+    const p = getPool();
+    if (!p)
+        return;
+    await p.query(`DELETE FROM agent_messages m
+     USING agent_sessions s
+     WHERE s.id = m.session_id AND s.user_id = $1 AND m.session_id = $2 AND m.id > $3`, [userId, sessionId, upToId]);
+}
+/** 按主键查分享记录；不存在返回 null。 */
+export async function getShareByToken(token) {
+    const p = getPool();
+    if (!p)
+        return null;
+    const result = await p.query(`SELECT token, session_id, created_by, created_at FROM agent_shares WHERE token = $1 LIMIT 1`, [token]);
+    const row = result.rows[0];
+    if (!row)
+        return null;
+    return {
+        token: String(row.token),
+        sessionId: String(row.session_id),
+        createdBy: String(row.created_by),
+        createdAt: row.created_at instanceof Date ? row.created_at : new Date(String(row.created_at)),
+    };
+}
+/** 创建分享记录；会话必须已存在（外键保证归属校验由调用方完成）。 */
+export async function createShareRecord(token, sessionId, userId) {
+    const p = getPool();
+    if (!p)
+        return false;
+    await ensureMigrated();
+    try {
+        await p.query(`INSERT INTO agent_shares (token, session_id, created_by) VALUES ($1, $2, $3)
+       ON CONFLICT (token) DO NOTHING`, [token, sessionId, userId]);
+        return true;
+    }
+    catch (e) {
+        console.error(`[agent-kit auth/db] createShareRecord 失败:`, e instanceof Error ? e.message : e);
+        return false;
+    }
+}
+/** 按 session_id 查会话标题（公开分享页展示用；不校验归属）。 */
+export async function getSessionTitleBySessionId(sessionId) {
+    const p = getPool();
+    if (!p)
+        return "";
+    const result = await p.query(`SELECT title FROM agent_sessions WHERE id = $1 LIMIT 1`, [sessionId]);
+    const row = result.rows[0];
+    return row && typeof row.title === "string" ? row.title : "";
+}
+/** 公开读取会话消息（分享页用；不校验用户归属，依赖分享 token 不可枚举）。 */
+export async function listAgentMessagesPublic(sessionId) {
+    const p = getPool();
+    if (!p)
+        return [];
+    const result = await p.query(`SELECT m.*
+     FROM agent_messages m
+     WHERE m.session_id = $1
+     ORDER BY m.id ASC`, [sessionId]);
+    return result.rows.map(rowToMessage);
+}
+/** 按主体键 `${provider}:${unionId}` 查钉钉 userid / 飞书 employee_id（OA 发送消息时作为 sender 使用）。 */
+export async function getUserCodeByKey(userId) {
+    const p = getPool();
+    if (!p)
+        return "";
+    const { provider, unionId } = parseSessionKey(userId);
+    if (!provider || !unionId)
+        return "";
+    const result = await p.query(`SELECT user_code FROM users WHERE provider = $1 AND union_id = $2 LIMIT 1`, [provider, unionId]);
+    const row = result.rows[0];
+    return row && typeof row.user_code === "string" ? row.user_code : "";
+}