@steerable/agent-shell 0.6.15

package/dist/local-backend/task-service.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 4.6a Task（跨 turn 后台任务）+ 4.6c Task×Worktree 组合。
+ *
+ * 核心难点——跨 turn 生命周期：sidecar 的父 turn 结束时会在 finally 里
+ * `orchestration.shutdown()` / `subagent_executor.shutdown()`（池寿命 =
+ * 父 turn），所以任务**不能**挂在父 turn 的 AgentPool 里。本模块的做法是
+ * 让宿主为每个任务起一条**独立的 sidecar chat 流**（复用
+ * `streamCoreLoopTurn`，与父 turn 同一 supervisor 进程但 streamId /
+ * durable record / CoreLoop / AgentPool 全部独立）：
+ *
+ *   - 父 turn 的 `task_run` 工具调用只落任务表 + 点火，立即返回
+ *     `{taskId, status: "running"}`——任务生命周期由宿主任务表管理；
+ *   - 父 turn 流 teardown 只 shutdown 它自己的池，任务流照常跑到终态；
+ *   - 任务流以 `task:<taskId>` 为 chatId/recordId： durable record 独立
+ *     （trace.fetch 可查），也不与父 chat 的 activeCoreLoopStreams /
+ *     turn_active 标记冲突。
+ *
+ * 任务的工具调用照常走反向通道回宿主执行；toolContext 里带
+ * `chatId: <父 chat>`（项目围栏照旧解析）与可选 `workspaceRoot:
+ * <worktree 路径>`（4.6b：reverse-tools 优先采用，把 cwd/文件围栏钉到
+ * 隔离工作区而不是主检出）。
+ *
+ * 深度约束与 delegate_subagent 一致：depth-1——任务回合的工具列表里
+ * 没有 `task_run`，任务不能再派生任务（任务里仍可 delegate_subagent）。
+ */
+import { getSidecarSupervisor } from '../llm/index.js';
+import type { TaskRecord } from '../storage/index.js';
+import type { ToolRouter } from '../tool-router.js';
+import { streamCoreLoopTurn } from './coreloop-stream.js';
+import type { WorktreeService } from './worktree-service.js';
+import { type PersistedTurnBlock } from './turn-timeline.js';
+/** 任务表的最小读写面（生产 = localStore；测试注入内存实现）。 */
+export interface TaskStore {
+    createTask(input: {
+        chatId: string;
+        task: string;
+        worktreePath?: string | null;
+        worktreeBranch?: string | null;
+        recordId?: string | null;
+        dependsOn?: string[] | null;
+        initialStatus?: 'blocked' | 'running';
+    }): TaskRecord;
+    getTask(taskId: string): TaskRecord | null;
+    listTasks(chatId?: string, limit?: number): TaskRecord[];
+    updateTask(taskId: string, updates: Partial<Pick<TaskRecord, 'status' | 'answer' | 'error' | 'worktreeState' | 'traceId' | 'recordId'>>): TaskRecord | null;
+    /** 回写推理时间线；缺省实现可为空（测试假 store 内存覆盖）。 */
+    saveTaskProcess?(taskId: string, processJson: string): void;
+}
+export interface TaskServiceDeps {
+    store: TaskStore;
+    toolRouter: ToolRouter;
+    worktreeService: WorktreeService;
+    /** chatId → 绑定项目（无项目对话返回 null）。与 router.resolveChatProject 同源。 */
+    resolveChatProject: (chatId: string) => {
+        name: string;
+        folderPath: string;
+    } | null;
+    /** 任务终态 / 推理过程广播（renderer 任务面板与右侧过程栏）。 */
+    broadcast?: (eventName: 'task-updated' | 'task-process', payload: Record<string, unknown>) => void;
+    /** 测试缝：替换真实流驱动（默认 streamCoreLoopTurn）。 */
+    runStream?: typeof streamCoreLoopTurn;
+    /** 测试缝：sidecar 句柄解析（默认 getSidecarSupervisor）。 */
+    getSupervisor?: typeof getSidecarSupervisor;
+    /** 测试缝：历史回放（默认读 sidecar sqlite）。 */
+    readHistory?: (recordId: string) => unknown[];
+}
+export declare class TaskService {
+    private readonly deps;
+    private readonly running;
+    constructor(deps: TaskServiceDeps);
+    /**
+     * task_run 工具的实现：落任务表 + 点火独立流，立即返回。
+     * 任何同步可知的失败（无 sidecar、worktree 建不起来）都抛给工具层，
+     * 让模型本轮就看到错误而不是一个永远 running 的幽灵任务。
+     *
+     * 编排（dependsOn）：依赖必须指向本 chat 已存在的任务——依赖图因此
+     * 天然无环（后来的任务不可能被先建的任务依赖）。依赖全部 completed
+     * 立即点火；有 running/blocked 依赖则落 blocked，由依赖终态时的
+     * maybeUnblock 调度点火；任一依赖已 failed 直接 fail fast。
+     */
+    runTask(input: {
+        chatId: string;
+        task: string;
+        worktree?: boolean;
+        worktreeName?: string;
+        dependsOn?: string[];
+    }): Promise<{
+        taskId: string;
+        status: 'blocked' | 'running';
+        worktreePath?: string;
+    }>;
+    /**
+     * task_send 工具的实现：向运行中的任务流 steer 一条消息（agent 间
+     * 消息）。任务已终态时流已关闭，只能让模型重跑——与框架 pool 的
+     * resume 不同，任务流是 fire-and-forget 整流。
+     */
+    sendMessage(chatId: string, taskId: string, message: string): Promise<Record<string, unknown>>;
+    /**
+     * 调度器：一个任务到终态后，扫描同 chat 的 blocked 任务——依赖全部
+     * completed 的点火；任一依赖 failed 的标 failed（fail fast，错误
+     * 指明是哪个依赖挂了）。
+     */
+    private maybeUnblock;
+    /** 点火：独立 sidecar 流跑任务，终态回写任务表。fire-and-forget。 */
+    private ignite;
+    private readonly processFlush;
+    /**
+     * 把时间线推给过程栏并回写任务表。整条时间线每次都要重新序列化，
+     * 所以文本/推理增量按 250ms 合并（否则每个 token 都发一份全量，长任务
+     * 的流量是 O(n²)）；工具事件与终态立即发，卡片状态不能延迟。
+     */
+    private publishProcess;
+    private cancelProcessFlush;
+    private executeTask;
+    /** task_status 工具：单任务或本 chat 全部任务的快照。 */
+    status(chatId: string, taskId?: string): Record<string, unknown>;
+    /** task_result 工具：取终态任务的完整结果。 */
+    result(chatId: string, taskId: string): Record<string, unknown>;
+    /** 喂给模型的任务视图（完整字段，answer 截断防爆上下文）。 */
+    private toModelView;
+    /**
+     * 右侧过程栏：当前推理时间线。running 且进程内有流 = live；
+     * 表上 running 但本进程没流 = 上次崩溃残留（stale）。
+     */
+    getProcess(taskId: string): {
+        task: TaskRecord;
+        timeline: PersistedTurnBlock[];
+        live: boolean;
+        stale: boolean;
+    } | null;
+    /** 合并任务 worktree 到主仓（UI「合并到主仓」按钮的路由实现）。 */
+    mergeTaskWorktree(taskId: string): Promise<TaskRecord>;
+    /** 丢弃任务 worktree（UI「丢弃」按钮的路由实现）。 */
+    discardTaskWorktree(taskId: string): Promise<TaskRecord>;
+}