@jingyi0605/codingns 0.9.0 → 0.9.5

package/dist/server/modules/affairs-indexer/core/src/sqlite/open-database.d.ts

@@ -1,9 +1,26 @@
-import { DatabaseSync } from "node:sqlite";
 export interface OpenDatabaseOptions {
     tempStore?: "FILE" | "MEMORY";
 }
+export interface AffairsIndexerRunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+/**
+ * affairs-indexer 只需要同步 SQL 的最小接口。
+ * 不直接暴露 better-sqlite3 的完整 Statement 类型，避免它的绑定参数类型把运行时允许的多参数调用误报成错误。
+ */
+export interface AffairsIndexerStatement {
+    run(...params: unknown[]): AffairsIndexerRunResult;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+export interface AffairsIndexerDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): AffairsIndexerStatement;
+    close(): void;
+}
 /**
  * 打开 SQLite 数据库。
- * 当前阶段统一使用 Node 内置 sqlite，同步接口足够支撑 CLI 初始化与检测。
+ * 这里统一走 better-sqlite3，避免 helper 子进程加载 Node 实验性的 node:sqlite。
  */
-export declare function openDatabase(dbPath: string, options?: OpenDatabaseOptions): DatabaseSync;
+export declare function openDatabase(dbPath: string, options?: OpenDatabaseOptions): AffairsIndexerDatabase;

package/dist/server/modules/affairs-indexer/core/src/sqlite/open-database.js

@@ -1,13 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
-import { DatabaseSync } from "node:sqlite";
+import Database from "../../../../../shared/runtime/better-sqlite3.js";
 /**
  * 打开 SQLite 数据库。
- * 当前阶段统一使用 Node 内置 sqlite，同步接口足够支撑 CLI 初始化与检测。
+ * 这里统一走 better-sqlite3，避免 helper 子进程加载 Node 实验性的 node:sqlite。
  */
 export function openDatabase(dbPath, options = {}) {
     fs.mkdirSync(path.dirname(dbPath), { recursive: true });
-    const db = new DatabaseSync(dbPath);
+    const db = new Database(dbPath);
     const tempStore = options.tempStore ?? "FILE";
     db.exec("PRAGMA journal_mode=WAL;");
     db.exec("PRAGMA synchronous=NORMAL;");

package/dist/server/modules/affairs-indexer/core/src/sqlite/open-database.js.map

@@ -1 +1 @@
-{"version":3,"file":"open-database.js","sourceRoot":"","sources":["../../../../../../../src/modules/affairs-indexer/core/src/sqlite/open-database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,UAA+B,EAAE;IAEjC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,EAAE,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACpC,EAAE,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACtC,EAAE,CAAC,IAAI,CAAC,qBAAqB,SAAS,GAAG,CAAC,CAAC;IAC3C,EAAE,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACnC,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"open-database.js","sourceRoot":"","sources":["../../../../../../../src/modules/affairs-indexer/core/src/sqlite/open-database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,QAAQ,MAAM,iDAAiD,CAAC;AA2BvE;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAc,EACd,UAA+B,EAAE;IAEjC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAsC,CAAC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,EAAE,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACpC,EAAE,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;IACtC,EAAE,CAAC,IAAI,CAAC,qBAAqB,SAAS,GAAG,CAAC,CAAC;IAC3C,EAAE,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACnC,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/server/modules/butler/assistant-sandbox-cleanup-scheduler.d.ts

@@ -0,0 +1,32 @@
+import { type SchedulerMetrics } from "../tasks/scheduler-metrics.js";
+import type { AssistantSandboxService } from "./assistant-sandbox-service.js";
+interface AssistantSandboxCleanupSchedulerLogger {
+    error(message: string, detail?: unknown): void;
+}
+interface AssistantSandboxCleanupSchedulerOptions {
+    intervalMs?: number;
+    maxIntervalMs?: number;
+    now?: () => string;
+    logger?: AssistantSandboxCleanupSchedulerLogger;
+    schedulerMetrics?: SchedulerMetrics;
+}
+export declare class AssistantSandboxCleanupScheduler {
+    private readonly assistantSandboxService;
+    private readonly intervalMs;
+    private readonly maxIntervalMs;
+    private readonly now;
+    private readonly logger;
+    private readonly schedulerMetrics;
+    private timer;
+    private ticking;
+    private started;
+    private disposed;
+    private idleStreak;
+    constructor(assistantSandboxService: Pick<AssistantSandboxService, "runDueCleanup">, options?: AssistantSandboxCleanupSchedulerOptions);
+    start(): void;
+    dispose(): Promise<void>;
+    runOnce(): Promise<void>;
+    private scheduleNext;
+    private tick;
+}
+export {};

package/dist/server/modules/butler/assistant-sandbox-cleanup-scheduler.js

@@ -0,0 +1,93 @@
+import { nowIso } from "../../shared/utils/time.js";
+import { resolveAdaptiveSchedulerDelayMs } from "../tasks/scheduler-metrics.js";
+const DEFAULT_INTERVAL_MS = 60_000;
+export class AssistantSandboxCleanupScheduler {
+    assistantSandboxService;
+    intervalMs;
+    maxIntervalMs;
+    now;
+    logger;
+    schedulerMetrics;
+    timer = null;
+    ticking = false;
+    started = false;
+    disposed = false;
+    idleStreak = 0;
+    constructor(assistantSandboxService, options = {}) {
+        this.assistantSandboxService = assistantSandboxService;
+        this.intervalMs = Math.max(15_000, options.intervalMs ?? DEFAULT_INTERVAL_MS);
+        this.maxIntervalMs = Math.max(this.intervalMs, options.maxIntervalMs ?? this.intervalMs * 8);
+        this.now = options.now ?? nowIso;
+        this.logger = options.logger ?? console;
+        this.schedulerMetrics = options.schedulerMetrics ?? null;
+    }
+    start() {
+        if (this.timer || this.disposed) {
+            return;
+        }
+        this.started = true;
+        this.scheduleNext(0);
+    }
+    async dispose() {
+        this.started = false;
+        this.disposed = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        while (this.ticking) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    async runOnce() {
+        await this.tick(false);
+    }
+    scheduleNext(delayMs) {
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick();
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    async tick(shouldScheduleNext = true) {
+        if (this.ticking) {
+            return;
+        }
+        this.ticking = true;
+        const tickStartedAt = Date.now();
+        const referenceAt = this.now();
+        let result = null;
+        let errorCount = 0;
+        try {
+            result = await this.assistantSandboxService.runDueCleanup(referenceAt);
+        }
+        catch (error) {
+            errorCount = 1;
+            this.logger.error("[assistant-sandbox-cleanup-scheduler] tick failed", {
+                error: error instanceof Error ? error.message : String(error),
+                referenceAt
+            });
+        }
+        finally {
+            this.ticking = false;
+            const idle = result?.idle ?? true;
+            const taskCount = result?.dueSandboxCount ?? 0;
+            this.idleStreak = idle ? this.idleStreak + 1 : 0;
+            const nextDelayMs = resolveAdaptiveSchedulerDelayMs(this.intervalMs, this.maxIntervalMs, this.idleStreak);
+            this.schedulerMetrics?.recordTick({
+                schedulerName: "assistant_sandbox_cleanup",
+                referenceAt,
+                durationMs: Date.now() - tickStartedAt,
+                taskCount,
+                idle,
+                errorCount,
+                nextDelayMs,
+                idleStreak: this.idleStreak
+            });
+            if (shouldScheduleNext && this.started && !this.disposed && this.timer === null) {
+                this.scheduleNext(nextDelayMs);
+            }
+        }
+    }
+}
+//# sourceMappingURL=assistant-sandbox-cleanup-scheduler.js.map

package/dist/server/modules/butler/assistant-sandbox-cleanup-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-sandbox-cleanup-scheduler.js","sourceRoot":"","sources":["../../../../src/modules/butler/assistant-sandbox-cleanup-scheduler.ts"],"names":[],"mappings":"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"}

package/dist/server/modules/butler/assistant-sandbox-service.d.ts

@@ -0,0 +1,69 @@
+import type { AssistantSandboxWorkspace, Workspace } from "../../types/domain.js";
+import type { AssistantSandboxWorkspaceRepository } from "../../storage/repositories/assistant-sandbox-workspace-repository.js";
+import type { ButlerProfileService } from "./butler-profile-service.js";
+import type { ButlerProjectService } from "./butler-project-service.js";
+import { type TaskManager } from "../tasks/task-manager.js";
+import type { CloneWorkspaceInput, WorkspaceService } from "../workspace/workspace-service.js";
+export interface AssistantSandboxWorkspaceView extends AssistantSandboxWorkspace {
+    workspace: Workspace | null;
+}
+export interface CreateAssistantSandboxInput {
+    userId: string;
+    controlSessionId?: string | null;
+    title?: string | null;
+    description?: string | null;
+    purpose?: string | null;
+    expiresAt?: string | null;
+    source: {
+        kind: "blank";
+        directoryName?: string | null;
+    } | {
+        kind: "clone";
+        repositoryUrl: string;
+        directoryName?: string | null;
+        auth?: CloneWorkspaceInput["auth"];
+    };
+}
+export interface PromoteAssistantSandboxInput {
+    mode?: "pin" | "project";
+    projectName?: string | null;
+    defaultProvider?: "codex" | "claude-code" | null;
+}
+export interface AssistantSandboxCleanupResult {
+    dueSandboxCount: number;
+    cleanedSandboxCount: number;
+    idle: boolean;
+}
+export declare class AssistantSandboxService {
+    private readonly repository;
+    private readonly butlerProfileService;
+    private readonly workspaceService;
+    private readonly butlerProjectService?;
+    private readonly taskManager;
+    constructor(repository: AssistantSandboxWorkspaceRepository, butlerProfileService: Pick<ButlerProfileService, "getProfile">, workspaceService: Pick<WorkspaceService, "importWorkspace" | "cloneWorkspace" | "removeWorkspace" | "getWorkspaceOrThrow">, butlerProjectService?: Pick<ButlerProjectService, "create"> | undefined, taskManager?: TaskManager);
+    listSandboxes(filters: {
+        userId: string;
+        controlSessionId?: string | null;
+        statuses?: Array<"active" | "archived" | "expired" | "orphaned" | "deleted">;
+        limit?: number;
+    }): AssistantSandboxWorkspaceView[];
+    getSandbox(sandboxId: string, userId: string): AssistantSandboxWorkspaceView;
+    createSandbox(input: CreateAssistantSandboxInput): Promise<AssistantSandboxWorkspaceView>;
+    promoteSandbox(sandboxId: string, userId: string, input?: PromoteAssistantSandboxInput): AssistantSandboxWorkspaceView;
+    markSandboxUsedByControlSession(sandboxId: string, userId: string, controlSessionId: string | null): AssistantSandboxWorkspaceView;
+    markSandboxOrphanedByWorkspaceId(workspaceId: string, userId: string): AssistantSandboxWorkspaceView | null;
+    expireSandbox(sandboxId: string, userId: string): AssistantSandboxWorkspaceView;
+    removeSandbox(sandboxId: string, userId: string): AssistantSandboxWorkspaceView;
+    runDueCleanup(referenceAt: string): Promise<AssistantSandboxCleanupResult>;
+    resolveWorkspaceId(sandboxId: string, userId: string): string;
+    private registerBackgroundTasks;
+    private runDueCleanupDirect;
+    private cleanupSandboxDirect;
+    private createBlankWorkspace;
+    private createCloneWorkspace;
+    private ensureSandboxRootPath;
+    private resolveSandboxRootPath;
+    private removeSandboxDirectoryIfSafe;
+    private requireSandbox;
+    private toView;
+}

package/dist/server/modules/butler/assistant-sandbox-service.js

@@ -0,0 +1,399 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../../shared/errors/app-error.js";
+import { createId } from "../../shared/utils/id.js";
+import { nowIso } from "../../shared/utils/time.js";
+import { createTaskManager } from "../tasks/task-manager.js";
+import { HOST_TASK_TYPES } from "../tasks/task-types.js";
+const DEFAULT_SANDBOX_RETENTION_DAYS = 30;
+const DEFAULT_SANDBOX_CLEANUP_LIMIT = 20;
+export class AssistantSandboxService {
+    repository;
+    butlerProfileService;
+    workspaceService;
+    butlerProjectService;
+    taskManager;
+    constructor(repository, butlerProfileService, workspaceService, butlerProjectService, taskManager = createTaskManager()) {
+        this.repository = repository;
+        this.butlerProfileService = butlerProfileService;
+        this.workspaceService = workspaceService;
+        this.butlerProjectService = butlerProjectService;
+        this.taskManager = taskManager;
+        this.registerBackgroundTasks();
+    }
+    listSandboxes(filters) {
+        return this.repository
+            .list({
+            userId: filters.userId,
+            controlSessionId: filters.controlSessionId ?? null,
+            statuses: filters.statuses,
+            limit: filters.limit
+        })
+            .map((record) => this.toView(record));
+    }
+    getSandbox(sandboxId, userId) {
+        return this.toView(this.requireSandbox(sandboxId, userId));
+    }
+    async createSandbox(input) {
+        const timestamp = nowIso();
+        const sandboxRootPath = this.ensureSandboxRootPath();
+        const workspace = input.source.kind === "blank"
+            ? this.createBlankWorkspace(sandboxRootPath, input)
+            : await this.createCloneWorkspace(sandboxRootPath, input);
+        const record = this.repository.create({
+            id: createId(),
+            userId: input.userId,
+            workspaceId: workspace.id,
+            controlSessionId: normalizeNullableText(input.controlSessionId),
+            title: normalizeSandboxTitle(input.title, workspace.name),
+            description: normalizeNullableText(input.description),
+            sourceKind: input.source.kind,
+            sourceRef: input.source.kind === "clone"
+                ? normalizeNullableText(input.source.repositoryUrl)
+                : workspace.path,
+            visibility: "assistant_only",
+            status: "active",
+            purpose: normalizeNullableText(input.purpose),
+            expiresAt: normalizeNullableIsoTime(input.expiresAt, "expiresAt"),
+            promotedAt: null,
+            createdAt: timestamp,
+            updatedAt: timestamp
+        });
+        return this.toView(record);
+    }
+    promoteSandbox(sandboxId, userId, input = {}) {
+        const current = this.requireSandbox(sandboxId, userId);
+        const promotedAt = nowIso();
+        const updated = this.repository.update({
+            ...current,
+            controlSessionId: null,
+            visibility: "pinned",
+            status: "active",
+            expiresAt: null,
+            promotedAt: current.promotedAt ?? promotedAt,
+            updatedAt: promotedAt
+        });
+        if (input.mode === "project") {
+            if (!this.butlerProjectService) {
+                throw new AppError({
+                    statusCode: 500,
+                    errorCode: "ASSISTANT_SANDBOX_PROMOTE_UNAVAILABLE",
+                    detail: "当前环境未启用沙箱晋升为项目的能力"
+                });
+            }
+            const workspace = this.workspaceService.getWorkspaceOrThrow(updated.workspaceId);
+            this.butlerProjectService.create({
+                workspaceId: workspace.id,
+                name: normalizeNullableText(input.projectName) ?? workspace.name,
+                repoRoot: workspace.repoRoot ?? workspace.path,
+                defaultProvider: input.defaultProvider ?? null,
+                config: {
+                    createdFrom: "assistant_sandbox",
+                    sandboxId: updated.id
+                }
+            });
+        }
+        return this.toView(updated);
+    }
+    markSandboxUsedByControlSession(sandboxId, userId, controlSessionId) {
+        const current = this.requireSandbox(sandboxId, userId);
+        const nextControlSessionId = normalizeNullableText(controlSessionId);
+        if (current.controlSessionId === nextControlSessionId) {
+            return this.toView(current);
+        }
+        const updated = this.repository.update({
+            ...current,
+            controlSessionId: nextControlSessionId,
+            updatedAt: nowIso()
+        });
+        return this.toView(updated);
+    }
+    markSandboxOrphanedByWorkspaceId(workspaceId, userId) {
+        const current = this.repository.findByWorkspaceId(workspaceId.trim());
+        if (!current || current.userId !== userId) {
+            return null;
+        }
+        if (current.status === "deleted") {
+            return this.toView(current);
+        }
+        const updatedAt = nowIso();
+        const nextStatus = isAutomaticCleanupProtected(current) ? current.status : "orphaned";
+        const updated = this.repository.update({
+            ...current,
+            controlSessionId: null,
+            status: nextStatus,
+            expiresAt: nextStatus === "orphaned" ? addDaysIso(updatedAt, DEFAULT_SANDBOX_RETENTION_DAYS) : null,
+            updatedAt
+        });
+        return this.toView(updated);
+    }
+    expireSandbox(sandboxId, userId) {
+        const current = this.requireSandbox(sandboxId, userId);
+        const updatedAt = nowIso();
+        const updated = this.repository.update({
+            ...current,
+            status: "expired",
+            updatedAt
+        });
+        return this.toView(updated);
+    }
+    removeSandbox(sandboxId, userId) {
+        const current = this.requireSandbox(sandboxId, userId);
+        const updatedAt = nowIso();
+        try {
+            this.workspaceService.removeWorkspace(current.workspaceId);
+        }
+        catch {
+            // 工作区可能已被清理或移除；这里仍然收口元数据，避免残留不可操作沙箱。
+        }
+        const updated = this.repository.update({
+            ...current,
+            status: "deleted",
+            updatedAt
+        });
+        return this.toView(updated);
+    }
+    async runDueCleanup(referenceAt) {
+        return await this.taskManager.enqueue(HOST_TASK_TYPES.assistantSandboxTick, {
+            key: "global",
+            source: "assistant_sandbox.run_due_cleanup",
+            input: {
+                referenceAt
+            }
+        }).promise;
+    }
+    resolveWorkspaceId(sandboxId, userId) {
+        const sandbox = this.requireSandbox(sandboxId, userId);
+        if (sandbox.status === "deleted") {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "ASSISTANT_SANDBOX_UNAVAILABLE",
+                detail: "该沙箱已经删除，不能再用于启动会话"
+            });
+        }
+        if (sandbox.status === "expired") {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "ASSISTANT_SANDBOX_UNAVAILABLE",
+                detail: "该沙箱已过期，不能再用于启动会话"
+            });
+        }
+        if (sandbox.status === "orphaned") {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "ASSISTANT_SANDBOX_UNAVAILABLE",
+                detail: "该沙箱已经孤立，不能再用于启动会话"
+            });
+        }
+        return sandbox.workspaceId;
+    }
+    registerBackgroundTasks() {
+        if (!this.taskManager.has(HOST_TASK_TYPES.assistantSandboxTick)) {
+            this.taskManager.register({
+                taskType: HOST_TASK_TYPES.assistantSandboxTick,
+                executionLane: "host_background",
+                timeoutMs: 10_000,
+                run: async ({ referenceAt }) => await this.runDueCleanupDirect(referenceAt)
+            });
+        }
+        if (!this.taskManager.has(HOST_TASK_TYPES.assistantSandboxCleanup)) {
+            this.taskManager.register({
+                taskType: HOST_TASK_TYPES.assistantSandboxCleanup,
+                executionLane: "host_background",
+                timeoutMs: 10_000,
+                run: async ({ sandboxId, referenceAt }) => {
+                    return this.cleanupSandboxDirect(sandboxId, referenceAt);
+                }
+            });
+        }
+    }
+    async runDueCleanupDirect(referenceAt) {
+        const dueSandboxes = this.repository.listDueCleanup(referenceAt, DEFAULT_SANDBOX_CLEANUP_LIMIT);
+        const handles = dueSandboxes.map((sandbox) => this.taskManager.enqueue(HOST_TASK_TYPES.assistantSandboxCleanup, {
+            key: sandbox.id,
+            source: "assistant_sandbox.tick.cleanup",
+            input: {
+                sandboxId: sandbox.id,
+                referenceAt
+            }
+        }));
+        const results = await Promise.all(handles.map((handle) => handle.promise));
+        const cleanedSandboxCount = results.filter(Boolean).length;
+        return {
+            dueSandboxCount: dueSandboxes.length,
+            cleanedSandboxCount,
+            idle: dueSandboxes.length === 0
+        };
+    }
+    async cleanupSandboxDirect(sandboxId, referenceAt) {
+        const current = this.repository.findById(sandboxId);
+        if (!current || current.status !== "orphaned" || !current.expiresAt || current.expiresAt > referenceAt) {
+            return false;
+        }
+        if (isAutomaticCleanupProtected(current)) {
+            this.repository.update({
+                ...current,
+                status: "active",
+                expiresAt: null,
+                updatedAt: nowIso()
+            });
+            return false;
+        }
+        await this.removeSandboxDirectoryIfSafe(current);
+        this.removeSandbox(current.id, current.userId);
+        return true;
+    }
+    createBlankWorkspace(sandboxRootPath, input) {
+        if (input.source.kind !== "blank") {
+            throw new Error("invalid blank sandbox input");
+        }
+        const directoryName = normalizeSandboxDirectoryName(input.source.directoryName, input.title);
+        const sandboxPath = path.join(sandboxRootPath, directoryName);
+        if (fs.existsSync(sandboxPath)) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "ASSISTANT_SANDBOX_EXISTS",
+                detail: "目标沙箱目录已存在，请换一个名称",
+                field: "directoryName"
+            });
+        }
+        fs.mkdirSync(sandboxPath, { recursive: true });
+        return this.workspaceService.importWorkspace(sandboxPath, normalizeNullableText(input.title) ?? directoryName);
+    }
+    async createCloneWorkspace(sandboxRootPath, input) {
+        if (input.source.kind !== "clone") {
+            throw new Error("invalid clone sandbox input");
+        }
+        return await this.workspaceService.cloneWorkspace({
+            repositoryUrl: input.source.repositoryUrl,
+            parentPath: sandboxRootPath,
+            directoryName: normalizeSandboxDirectoryName(input.source.directoryName, input.title, input.source.repositoryUrl),
+            name: normalizeNullableText(input.title) ?? undefined,
+            auth: input.source.auth
+        });
+    }
+    ensureSandboxRootPath() {
+        const sandboxRootPath = this.resolveSandboxRootPath();
+        fs.mkdirSync(sandboxRootPath, { recursive: true });
+        return sandboxRootPath;
+    }
+    resolveSandboxRootPath() {
+        const profile = this.butlerProfileService.getProfile();
+        if (!profile) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "BUTLER_PROFILE_NOT_INITIALIZED",
+                detail: "代码助手尚未完成初始化，不能创建沙箱工作区"
+            });
+        }
+        const workspacePath = profile.workspacePath;
+        return path.join(path.resolve(workspacePath), "sandboxes");
+    }
+    async removeSandboxDirectoryIfSafe(record) {
+        const sandboxPath = this.toView(record).workspace?.path?.trim() || null;
+        if (!sandboxPath) {
+            return;
+        }
+        const resolvedSandboxPath = path.resolve(sandboxPath);
+        const sandboxRootPath = this.resolveSandboxRootPath();
+        if (!isPathInsideDirectory(resolvedSandboxPath, sandboxRootPath)) {
+            throw new AppError({
+                statusCode: 409,
+                errorCode: "ASSISTANT_SANDBOX_DELETE_PATH_UNSAFE",
+                detail: "沙箱目录不在允许清理的沙箱根目录内，已拒绝自动删除"
+            });
+        }
+        await fs.promises.rm(resolvedSandboxPath, {
+            recursive: true,
+            force: true
+        });
+    }
+    requireSandbox(sandboxId, userId) {
+        const sandbox = this.repository.findById(sandboxId.trim());
+        if (!sandbox || sandbox.userId !== userId) {
+            throw new AppError({
+                statusCode: 404,
+                errorCode: "ASSISTANT_SANDBOX_NOT_FOUND",
+                detail: "未找到对应的助手沙箱"
+            });
+        }
+        return sandbox;
+    }
+    toView(record) {
+        try {
+            return {
+                ...record,
+                workspace: this.workspaceService.getWorkspaceOrThrow(record.workspaceId)
+            };
+        }
+        catch {
+            return {
+                ...record,
+                workspace: null
+            };
+        }
+    }
+}
+function isAutomaticCleanupProtected(sandbox) {
+    return sandbox.visibility === "pinned" || sandbox.promotedAt !== null;
+}
+function normalizeNullableText(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : null;
+}
+function normalizeSandboxTitle(input, fallback) {
+    return normalizeNullableText(input) ?? fallback;
+}
+function normalizeSandboxDirectoryName(requestedName, title, repositoryUrl) {
+    const normalized = normalizeNullableText(requestedName)
+        ?? slugifyPathSegment(normalizeNullableText(title) ?? inferRepositoryName(repositoryUrl) ?? `sandbox-${createId().slice(0, 8)}`);
+    if (!normalized) {
+        throw new AppError({
+            statusCode: 400,
+            errorCode: "INVALID_INPUT",
+            detail: "沙箱目录名不能为空",
+            field: "directoryName"
+        });
+    }
+    return normalized;
+}
+function inferRepositoryName(repositoryUrl) {
+    const normalized = normalizeNullableText(repositoryUrl);
+    if (!normalized) {
+        return null;
+    }
+    const tail = normalized.split("/").pop() ?? "";
+    return tail.replace(/\.git$/i, "").trim() || null;
+}
+function slugifyPathSegment(value) {
+    const normalized = value
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return normalized.slice(0, 64);
+}
+function normalizeNullableIsoTime(value, field) {
+    const normalized = normalizeNullableText(value);
+    if (!normalized) {
+        return null;
+    }
+    const timestamp = Date.parse(normalized);
+    if (Number.isNaN(timestamp)) {
+        throw new AppError({
+            statusCode: 400,
+            errorCode: "INVALID_INPUT",
+            detail: `${field} 必须是合法的 ISO 时间`,
+            field
+        });
+    }
+    return new Date(timestamp).toISOString();
+}
+function addDaysIso(referenceAt, days) {
+    return new Date(new Date(referenceAt).getTime() + days * 24 * 60 * 60 * 1000).toISOString();
+}
+function isPathInsideDirectory(candidatePath, parentPath) {
+    const relative = path.relative(path.resolve(parentPath), path.resolve(candidatePath));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+//# sourceMappingURL=assistant-sandbox-service.js.map