@kiturone/kapibala 0.0.7 → 0.0.9

package/dist/index.d.cts

@@ -1151,9 +1151,13 @@ declare class SessionManager {
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
-    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+    /**
+     * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+     * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+     */
     list(page?: number, options?: {
         includeArchived?: boolean;
+        pageSize?: number;
     }): Promise<{
         items: SessionMetadata[];
         total: number;
@@ -3617,6 +3621,9 @@ declare class AgentRuntime {
     private readonly controllers;
     private readonly timers;
     private readonly stateListeners;
+    /** 宿主观察订阅独立于调度等待；关闭宿主订阅不能影响任务收口。 */
+    private readonly taskChangeListeners;
+    private taskChangeNotificationPending;
     private readonly outbox;
     private readonly runningPromises;
     private runner;
@@ -3638,6 +3645,17 @@ declare class AgentRuntime {
      * 获取指定子代理记录快照。
      */
     getTask(agentId: string): AgentTaskRecord | undefined;
+    /**
+     * 订阅任务创建与状态变化；通知只表示快照可能已更新，不提供可变任务对象。
+     * 同一轮微任务内的变化可合并，不保证逐个中间状态；订阅时不主动发送通知，
+     * 宿主应先订阅，再通过 listTasks 按会话和根任务读取独立复制的快照。
+     * 监听器的同步异常与异步拒绝均隔离，不等待监听器，也不触发结果投递或父模型请求。
+     *
+     * @param listener 无参数变化监听器；应只读取展示状态，异步监听器可自行重叠执行。
+     * @returns 幂等取消函数；同一监听器的多次订阅独立取消，运行时关闭时全部释放。
+     * 已关闭的运行时不保留新订阅，返回的取消函数可安全调用。
+     */
+    subscribeTaskChanges(listener: () => void | Promise<void>): () => void;
     /**
      * 判断目标任务是否为指定祖先任务的后代（直接或间接子任务）。
      */
@@ -3703,11 +3721,11 @@ declare class AgentRuntime {
         pending: string[];
     }>;
     /**
-     * 按过滤条件查询子代理任务列表。
+     * 按过滤条件查询子代理任务列表；每条记录深度复制，调用方修改快照不影响运行时。
      */
     listTasks(filter?: ListAgentsFilter): AgentTaskRecord[];
     /**
-     * 关闭 Runtime 并取消所有活动任务。
+     * 关闭 Runtime 并取消所有活动任务；立即释放宿主订阅，再等待任务清理收口。
      */
     close(): Promise<void>;
     /**
@@ -3717,7 +3735,13 @@ declare class AgentRuntime {
     private releaseTaskSlotOnce;
     private releaseActiveSlot;
     private clearTaskTimer;
+    /** 先保留调度等待者的同步唤醒时序，再异步通知宿主读取任务快照。 */
     private notifyStateChange;
+    /**
+     * 合并宿主变化通知，避免宿主回调同步重入任务状态转换；不改变内部等待者的唤醒时序。
+     * 派发前再次检查订阅与关闭状态，取消后的回调不会执行，观察者失败不传播至任务。
+     */
+    private notifyTaskChanges;
     private waitForNextStateChange;
 }
 

package/dist/index.d.ts

@@ -1151,9 +1151,13 @@ declare class SessionManager {
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
-    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+    /**
+     * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+     * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+     */
     list(page?: number, options?: {
         includeArchived?: boolean;
+        pageSize?: number;
     }): Promise<{
         items: SessionMetadata[];
         total: number;
@@ -3617,6 +3621,9 @@ declare class AgentRuntime {
     private readonly controllers;
     private readonly timers;
     private readonly stateListeners;
+    /** 宿主观察订阅独立于调度等待；关闭宿主订阅不能影响任务收口。 */
+    private readonly taskChangeListeners;
+    private taskChangeNotificationPending;
     private readonly outbox;
     private readonly runningPromises;
     private runner;
@@ -3638,6 +3645,17 @@ declare class AgentRuntime {
      * 获取指定子代理记录快照。
      */
     getTask(agentId: string): AgentTaskRecord | undefined;
+    /**
+     * 订阅任务创建与状态变化；通知只表示快照可能已更新，不提供可变任务对象。
+     * 同一轮微任务内的变化可合并，不保证逐个中间状态；订阅时不主动发送通知，
+     * 宿主应先订阅，再通过 listTasks 按会话和根任务读取独立复制的快照。
+     * 监听器的同步异常与异步拒绝均隔离，不等待监听器，也不触发结果投递或父模型请求。
+     *
+     * @param listener 无参数变化监听器；应只读取展示状态，异步监听器可自行重叠执行。
+     * @returns 幂等取消函数；同一监听器的多次订阅独立取消，运行时关闭时全部释放。
+     * 已关闭的运行时不保留新订阅，返回的取消函数可安全调用。
+     */
+    subscribeTaskChanges(listener: () => void | Promise<void>): () => void;
     /**
      * 判断目标任务是否为指定祖先任务的后代（直接或间接子任务）。
      */
@@ -3703,11 +3721,11 @@ declare class AgentRuntime {
         pending: string[];
     }>;
     /**
-     * 按过滤条件查询子代理任务列表。
+     * 按过滤条件查询子代理任务列表；每条记录深度复制，调用方修改快照不影响运行时。
      */
     listTasks(filter?: ListAgentsFilter): AgentTaskRecord[];
     /**
-     * 关闭 Runtime 并取消所有活动任务。
+     * 关闭 Runtime 并取消所有活动任务；立即释放宿主订阅，再等待任务清理收口。
      */
     close(): Promise<void>;
     /**
@@ -3717,7 +3735,13 @@ declare class AgentRuntime {
     private releaseTaskSlotOnce;
     private releaseActiveSlot;
     private clearTaskTimer;
+    /** 先保留调度等待者的同步唤醒时序，再异步通知宿主读取任务快照。 */
     private notifyStateChange;
+    /**
+     * 合并宿主变化通知，避免宿主回调同步重入任务状态转换；不改变内部等待者的唤醒时序。
+     * 派发前再次检查订阅与关闭状态，取消后的回调不会执行，观察者失败不传播至任务。
+     */
+    private notifyTaskChanges;
     private waitForNextStateChange;
 }
 

package/dist/index.js

@@ -1598,17 +1598,21 @@ var SessionManager = class {
       throw error;
     }
   }
-  /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+  /**
+   * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
+   * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+   */
   async list(page = 1, options) {
-    if (!Number.isSafeInteger(page) || page < 1)
+    const pageSize = options?.pageSize ?? 20;
+    if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100)
       throw new Error("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。 */
@@ -10660,6 +10664,9 @@ var AgentRuntime = class {
   controllers = /* @__PURE__ */ new Map();
   timers = /* @__PURE__ */ new Map();
   stateListeners = /* @__PURE__ */ new Set();
+  /** 宿主观察订阅独立于调度等待；关闭宿主订阅不能影响任务收口。 */
+  taskChangeListeners = /* @__PURE__ */ new Set();
+  taskChangeNotificationPending = false;
   outbox;
   runningPromises = /* @__PURE__ */ new Map();
   runner;
@@ -10694,6 +10701,25 @@ var AgentRuntime = class {
     const task = this.tasks.get(agentId);
     return task ? structuredClone(task) : void 0;
   }
+  /**
+   * 订阅任务创建与状态变化；通知只表示快照可能已更新，不提供可变任务对象。
+   * 同一轮微任务内的变化可合并，不保证逐个中间状态；订阅时不主动发送通知，
+   * 宿主应先订阅，再通过 listTasks 按会话和根任务读取独立复制的快照。
+   * 监听器的同步异常与异步拒绝均隔离，不等待监听器，也不触发结果投递或父模型请求。
+   *
+   * @param listener 无参数变化监听器；应只读取展示状态，异步监听器可自行重叠执行。
+   * @returns 幂等取消函数；同一监听器的多次订阅独立取消，运行时关闭时全部释放。
+   * 已关闭的运行时不保留新订阅，返回的取消函数可安全调用。
+   */
+  subscribeTaskChanges(listener) {
+    if (this.isClosed) return () => {
+    };
+    const subscription = () => listener();
+    this.taskChangeListeners.add(subscription);
+    return () => {
+      this.taskChangeListeners.delete(subscription);
+    };
+  }
   /**
    * 判断目标任务是否为指定祖先任务的后代（直接或间接子任务）。
    */
@@ -10869,6 +10895,7 @@ var AgentRuntime = class {
         parentTask.childAgentIds.add(agentId);
       }
     }
+    this.notifyTaskChanges();
     const preferredRole = ROLE_PRESETS[params.role].preferredRole;
     return {
       agentId,
@@ -11125,7 +11152,7 @@ var AgentRuntime = class {
     return { completed, pending };
   }
   /**
-   * 按过滤条件查询子代理任务列表。
+   * 按过滤条件查询子代理任务列表；每条记录深度复制，调用方修改快照不影响运行时。
    */
   listTasks(filter) {
     const results = [];
@@ -11155,10 +11182,11 @@ var AgentRuntime = class {
     return results;
   }
   /**
-   * 关闭 Runtime 并取消所有活动任务。
+   * 关闭 Runtime 并取消所有活动任务；立即释放宿主订阅，再等待任务清理收口。
    */
   async close() {
     this.isClosed = true;
+    this.taskChangeListeners.clear();
     const activeTasks = Array.from(this.tasks.values()).filter((t) => isActiveTaskStatus(t.status));
     await Promise.all(activeTasks.map((t) => this.cancelTask(t.agentId, "Runtime closing")));
     await Promise.all(Array.from(this.runningPromises.values()).map((p) => p.catch(() => {
@@ -11195,6 +11223,7 @@ var AgentRuntime = class {
       this.timers.delete(agentId);
     }
   }
+  /** 先保留调度等待者的同步唤醒时序，再异步通知宿主读取任务快照。 */
   notifyStateChange() {
     for (const listener of this.stateListeners) {
       try {
@@ -11202,6 +11231,28 @@ var AgentRuntime = class {
       } catch {
       }
     }
+    this.notifyTaskChanges();
+  }
+  /**
+   * 合并宿主变化通知，避免宿主回调同步重入任务状态转换；不改变内部等待者的唤醒时序。
+   * 派发前再次检查订阅与关闭状态，取消后的回调不会执行，观察者失败不传播至任务。
+   */
+  notifyTaskChanges() {
+    if (this.isClosed || this.taskChangeNotificationPending || this.taskChangeListeners.size === 0) {
+      return;
+    }
+    this.taskChangeNotificationPending = true;
+    queueMicrotask(() => {
+      this.taskChangeNotificationPending = false;
+      for (const listener of [...this.taskChangeListeners]) {
+        if (!this.taskChangeListeners.has(listener)) continue;
+        try {
+          void Promise.resolve(listener()).catch(() => {
+          });
+        } catch {
+        }
+      }
+    });
   }
   waitForNextStateChange(signal) {
     if (signal.aborted) return Promise.resolve();