@kiturone/kapibala 0.0.8 → 0.0.10

package/dist/index.cjs

@@ -103,6 +103,7 @@ __export(index_exports, {
   createLogId: () => createLogId,
   createMessageId: () => createMessageId,
   createRunCommandTool: () => createRunCommandTool,
+  createSessionError: () => createSessionError,
   createSpawnAgentTool: () => createSpawnAgentTool,
   createWaitAgentTool: () => createWaitAgentTool,
   defineTool: () => defineTool,
@@ -158,7 +159,6 @@ __export(index_exports, {
   sanitizeModelErrorMessage: () => sanitizeModelErrorMessage,
   sanitizeSessionTitle: () => sanitizeSessionTitle,
   scanSkillRoot: () => scanSkillRoot,
-  sharedWorkspaceLeaseCoordinator: () => sharedWorkspaceLeaseCoordinator,
   skillDigest: () => skillDigest,
   skillFailure: () => skillFailure,
   skillPathKey: () => skillPathKey,
@@ -308,6 +308,21 @@ var KapibalaError = class extends Error {
     this.dispatchOutcome = options?.dispatchOutcome;
   }
 };
+var SESSION_SAFE_MESSAGES = {
+  SESSION_LOCKED: "\u4F1A\u8BDD\u5DF2\u88AB\u5176\u4ED6\u6301\u6709\u8005\u5360\u7528",
+  SESSION_RECOVERY_IN_PROGRESS: "\u4F1A\u8BDD\u6B63\u5728\u6062\u590D",
+  SESSION_LOCK_OWNER_CHANGED: "\u4F1A\u8BDD\u9501\u6301\u6709\u8005\u5DF2\u53D8\u5316",
+  SESSION_NOT_FOUND: "\u672A\u627E\u5230\u6307\u5B9A\u4F1A\u8BDD",
+  SESSION_ID_AMBIGUOUS: "\u4F1A\u8BDD\u524D\u7F00\u4E0D\u552F\u4E00",
+  HISTORY_PAGE_INVALID: "\u5386\u53F2\u9875\u53C2\u6570\u65E0\u6548"
+};
+function createSessionError(code, message) {
+  return new KapibalaError(message, {
+    code,
+    safeMessage: SESSION_SAFE_MESSAGES[code],
+    retryPolicy: "after_user_action"
+  });
+}
 var PreDispatchError = class extends KapibalaError {
   constructor(message, options) {
     super(message, {
@@ -1453,19 +1468,23 @@ var SessionLock = class _SessionLock {
       if (error.code !== "EEXIST") throw error;
       const stale = _SessionLock.readOwner(lockPath);
       if (!stale || !_SessionLock.isDead(stale.pid))
-        throw new Error(
+        throw createSessionError(
+          "SESSION_LOCKED",
           `Session locked by a live or unknown owner${stale ? ` (pid=${stale.pid})` : ""}`
         );
       try {
         import_node_fs3.default.mkdirSync(recovery);
       } catch {
-        throw new Error("Session locked: recovery in progress");
+        throw createSessionError(
+          "SESSION_RECOVERY_IN_PROGRESS",
+          "Session locked: recovery in progress"
+        );
       }
       try {
         import_node_fs3.default.writeFileSync(import_node_path2.default.join(recovery, "owner.json"), JSON.stringify(owner), { flag: "wx" });
         const current = _SessionLock.readOwner(lockPath);
         if (current?.nonce !== stale.nonce || current.pid !== stale.pid || !_SessionLock.isDead(current.pid)) {
-          throw new Error("Session locked: owner changed");
+          throw createSessionError("SESSION_LOCK_OWNER_CHANGED", "Session locked: owner changed");
         }
         const quarantine = `${lockPath}.stale-${(0, import_node_crypto4.randomUUID)()}`;
         import_node_fs3.default.renameSync(lockPath, quarantine);
@@ -1485,7 +1504,8 @@ var SessionLock = class _SessionLock {
           }
           if (installError.code === "EEXIST") {
             const winner = _SessionLock.readOwner(lockPath);
-            throw new Error(
+            throw createSessionError(
+              "SESSION_LOCKED",
               `Session locked by a live or unknown owner${winner ? ` (pid=${winner.pid})` : ""}`
             );
           }
@@ -1519,7 +1539,7 @@ var SessionLock = class _SessionLock {
     if (this.released) return;
     const current = _SessionLock.readOwner(this.lockPath);
     if (current?.nonce !== this.owner.nonce || current.pid !== this.owner.pid)
-      throw new Error("Session lock owner changed");
+      throw createSessionError("SESSION_LOCK_OWNER_CHANGED", "Session lock owner changed");
     import_node_fs3.default.unlinkSync(import_node_path2.default.join(this.lockPath, "owner.json"));
     import_node_fs3.default.rmdirSync(this.lockPath);
     this.released = true;
@@ -1550,7 +1570,11 @@ var SessionLock = class _SessionLock {
   /** 无残留或残留进程已死亡时放行；确认存活的回收进行中则明确失败。 */
   static ensureNoLiveRecovery(recovery) {
     _SessionLock.clearAbandonedRecovery(recovery);
-    if (import_node_fs3.default.existsSync(recovery)) throw new Error("Session locked: recovery in progress");
+    if (import_node_fs3.default.existsSync(recovery))
+      throw createSessionError(
+        "SESSION_RECOVERY_IN_PROGRESS",
+        "Session locked: recovery in progress"
+      );
   }
   /** 仅 ESRCH 表示确定死亡；PID 复用或 EPERM 均保持原锁。 */
   static isDead(pid) {
@@ -1777,30 +1801,36 @@ var SessionManager = class {
       throw error;
     }
   }
-  /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+  /**
+   * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+   * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+   */
   async list(page = 1, options) {
-    if (!Number.isSafeInteger(page) || page < 1)
-      throw new Error("History page must be a positive integer");
+    const pageSize = options?.pageSize ?? 20;
+    if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100)
+      throw createSessionError("HISTORY_PAGE_INVALID", "History page must be a positive integer");
     const all = await this.allMetadata();
     const filtered = options?.includeArchived ? all : all.filter((m) => !m.archived);
     return {
-      items: filtered.slice((page - 1) * 20, page * 20),
+      items: filtered.slice((page - 1) * pageSize, page * pageSize),
       total: filtered.length,
       page,
-      pages: Math.max(1, Math.ceil(filtered.length / 20))
+      pages: Math.max(1, Math.ceil(filtered.length / pageSize))
     };
   }
   /** 解析完整 ID 或唯一前缀对应的会话文件与 ID。 */
   resolveSession(id) {
-    if (!id || !/^[a-zA-Z0-9-]+$/.test(id)) throw new Error("Session not found");
+    if (!id || !/^[a-zA-Z0-9-]+$/.test(id))
+      throw createSessionError("SESSION_NOT_FOUND", "Session not found");
     const all = import_node_fs5.default.readdirSync(this.directory).filter((name) => /^\d+_[a-zA-Z0-9-]+\.jsonl$/.test(name)).map((fileName) => ({
       fileName,
       conversationId: fileName.slice(fileName.indexOf("_") + 1, -6)
     }));
     const exact = all.find((m) => m.conversationId === id || m.fileName === id);
     const matches = exact ? [exact] : all.filter((m) => m.conversationId.startsWith(id));
-    if (!matches.length) throw new Error(`Session not found: ${id}`);
-    if (matches.length !== 1) throw new Error(`Ambiguous session prefix: ${id}`);
+    if (!matches.length) throw createSessionError("SESSION_NOT_FOUND", `Session not found: ${id}`);
+    if (matches.length !== 1)
+      throw createSessionError("SESSION_ID_AMBIGUOUS", `Ambiguous session prefix: ${id}`);
     return matches[0];
   }
   /**
@@ -2059,13 +2089,18 @@ var SessionManager = class {
       }));
       const exact = all.find((m) => m.conversationId === idOrFileName);
       const matches = exact ? [exact] : all.filter((m) => m.conversationId.startsWith(idOrFileName));
-      if (!matches.length) throw new Error(`Session not found: ${idOrFileName}`);
-      if (matches.length !== 1) throw new Error(`Ambiguous session prefix: ${idOrFileName}`);
+      if (!matches.length)
+        throw createSessionError("SESSION_NOT_FOUND", `Session not found: ${idOrFileName}`);
+      if (matches.length !== 1)
+        throw createSessionError(
+          "SESSION_ID_AMBIGUOUS",
+          `Ambiguous session prefix: ${idOrFileName}`
+        );
       sourceFileName = matches[0].fileName;
     }
     const sourcePath = import_node_path4.default.join(this.directory, sourceFileName);
     if (!import_node_fs5.default.existsSync(sourcePath)) {
-      throw new Error(`Session not found: ${idOrFileName}`);
+      throw createSessionError("SESSION_NOT_FOUND", `Session not found: ${idOrFileName}`);
     }
     const nativeSource = toNativePhysicalPath(sourcePath);
     const beforeStat = import_node_fs5.default.statSync(nativeSource);
@@ -3434,7 +3469,6 @@ var WorkspaceLeaseCoordinator = class {
     }
   }
 };
-var sharedWorkspaceLeaseCoordinator = new WorkspaceLeaseCoordinator();
 
 // src/context/manager.ts
 var import_node_crypto10 = require("crypto");
@@ -8113,6 +8147,7 @@ var ToolExecutor = class {
         this.signal?.addEventListener("abort", abortFromSession, { once: true });
       }
       const toolCtx = {
+        leaseCoordinator: this.leaseCoordinator,
         workspaceRoot: this.workspaceRoot,
         executionCwd: this.executionCwd,
         sandbox: this.sandbox,
@@ -10835,6 +10870,7 @@ var SessionInbox = class _SessionInbox {
 
 // src/runtime/agent/runtime.ts
 var AgentRuntime = class {
+  runnerContexts = /* @__PURE__ */ new Map();
   tasks = /* @__PURE__ */ new Map();
   controllers = /* @__PURE__ */ new Map();
   timers = /* @__PURE__ */ new Map();
@@ -10918,6 +10954,13 @@ var AgentRuntime = class {
    * - 登记为 preparing 状态并返回 accepted 回执，使父工具事务能立刻闭合。
    */
   async prepareSpawn(context, params) {
+    const coordinator = context.leaseCoordinator;
+    if (!coordinator || typeof coordinator !== "object" || typeof coordinator.isLocked !== "function" || typeof coordinator.getActiveLease !== "function" || typeof coordinator.tryAcquire !== "function" || typeof coordinator.acquire !== "function") {
+      throw new KapibalaError("Spawn requires the parent workspace lease coordinator", {
+        code: "CONFIG_INVALID",
+        safeMessage: "\u5FC5\u987B\u663E\u5F0F\u4F20\u5165\u7236\u4F1A\u8BDD\u5199\u79DF\u7EA6\u534F\u8C03\u5668"
+      });
+    }
     if (this.isClosed) {
       throw new KapibalaError("AgentRuntime is closed", {
         code: "CONFIG_INVALID",
@@ -11060,6 +11103,7 @@ var AgentRuntime = class {
         timeoutMs
       })
     };
+    this.runnerContexts.set(agentId, Object.freeze({ leaseCoordinator: context.leaseCoordinator }));
     this.tasks.set(agentId, taskRecord);
     this.totalActiveCount++;
     this.treeActiveCounts.set(rootTaskId, treeActive + 1);
@@ -11112,6 +11156,7 @@ var AgentRuntime = class {
     const task = this.tasks.get(agentId);
     if (!task) return;
     if (task.status === "preparing") {
+      this.runnerContexts.delete(agentId);
       task.status = "cancelled";
       task.error = "Parent transaction aborted before commit";
       task.finishedAt = Date.now();
@@ -11137,7 +11182,10 @@ var AgentRuntime = class {
     this.timers.set(task.agentId, timer);
     let runError;
     try {
-      const result = await this.runner(task, controller.signal);
+      const context = this.runnerContexts.get(task.agentId);
+      if (!context)
+        throw new KapibalaError("Runner context is unavailable", { code: "CONFIG_INVALID" });
+      const result = await this.runner(task, controller.signal, context);
       if (task.status === "cancelling") {
         task.status = "cancelled";
         return;
@@ -11188,6 +11236,7 @@ var AgentRuntime = class {
       task.error = runError.message;
       await this.cascadeCancelChildren(task.agentId, "Parent task failed");
     } finally {
+      this.runnerContexts.delete(task.agentId);
       this.clearTaskTimer(task.agentId);
       this.controllers.delete(task.agentId);
       if (!isTerminalTaskStatus(task.status)) {
@@ -11263,6 +11312,7 @@ var AgentRuntime = class {
     controller?.abort(new Error(reason));
     await this.cascadeCancelChildren(agentId, reason);
     const inFlight = this.runningPromises.get(agentId);
+    if (!inFlight) this.runnerContexts.delete(agentId);
     if (inFlight) {
       const GRACE_PERIOD_MS = 5e3;
       let timer;
@@ -11371,6 +11421,7 @@ var AgentRuntime = class {
     }
     this.timers.clear();
     this.controllers.clear();
+    this.runnerContexts.clear();
     this.stateListeners.clear();
   }
   /**
@@ -11511,9 +11562,15 @@ function createSpawnAgentTool(runtime) {
       required: ["description", "prompt", "role"]
     },
     async execute(input, ctx) {
+      if (!ctx.leaseCoordinator)
+        throw new KapibalaError("Missing parent lease coordinator", {
+          code: "CONFIG_INVALID",
+          safeMessage: "\u7F3A\u5C11\u7236\u4F1A\u8BDD\u5199\u79DF\u7EA6\u534F\u8C03\u5668"
+        });
       const workspaceRoot = ctx.workspaceRoot ?? ctx.rootDir;
       const executionCwd = ctx.executionCwd ?? workspaceRoot;
       const spawnContext = {
+        leaseCoordinator: ctx.leaseCoordinator,
         rootTaskId: ctx.rootTaskId,
         sessionId: ctx.sessionId ?? "session-default",
         branchId: ctx.branchId ?? "main",
@@ -11876,7 +11933,7 @@ var AgentSession = class {
     this.cwd = resolvedWorkspace.executionCwd;
     this.projectKey = resolvedWorkspace.projectKey;
     this.sandbox = config.sandbox ?? new PathSandbox({ workspaceRoot: this.workspaceRoot });
-    this.leaseCoordinator = config.leaseCoordinator ?? sharedWorkspaceLeaseCoordinator;
+    this.leaseCoordinator = config.leaseCoordinator ?? new WorkspaceLeaseCoordinator();
     this.tools = new ToolRegistry();
     if (config.skills) {
       this.skillRegistry = new SkillRegistry(config.skills);
@@ -13205,6 +13262,7 @@ var AgentSession = class {
   createLogId,
   createMessageId,
   createRunCommandTool,
+  createSessionError,
   createSpawnAgentTool,
   createWaitAgentTool,
   defineTool,
@@ -13260,7 +13318,6 @@ var AgentSession = class {
   sanitizeModelErrorMessage,
   sanitizeSessionTitle,
   scanSkillRoot,
-  sharedWorkspaceLeaseCoordinator,
   skillDigest,
   skillFailure,
   skillPathKey,