@turingflow/agent-kit 0.0.0-stage → 0.1.0

package/dist/server/session-access.d.ts

@@ -0,0 +1,5 @@
+export type SessionAccessKind = "user" | null;
+/** 判断某个会话是否属于当前请求者（登录用户 → DB 归属校验）。 */
+export declare function assertSessionAccess(request: Request, sessionId: string): Promise<SessionAccessKind>;
+/** chat / answer / steer 的访问判定：登录用户 → DB 归属；未登录 → 拒绝。 */
+export declare function assertChatAccess(request: Request, sessionId: string, resume: boolean): Promise<SessionAccessKind>;

package/dist/server/session-access.js

@@ -0,0 +1,68 @@
+/**
+ * agent-kit · 会话访问控制（隔离核心）
+ *
+ * 目标：不同用户之间不能访问彼此的会话数据（消息 / 产物 / 常驻 CLI 会话）。
+ * 唯一路径：以会话 Cookie（agent_session）解析 user.sub（主体键 `provider:unionId`），再查 PostgreSQL
+ * agent_sessions.user_id —— 只能访问**自己**的会话。任何请求带别人的 sessionId
+ * → 拒绝。未登录一律无权限（不再支持游客模式）。
+ *
+ * 设计取舍：
+ *   - 产物（iframe/img/a 无法带 header）同样走 Cookie：同源请求自动携带，
+ *     无需 URL 签名票据；
+ *   - 数据库故障时放行登录用户（体验优先，风险=失去归属校验，接受并记日志）。
+ */
+import { verifySession } from "./auth/handlers.js";
+import { loadAuthConfig } from "./auth/config.js";
+import { getAgentSession, isDbEnabled } from "./auth/db.js";
+/** 判断某个会话是否属于当前请求者（登录用户 → DB 归属校验）。 */
+export async function assertSessionAccess(request, sessionId) {
+    const user = verifySession(request, loadAuthConfig());
+    if (!user?.sub)
+        return null;
+    if (isDbEnabled()) {
+        try {
+            const row = await getAgentSession(user.sub, sessionId);
+            return row ? "user" : null;
+        }
+        catch (e) {
+            // DB 查询异常：放行登录用户（体验优先，风险=数据库故障时失去归属校验，接受并记日志）
+            console.warn("[agent-kit access] DB 归属校验异常，放行登录用户:", e instanceof Error ? e.message : e);
+            return "user";
+        }
+    }
+    return "user"; // 数据库未启用：会话无持久化，无跨用户数据可泄露
+}
+/** chat / answer / steer 的访问判定：登录用户 → DB 归属；未登录 → 拒绝。 */
+export async function assertChatAccess(request, sessionId, resume) {
+    const user = verifySession(request, loadAuthConfig());
+    if (!user?.sub)
+        return null;
+    if (isDbEnabled()) {
+        try {
+            const row = await getAgentSession(user.sub, sessionId);
+            if (row)
+                return "user";
+            // 编辑重发时前端会换一个「临时 SDK transcript id」避免 CLI 加载旧 transcript。
+            // 该 id 形如 `${本会话 id}_${随机后缀}`（会话 id 为 UUID，不含 '_'）。
+            // 取 '_' 前的会话 id 校验归属——id 由受信会话 id 派生，无法借它冒用他人会话：
+            //   · 直接拿他人会话 id 当 sessionId → 上面查不到，无 '_' 可选，落到此处仍拒绝；
+            //   · 伪造 `${他人会话 id}_x` → 基准 id 非本人所有，拒绝。
+            const sep = sessionId.indexOf("_");
+            if (sep > 0) {
+                const base = sessionId.slice(0, sep);
+                const owner = await getAgentSession(user.sub, base);
+                if (owner)
+                    return "user";
+            }
+        }
+        catch (e) {
+            console.warn("[agent-kit access] DB 归属校验异常，放行登录用户:", e instanceof Error ? e.message : e);
+            return "user";
+        }
+        // DB 可用但库里没有该会话：仅首轮（resume=false）放行——视为当前用户的新会话
+        //（前端发送前会先 POST /api/sessions 注册；此分支覆盖注册竞态）；
+        // 续接一个"不属于自己"的会话 → 拒绝。
+        return resume ? null : "user";
+    }
+    return "user"; // 数据库未启用
+}

package/dist/server/session-fork.d.ts

@@ -0,0 +1,10 @@
+import type { AgentMessageRow } from "./auth/db.js";
+export declare function nextBranchTitle(title: string, existing: Iterable<string>): string;
+export declare function selectBranchMessages(messages: AgentMessageRow[], index: number, messageId?: number): AgentMessageRow[];
+/** Preserve still-visible browser steps/long text while keeping file references server-owned. */
+export declare function mergeBranchSnapshot(messages: AgentMessageRow[], snapshot?: unknown): AgentMessageRow[];
+/** Independent files prevent deleting/editing the source from breaking the branch. */
+export declare function copyBranchFiles(sourceId: string, targetId: string, messages: AgentMessageRow[], workspaceDir?: string): Promise<{
+    messages: AgentMessageRow[];
+    cleanup: () => Promise<void>;
+}>;

package/dist/server/session-fork.js

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { artifactType, ensureSessionDir, readArtifact, saveRegistry, sanitizeArtifactName } from "./artifacts.js";
+export function nextBranchTitle(title, existing) {
+    const used = new Set(existing);
+    const base = title.replace(/（\d+）$/, "");
+    for (let n = 1;; n++) {
+        const suffix = `（${n}）`;
+        const candidate = base.slice(0, 250 - suffix.length) + suffix;
+        if (!used.has(candidate))
+            return candidate;
+    }
+}
+export function selectBranchMessages(messages, index, messageId) {
+    const end = messageId === undefined ? index : messages.findIndex((message) => message.id === messageId);
+    if (!Number.isSafeInteger(end) || end < 0 || end >= messages.length || messages[end].role !== "assistant") {
+        throw new Error("所选答复尚未保存或已发生变化，请刷新后重试");
+    }
+    return structuredClone(messages.slice(0, end + 1));
+}
+/** Preserve still-visible browser steps/long text while keeping file references server-owned. */
+export function mergeBranchSnapshot(messages, snapshot) {
+    if (snapshot === undefined)
+        return messages;
+    if (!Array.isArray(snapshot) || snapshot.length !== messages.length)
+        throw new Error("会话内容已变化，请刷新后重试");
+    return messages.map((message, index) => {
+        const live = snapshot[index];
+        if (!live || live.role !== message.role || typeof live.content !== "string" || (live.id !== undefined && live.id !== message.id)
+            || (live.content !== message.content && live.content.slice(0, 20000) !== message.content))
+            throw new Error("会话内容已变化，请刷新后重试");
+        return { ...message, content: live.content, images: Array.isArray(live.images) ? live.images : message.images,
+            steps: Array.isArray(live.steps) ? live.steps : message.steps };
+    });
+}
+/** Independent files prevent deleting/editing the source from breaking the branch. */
+export async function copyBranchFiles(sourceId, targetId, messages, workspaceDir) {
+    const copies = [];
+    const replacements = new Map();
+    const sourceUploads = path.resolve(process.cwd(), "public", "uploads");
+    const result = structuredClone(messages);
+    let folder;
+    const cleanup = async () => {
+        await Promise.all(copies.map((file) => fs.unlink(file).catch(() => { })));
+        // Resolve and check the generated UUID directory before removing anything recursively.
+        if (folder && path.basename(path.resolve(folder)) === targetId)
+            await fs.rm(path.resolve(folder), { recursive: true, force: true });
+        if (folder)
+            await saveRegistry(targetId, [], workspaceDir);
+    };
+    try {
+        // Only server-stored attachment URLs are allowed to select upload files.
+        for (const message of result) {
+            const attachment = message.attachment;
+            if (!attachment?.url?.startsWith("/uploads/"))
+                continue;
+            if (replacements.has(attachment.url))
+                continue;
+            const relative = decodeURIComponent(attachment.url.slice("/uploads/".length));
+            const source = path.resolve(sourceUploads, relative);
+            if (!source.startsWith(sourceUploads + path.sep))
+                throw new Error("附件路径无效");
+            const name = `${targetId}-${randomUUID()}${path.extname(source)}`;
+            const target = path.join(sourceUploads, name);
+            try {
+                await fs.copyFile(source, target, fs.constants.COPYFILE_EXCL);
+            }
+            catch {
+                throw new Error("附件文件不可用，未创建分支");
+            }
+            copies.push(target);
+            replacements.set(attachment.url, `/uploads/${name}`);
+            replacements.set(`/attachments/${relative}`, `/attachments/${name}`);
+        }
+        folder = await ensureSessionDir(targetId, workspaceDir);
+        const staging = path.join(workspaceDir ? path.resolve(workspaceDir) : folder, "attachments");
+        for (const url of replacements.values()) {
+            if (!url.startsWith("/uploads/"))
+                continue;
+            const name = path.basename(url);
+            await fs.mkdir(staging, { recursive: true });
+            const target = path.join(staging, name);
+            await fs.copyFile(path.join(sourceUploads, name), target, fs.constants.COPYFILE_EXCL);
+            copies.push(target);
+        }
+        const files = new Map();
+        const created = new Set();
+        for (const message of result)
+            for (const item of Array.isArray(message.artifacts) ? message.artifacts : []) {
+                if (!item || typeof item.id !== "string" || item.type === "browser")
+                    continue;
+                if (item.change === "added" || !item.change)
+                    created.add(item.id);
+                files.set(item.id, item);
+            }
+        const entries = [];
+        for (const [id, file] of files) {
+            if (file.change === "deleted")
+                continue;
+            const name = sanitizeArtifactName(id);
+            const target = path.resolve(folder, name);
+            if (!target.startsWith(path.resolve(folder) + path.sep))
+                throw new Error("产出物路径无效");
+            const content = typeof file.newContent === "string" ? Buffer.from(file.newContent) : (await readArtifact(sourceId, id, workspaceDir))?.buf;
+            if (!content)
+                throw new Error(`产出物 ${String(file.name ?? id)} 不可用，未创建分支`);
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, content, { flag: "wx" });
+            entries.push({ id: name, name: String(file.name ?? name), absPath: target, type: artifactType(name), origin: "model", createdBySession: created.has(id), lastSeen: true, size: content.length });
+        }
+        await saveRegistry(targetId, entries, workspaceDir);
+        // Rewrite embedded upload links and artifact session URLs throughout message metadata.
+        replacements.set(`/agent-output/${sourceId}/`, `/agent-output/${targetId}/`);
+        replacements.set(`session=${encodeURIComponent(sourceId)}`, `session=${encodeURIComponent(targetId)}`);
+        const rewrite = (value) => {
+            if (typeof value === "string") {
+                for (const [before, after] of replacements)
+                    value = value.split(before).join(after);
+                return value;
+            }
+            if (Array.isArray(value))
+                return value.map(rewrite);
+            if (value && typeof value === "object" && !(value instanceof Date))
+                return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, rewrite(item)]));
+            return value;
+        };
+        return { messages: result.map((message) => {
+                const copied = rewrite(message);
+                if (Array.isArray(copied.artifacts))
+                    copied.artifacts = copied.artifacts.map((file) => {
+                        const entry = entries.find((entry) => entry.id === file.id);
+                        return entry ? { ...file, dir: path.dirname(entry.absPath) } : file;
+                    });
+                return copied;
+            }), cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}

package/dist/server/session-store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * agent-kit · Session 常驻注册表（多轮 + steer 支撑）
+ *
+ * 基于 @tencent-ai/agent-sdk 的 V2 Session API（unstable_v2_createSession）：
+ * 一个前端 sessionId 对应一个常驻 CLI 会话进程，跨轮复用，运行中可插入消息（steer）。
+ *
+ * 为什么不用每轮 query()：
+ *   query() 是单发模式（一轮一 CLI 进程），中途无法插入消息；
+ *   Session API 底层 CLI（>= 2.140.0，bundled 2.158.0）支持 stream-json 的
+ *   steer control_request：消息进入 SteerInputBuffer，在「下一次模型请求前」注入，
+ *   不打断当前正在执行的工具循环——这正是前端「插话/steer」所需的语义。
+ *
+ * steer 通道说明（TS SDK 尚未公开，走 transport 内部通道，官方暴露后可替换）：
+ *   transport.sendControlRequest({
+ *     subtype: "steer",
+ *     session_id: <CLI 侧会话 ID>,          // 从 stream 的 system 消息捕获
+ *     content_blocks: [{ type: "text", text }],
+ *     expected_request_id: <可选，同轮约束>,
+ *   })
+ *   → { steered: true } | { steered: false, reason: "stale" | "idle" }
+ *
+ * 注意：TS 的 private 在运行时只是普通属性，因此可以访问 session._transport
+ * 与 session.getSessionIdForControl()；SDK 升级可能改名，调用处均有防御。
+ */
+import { type Session, type SessionOptions } from "@tencent-ai/agent-sdk";
+export type SteerResult = {
+    steered: boolean;
+    reason?: string;
+    response?: unknown;
+};
+export interface ManagedSession {
+    /** 前端会话 ID（registry key，也是 AskUserQuestion 挂起/产物隔离用的 sid） */
+    sid: string;
+    /** SDK Session 实例（常驻 CLI 进程；Session 接口不含 interrupt/setCanUseTool，调用处断言） */
+    session: Session;
+    /** CLI 侧会话 ID（从 stream 的 system 消息捕获；steer control_request 需要它） */
+    cliSessionId: string | null;
+    lastActiveAt: number;
+    createdAt: number;
+}
+export declare function getManagedSession(sid: string): ManagedSession | undefined;
+export declare function createManagedSession(sid: string, options: SessionOptions): ManagedSession;
+/** 首轮 stream 的 system 消息会携带 CLI 侧会话 ID，捕获后供 steer 使用（只取第一个） */
+export declare function setCliSessionId(sid: string, cliSessionId: string): void;
+export declare function touchSession(sid: string): void;
+/**
+ * 运行中插入消息（steer）：走 CLI 2.140.0+ 的 stream-json steer 控制通道。
+ * 返回 { steered: true } 表示已进入缓冲，将在下一次模型请求前注入。
+ */
+export declare function steerSession(sid: string, text: string): Promise<SteerResult>;
+/** 中断当前轮的模型执行（前端"停止生成"→ request.signal abort → 本函数） */
+export declare function interruptSession(sid: string): Promise<void>;
+export declare function closeSession(sid: string): void;
+export declare function getSessionCount(): number;
+/** 惰性启动空闲回收（Node 环境；.unref 让定时器不阻塞进程退出） */
+export declare function startSessionSweeper(): void;

package/dist/server/session-store.js

@@ -0,0 +1,148 @@
+/**
+ * agent-kit · Session 常驻注册表（多轮 + steer 支撑）
+ *
+ * 基于 @tencent-ai/agent-sdk 的 V2 Session API（unstable_v2_createSession）：
+ * 一个前端 sessionId 对应一个常驻 CLI 会话进程，跨轮复用，运行中可插入消息（steer）。
+ *
+ * 为什么不用每轮 query()：
+ *   query() 是单发模式（一轮一 CLI 进程），中途无法插入消息；
+ *   Session API 底层 CLI（>= 2.140.0，bundled 2.158.0）支持 stream-json 的
+ *   steer control_request：消息进入 SteerInputBuffer，在「下一次模型请求前」注入，
+ *   不打断当前正在执行的工具循环——这正是前端「插话/steer」所需的语义。
+ *
+ * steer 通道说明（TS SDK 尚未公开，走 transport 内部通道，官方暴露后可替换）：
+ *   transport.sendControlRequest({
+ *     subtype: "steer",
+ *     session_id: <CLI 侧会话 ID>,          // 从 stream 的 system 消息捕获
+ *     content_blocks: [{ type: "text", text }],
+ *     expected_request_id: <可选，同轮约束>,
+ *   })
+ *   → { steered: true } | { steered: false, reason: "stale" | "idle" }
+ *
+ * 注意：TS 的 private 在运行时只是普通属性，因此可以访问 session._transport
+ * 与 session.getSessionIdForControl()；SDK 升级可能改名，调用处均有防御。
+ */
+import { unstable_v2_createSession } from "@tencent-ai/agent-sdk";
+import { slog } from "./debug-log.js";
+const registry = new Map();
+/** 空闲回收：会话超过该时长无任何活动则关闭 CLI 进程，避免常驻进程堆积 */
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000;
+let sweeper = null;
+export function getManagedSession(sid) {
+    const entry = registry.get(sid);
+    if (entry)
+        entry.lastActiveAt = Date.now();
+    return entry;
+}
+export function createManagedSession(sid, options) {
+    const session = unstable_v2_createSession({ ...options });
+    const entry = {
+        sid,
+        session: session,
+        cliSessionId: null,
+        lastActiveAt: Date.now(),
+        createdAt: Date.now(),
+    };
+    registry.set(sid, entry);
+    console.log(`[agent-kit] Session 已创建 sid=${sid}（registry=${registry.size}）`);
+    slog(sid, "session.created", { registrySize: registry.size }, "info");
+    return entry;
+}
+/** 首轮 stream 的 system 消息会携带 CLI 侧会话 ID，捕获后供 steer 使用（只取第一个） */
+export function setCliSessionId(sid, cliSessionId) {
+    const entry = registry.get(sid);
+    if (entry && !entry.cliSessionId)
+        entry.cliSessionId = cliSessionId;
+}
+export function touchSession(sid) {
+    const entry = registry.get(sid);
+    if (entry)
+        entry.lastActiveAt = Date.now();
+}
+/**
+ * 运行中插入消息（steer）：走 CLI 2.140.0+ 的 stream-json steer 控制通道。
+ * 返回 { steered: true } 表示已进入缓冲，将在下一次模型请求前注入。
+ */
+export async function steerSession(sid, text) {
+    const entry = registry.get(sid);
+    if (!entry) {
+        slog(sid, "steer.reject", { reason: "no_session" }, "warn");
+        return { steered: false, reason: "no_session" };
+    }
+    const session = entry.session;
+    const transport = session._transport;
+    if (!transport?.sendControlRequest) {
+        slog(sid, "steer.reject", { reason: "no_transport" }, "warn");
+        return { steered: false, reason: "no_transport" };
+    }
+    const cliSessionId = entry.cliSessionId ?? session.getSessionIdForControl?.();
+    if (!cliSessionId) {
+        slog(sid, "steer.reject", { reason: "no_session_id" }, "warn");
+        return { steered: false, reason: "no_session_id" };
+    }
+    try {
+        slog(sid, "steer.request", { cliSessionId, textLen: text.length, text }, "info");
+        const resp = (await transport.sendControlRequest({
+            subtype: "steer",
+            session_id: cliSessionId,
+            content_blocks: [{ type: "text", text }],
+        }));
+        entry.lastActiveAt = Date.now();
+        const steered = resp?.steered === true;
+        console.log(`[agent-kit] steer sid=${sid} steered=${steered}${steered ? "" : ` reason=${resp?.reason ?? "unknown"}`}`);
+        slog(sid, "steer.response", { steered, reason: resp?.reason ?? null, response: resp }, "info");
+        return { steered, reason: resp?.reason, response: resp };
+    }
+    catch (err) {
+        console.error(`[agent-kit] steer 请求异常 sid=${sid}:`, err instanceof Error ? err.message : err);
+        slog(sid, "steer.error", { error: err instanceof Error ? err.message : String(err) }, "error");
+        return { steered: false, reason: "error" };
+    }
+}
+/** 中断当前轮的模型执行（前端"停止生成"→ request.signal abort → 本函数） */
+export async function interruptSession(sid) {
+    const entry = registry.get(sid);
+    if (!entry)
+        return;
+    try {
+        // Session 接口未声明 interrupt（SessionImpl 才有）；运行时存在，防御性调用
+        await entry.session.interrupt();
+        slog(sid, "session.interrupt", {}, "info");
+    }
+    catch (err) {
+        console.warn(`[agent-kit] interrupt sid=${sid}:`, err instanceof Error ? err.message : err);
+        slog(sid, "session.interrupt.error", { error: err instanceof Error ? err.message : String(err) }, "warn");
+    }
+}
+export function closeSession(sid) {
+    const entry = registry.get(sid);
+    if (!entry)
+        return;
+    try {
+        entry.session.close();
+    }
+    catch { /* ignore */ }
+    registry.delete(sid);
+    console.log(`[agent-kit] Session 已关闭 sid=${sid}（registry=${registry.size}）`);
+    slog(sid, "session.closed", { registrySize: registry.size }, "info");
+}
+export function getSessionCount() {
+    return registry.size;
+}
+/** 惰性启动空闲回收（Node 环境；.unref 让定时器不阻塞进程退出） */
+export function startSessionSweeper() {
+    if (sweeper)
+        return;
+    sweeper = setInterval(() => {
+        const now = Date.now();
+        for (const [sid, entry] of registry) {
+            if (now - entry.lastActiveAt > IDLE_TIMEOUT_MS) {
+                console.log(`[agent-kit] 回收空闲会话 ${sid}（${Math.round((now - entry.lastActiveAt) / 1000)}s 无活动）`);
+                closeSession(sid);
+            }
+        }
+    }, SWEEP_INTERVAL_MS);
+    if (typeof sweeper.unref === "function")
+        sweeper.unref();
+}

package/dist/server/sessions.d.ts

@@ -0,0 +1,24 @@
+/** POST /api/admin/login：校验 admin/admin，成功签发登录 Cookie。 */
+declare function adminLogin(request: Request): Promise<Response>;
+/** POST /api/admin/logout：清除 admin 登录 Cookie。 */
+declare function adminLogout(): Response;
+/** 跑一次极简 LLM 调用，把用户首条消息总结成 6-12 字中文标题（fire-and-forget，失败返回空串）。
+ *  失败不打扰对话：标题保持快速占位（deriveQuickTitle）。 */
+export declare function summarizeSessionTitle(userMessage: string): Promise<string>;
+export declare function createSessionHandlers(): {
+    list: (request: Request) => Promise<Response>;
+    create: (request: Request) => Promise<Response>;
+    rename: (request: Request, ctx: unknown) => Promise<Response>;
+    remove: (request: Request, ctx: unknown) => Promise<Response>;
+    messages: (request: Request, ctx: unknown) => Promise<Response>;
+    appendMessage: (request: Request, ctx: unknown) => Promise<Response>;
+    autoTitle: (request: Request, ctx: unknown) => Promise<Response>;
+    truncate: (request: Request, ctx: unknown) => Promise<Response>;
+    fork: (request: Request, ctx: unknown) => Promise<Response>;
+    closeSdk: (request: Request, ctx: unknown) => Promise<Response>;
+    adminUsage: (request: Request) => Promise<Response>;
+    adminLogin: typeof adminLogin;
+    adminLogout: typeof adminLogout;
+    modelContext: (request: Request) => Promise<Response>;
+};
+export {};