@co0ontty/wand 4.76.0-beta.ge98b32f → 4.77.0-beta.g6c4df97

package/dist/agent-dispatch.d.ts

@@ -0,0 +1,46 @@
+import type { ProcessManager } from "./process-manager.js";
+import type { SessionRegistry } from "./session-registry.js";
+import type { WandStorage } from "./storage.js";
+import type { StructuredSessionManager } from "./structured-session-manager.js";
+import type { WandTask, WandTaskAgent } from "./task-types.js";
+import type { SessionSnapshot, WandConfig } from "./types.js";
+export interface AgentDispatchDeps {
+    storage: WandStorage;
+    config: WandConfig;
+    structured: StructuredSessionManager | null;
+    processes: ProcessManager | null;
+}
+export interface AgentDispatchResult {
+    session: SessionSnapshot;
+    cwd: string;
+    workspaceId: string;
+}
+/** 任务卡的执行目录：工作任务的 worktree / 目录 → 所属项目目录 → 全局默认目录。 */
+export declare function resolveTaskDispatchTarget(deps: Pick<AgentDispatchDeps, "storage" | "config">, task: WandTask): {
+    cwd: string;
+    workspaceId: string;
+    workspaceTaskId: string;
+};
+/**
+ * 为任务卡开一个新会话（structured 或 PTY，按 agent.kind），发送首条提示词，并把会话绑定回任务卡。
+ * cwd 取任务的工作任务目录 / 所属项目目录；未指定项目时用全局默认目录。
+ * 结构化会话的整轮 completion 不等待：进度与失败走正常会话事件。
+ */
+export declare function dispatchAgentForTask(deps: AgentDispatchDeps, input: {
+    task: WandTask;
+    agent: WandTaskAgent;
+    prompt: string;
+    automationId: string;
+    systemPrompt?: string;
+}): Promise<AgentDispatchResult>;
+/**
+ * 给已有会话追加一条消息。结构化会话走 sendMessage（不等整轮结束）；
+ * PTY 按输入契约先写文本、再单独写 "\r"，不用 text + "\n" 代替回车。
+ */
+export declare function sendToAgentSession(deps: Pick<AgentDispatchDeps, "structured" | "processes"> & {
+    sessions: SessionRegistry;
+}, sessionId: string, text: string): Promise<void>;
+/** 与 /api/sessions/:id/stop 同样按会话归属分派到对应 manager。 */
+export declare function stopAgentSession(deps: Pick<AgentDispatchDeps, "structured" | "processes"> & {
+    sessions: SessionRegistry;
+}, sessionId: string): void;

package/dist/agent-dispatch.js

@@ -0,0 +1,84 @@
+import { getDefaultModelForProvider } from "./config.js";
+import { providerCliCommand } from "./session-provider.js";
+import { ensureWorkspaceTaskForBoardTask } from "./wand-task-sync.js";
+/** 任务卡的执行目录：工作任务的 worktree / 目录 → 所属项目目录 → 全局默认目录。 */
+export function resolveTaskDispatchTarget(deps, task) {
+    const workspace = task.workspaceId ? deps.storage.getWorkspace(task.workspaceId) : null;
+    if (task.workspaceId && !workspace)
+        throw new Error("任务所属项目已被删除，请重新指定。");
+    const group = ensureWorkspaceTaskForBoardTask(deps.storage, task);
+    const cwd = group.worktree?.path || group.cwd || workspace?.cwd || deps.config.defaultCwd;
+    return { cwd, workspaceId: group.workspaceId, workspaceTaskId: group.id };
+}
+/**
+ * 为任务卡开一个新会话（structured 或 PTY，按 agent.kind），发送首条提示词，并把会话绑定回任务卡。
+ * cwd 取任务的工作任务目录 / 所属项目目录；未指定项目时用全局默认目录。
+ * 结构化会话的整轮 completion 不等待：进度与失败走正常会话事件。
+ */
+export async function dispatchAgentForTask(deps, input) {
+    const { storage, config, structured, processes } = deps;
+    const { agent } = input;
+    const systemPrompt = input.systemPrompt?.trim() || undefined;
+    if (agent.kind === "structured" && !structured)
+        throw new Error("当前服务未启用结构化会话，无法派发 Agent。");
+    if (agent.kind === "pty" && !processes)
+        throw new Error("当前服务未启用终端会话，无法派发 Agent。");
+    const group = resolveTaskDispatchTarget(deps, input.task);
+    const cwd = group.cwd;
+    const provider = agent.provider;
+    const model = agent.model === "default" ? "" : agent.model;
+    const resolvedModel = model || getDefaultModelForProvider(config, provider) || undefined;
+    const session = agent.kind === "pty"
+        ? await processes.start(providerCliCommand(provider), cwd, agent.mode, input.prompt, {
+            provider,
+            model: resolvedModel,
+            thinkingEffort: agent.thinkingEffort,
+            sessionSource: "automation",
+            automationId: input.automationId,
+            systemPrompt,
+            workspaceId: group.workspaceId,
+            workspaceTaskId: group.workspaceTaskId,
+        })
+        : structured.createSession({
+            cwd,
+            mode: agent.mode,
+            provider,
+            model: resolvedModel,
+            thinkingEffort: agent.thinkingEffort,
+            worktreeEnabled: false,
+            sessionSource: "automation",
+            automationId: input.automationId,
+            systemPrompt,
+            workspaceId: group.workspaceId,
+            workspaceTaskId: group.workspaceTaskId,
+        });
+    storage.bindWandTaskSession(input.task.id, session.id);
+    if (agent.kind !== "pty") {
+        const completion = structured.sendMessage(session.id, input.prompt);
+        completion.catch((error) => console.error(`[AgentDispatch] ${input.automationId} failed:`, error));
+    }
+    return { session, cwd, workspaceId: group.workspaceId };
+}
+/**
+ * 给已有会话追加一条消息。结构化会话走 sendMessage（不等整轮结束）；
+ * PTY 按输入契约先写文本、再单独写 "\r"，不用 text + "\n" 代替回车。
+ */
+export async function sendToAgentSession(deps, sessionId, text) {
+    if (deps.sessions.ownerOf(sessionId) === "structured") {
+        const completion = deps.structured.sendMessage(sessionId, text);
+        completion.catch((error) => console.error(`[AgentDispatch] message to ${sessionId} failed:`, error));
+        return;
+    }
+    if (!deps.processes)
+        throw new Error("当前服务未启用终端会话。");
+    await deps.processes.sendInputConfirmed(sessionId, text, "terminal");
+    await deps.processes.sendInputConfirmed(sessionId, "\r", "terminal", "enter_text");
+}
+/** 与 /api/sessions/:id/stop 同样按会话归属分派到对应 manager。 */
+export function stopAgentSession(deps, sessionId) {
+    if (deps.sessions.ownerOf(sessionId) === "structured") {
+        deps.structured?.stop(sessionId);
+        return;
+    }
+    deps.processes?.stop(sessionId);
+}

package/dist/ai-team-availability.d.ts

@@ -0,0 +1,69 @@
+import type { CandidateFailureKind } from "./ai-team-types.js";
+import type { WandTaskAgent, WandTaskAgentKind } from "./task-types.js";
+/**
+ * v2 启动失败分类与候选降级判定（设计文档 §3.4）。
+ * 本模块只放纯函数：不接 runner、不读全局状态、不碰时钟与文件系统；
+ * 时间窗与快照一律由调用方算好传入。
+ */
+/** 类别真源在 ai-team-types.ts（StepDispatchInfo 引用），这里按文档口径对外再导出一次。 */
+export type { CandidateFailureKind } from "./ai-team-types.js";
+/**
+ * startup-timeout 判定的启动窗口（§3.4、§11-Q7）：固定常量，刻意不开 config 口子。
+ * 窗口内「会话已没 + 从没出过 assistant 回复」才视为启动失败可降级；窗口外按 runtime-failure 对待。
+ */
+export declare const AI_TEAM_STARTUP_WINDOW_MS = 45000;
+export declare function isSessionGoneStatus(status: string): boolean;
+/**
+ * 按错误文案分类。只认 spawn-missing 与 host-disabled 两类稳定信号；
+ * 无法归类的启动期错误一律 runtime-failure（不降级，宁失败交回 Leader）。
+ * model-unknown 只由事前快照比对产生（isModelUnknownBeforeDispatch），事后一律不判。
+ */
+export declare function classifyCandidateFailure(errorMessage: string | null | undefined): CandidateFailureKind;
+export interface StartupFailureProbe {
+    /** 会话快照状态（SessionSnapshot.status 字面量）。 */
+    status: string;
+    /** snapshot.messages 是否出现过 assistant 回复（有任何输出即算）。 */
+    hasAssistantReply: boolean;
+    /** now - step.startedAt（毫秒）；由调用方计算。 */
+    elapsedMs: number;
+    /** structuredState.lastError 等错误文案；没有则留空。 */
+    errorMessage?: string | null;
+}
+/**
+ * 异步启动失败的组合判定：先按文案（ENOENT 优先于窗口），再看 startup window。
+ * 结论只会是 spawn-missing / host-disabled / startup-timeout / runtime-failure。
+ */
+export declare function classifyStartupFailure(probe: StartupFailureProbe): CandidateFailureKind;
+export interface WorkFailureInput {
+    /** 只有 work 步骤参与降级；leader 步骤走既有格式重试/waiting_user 路径。 */
+    stepKind: "leader" | "work";
+    /** PTY 候选一律不异步分类、不降级（§3.4 修正 B4）。 */
+    agentKind: WandTaskAgentKind;
+    /** stepOutcome 给出的会话失败信号。 */
+    sessionError: boolean;
+    /** 报告文件已有产出 → 会话启动是成功的，不降级。 */
+    hasReportOutput: boolean;
+    /** classifyStartupFailure / classifyCandidateFailure 的结果。 */
+    failure: CandidateFailureKind;
+    /** 本步实际使用的候选下标。 */
+    usedCandidate: number;
+    /** 该成员的候选总数（memberAgents(member).length）。 */
+    candidateCount: number;
+    /** 下一候选是否已在 run 级黑名单里。 */
+    nextCandidateBlocked: boolean;
+}
+/**
+ * 降级判定核（§3.4 触发点 2）：全部条件满足才允许「降级开新步」。
+ * host-disabled / model-unknown / runtime-failure / format-error / user-stop 一律 false。
+ */
+export declare function isDegradableWorkFailure(input: WorkFailureInput): boolean;
+/** 事前比对用的最小快照视图：一列模型 id（字符串或带 id 字段的条目）。 */
+export type ModelCatalogView = ReadonlyArray<string | {
+    id?: unknown;
+} | null | undefined> | null | undefined;
+/**
+ * model-unknown 的事前检查（§3.4 修正 B3），方向是「拿不准就放行」：
+ * 仅当快照存在、清单非空、model 不是 "default" 且精确匹配失败时才返回 true。
+ * 快照缺失 / 空清单（冷启动）、"default"、命中清单 → false，照常派发交给事后降级。
+ */
+export declare function isModelUnknownBeforeDispatch(agent: WandTaskAgent, snapshot: ModelCatalogView): boolean;

package/dist/ai-team-availability.js

@@ -0,0 +1,100 @@
+/**
+ * startup-timeout 判定的启动窗口（§3.4、§11-Q7）：固定常量，刻意不开 config 口子。
+ * 窗口内「会话已没 + 从没出过 assistant 回复」才视为启动失败可降级；窗口外按 runtime-failure 对待。
+ */
+export const AI_TEAM_STARTUP_WINDOW_MS = 45_000;
+/** 与 runner isSessionGone 同语义的状态清单（本地镜像，保持本模块零依赖 runner）。 */
+const SESSION_GONE_STATUSES = ["exited", "failed", "stopped"];
+export function isSessionGoneStatus(status) {
+    return SESSION_GONE_STATUSES.includes(status);
+}
+/**
+ * CLI 缺失类文案（spawn-missing）。来源样例（只引用不改）：
+ *   - structured-session-manager.ts: codex exec ENOENT →「PATH 中找不到 … 可执行文件」
+ *   - git-quick-commit.ts: error.code === "ENOENT" →「未找到 <cmd> CLI。」
+ *   - claude-sdk-runner.ts:「Claude Code native binary not found」/ ENOENT →「未找到 claude CLI。」
+ */
+const SPAWN_MISSING_PATTERNS = [
+    /\bENOENT\b/i,
+    /No such file or directory/i,
+    /command not found/i,
+    /native binary not found/i,
+    /找不到[^\n]{0,24}可执行文件/,
+    /未找到[^\n]{0,24}CLI/,
+    /(cli|binary|executable|可执行文件)[^\n]{0,24}not found/i,
+    /not found[^\n]{0,24}(cli|binary|executable)/i,
+];
+/** host-disabled 文案源：agent-dispatch.ts 的「当前服务未启用结构化/终端会话，无法派发 Agent。」 */
+const HOST_DISABLED_PATTERNS = [/未启用[^\n]{0,8}会话/];
+/**
+ * 按错误文案分类。只认 spawn-missing 与 host-disabled 两类稳定信号；
+ * 无法归类的启动期错误一律 runtime-failure（不降级，宁失败交回 Leader）。
+ * model-unknown 只由事前快照比对产生（isModelUnknownBeforeDispatch），事后一律不判。
+ */
+export function classifyCandidateFailure(errorMessage) {
+    const text = (errorMessage ?? "").trim();
+    if (!text)
+        return "runtime-failure";
+    if (HOST_DISABLED_PATTERNS.some((pattern) => pattern.test(text)))
+        return "host-disabled";
+    if (SPAWN_MISSING_PATTERNS.some((pattern) => pattern.test(text)))
+        return "spawn-missing";
+    return "runtime-failure";
+}
+/**
+ * 异步启动失败的组合判定：先按文案（ENOENT 优先于窗口），再看 startup window。
+ * 结论只会是 spawn-missing / host-disabled / startup-timeout / runtime-failure。
+ */
+export function classifyStartupFailure(probe) {
+    const byText = classifyCandidateFailure(probe.errorMessage);
+    if (byText !== "runtime-failure")
+        return byText;
+    if (isSessionGoneStatus(probe.status)
+        && !probe.hasAssistantReply
+        && probe.elapsedMs < AI_TEAM_STARTUP_WINDOW_MS) {
+        return "startup-timeout";
+    }
+    return "runtime-failure";
+}
+/**
+ * 降级判定核（§3.4 触发点 2）：全部条件满足才允许「降级开新步」。
+ * host-disabled / model-unknown / runtime-failure / format-error / user-stop 一律 false。
+ */
+export function isDegradableWorkFailure(input) {
+    if (input.stepKind !== "work")
+        return false;
+    if (input.agentKind !== "structured")
+        return false;
+    if (!input.sessionError)
+        return false;
+    if (input.hasReportOutput)
+        return false;
+    if (input.failure !== "spawn-missing" && input.failure !== "startup-timeout")
+        return false;
+    if (input.usedCandidate >= input.candidateCount - 1)
+        return false;
+    if (input.nextCandidateBlocked)
+        return false;
+    return true;
+}
+/**
+ * model-unknown 的事前检查（§3.4 修正 B3），方向是「拿不准就放行」：
+ * 仅当快照存在、清单非空、model 不是 "default" 且精确匹配失败时才返回 true。
+ * 快照缺失 / 空清单（冷启动）、"default"、命中清单 → false，照常派发交给事后降级。
+ */
+export function isModelUnknownBeforeDispatch(agent, snapshot) {
+    if (!Array.isArray(snapshot) || snapshot.length === 0)
+        return false;
+    if (agent.model === "default")
+        return false;
+    const ids = new Set();
+    for (const entry of snapshot) {
+        if (typeof entry === "string")
+            ids.add(entry);
+        else if (entry && typeof entry === "object" && typeof entry.id === "string")
+            ids.add(entry.id);
+    }
+    if (ids.size === 0)
+        return false;
+    return !ids.has(agent.model);
+}

package/dist/ai-team-prompts.d.ts

@@ -0,0 +1,113 @@
+import { type AiTeam, type AiTeamMember, type AiTeamRun, type AiTeamRunStatus, type AiTeamStep } from "./ai-team-types.js";
+import type { ConversationTurn } from "./types.js";
+export declare const AI_TEAM_REPORT_DIR = ".wand-team";
+export declare const AI_TEAM_MAX_ASSIGN_STEPS = 5;
+export interface AiTeamAssignedStep {
+    memberId: string;
+    title: string;
+    instructions: string;
+    /** 依赖本次 steps 里的哪些项（0 起下标）；空数组 = 立刻开始。 */
+    after: number[];
+}
+export type AiTeamLeaderDecision = {
+    action: "assign";
+    message: string;
+    steps: AiTeamAssignedStep[];
+} | {
+    action: "ask";
+    message: string;
+} | {
+    action: "finish";
+    message: string;
+};
+/**
+ * 团队这一轮要做的事。
+ * 指派框 / 群聊里刚输入的文字就是本轮任务，不再把任务卡上的旧描述静默拼进去。
+ * 没有单独输入时（创建任务后立刻交给团队）才用标题 + 描述。
+ */
+export declare function buildAiTeamObjective(task: {
+    title: string;
+    description: string;
+}, note?: string): string;
+export declare function leaderOf(team: AiTeam): AiTeamMember;
+export declare function workersOf(team: AiTeam): AiTeamMember[];
+/** 每步的约定报告文件（相对 cwd）。所有 CLI 都能写文件，因此是通用的交接方式。 */
+export declare function aiTeamReportPath(runId: string, seq: number, kind: "leader" | "work", memberId: string): string;
+/**
+ * 交接文件（相对 cwd）：上一批步骤的报告全文汇总，服务端在派发前写好，
+ * 下一步的提示词只给这条路径，让执行者自己去读，不再把报告贴进提示词。
+ */
+export declare function aiTeamHandoffPath(runId: string, seq: number, kind: "leader" | "work"): string;
+/**
+ * 群聊续跑的上下文文件（相对 cwd）：用户在同一个群聊里接着说话时，服务端把之前几轮的
+ * 步骤摘要与群聊原文写在这里，新一轮的负责人与成员先读它再动手，不从零重来。
+ * 文件名由运行 id 决定，所以在库里不用额外记一列；「文件在不在」就是「是不是续跑」。
+ */
+export declare function aiTeamChatHistoryPath(runId: string): string;
+/** 一条待交接的上游步骤：提示词里只给元信息，正文进交接文件。 */
+export interface AiTeamHandoffStep {
+    seq: number;
+    title: string;
+    memberName: string;
+    status: AiTeamStep["status"];
+    reportPath: string;
+}
+/** 交接文件正文用的条目：元信息 + 报告全文。 */
+export interface AiTeamHandoffEntry extends AiTeamHandoffStep {
+    report: string;
+}
+/** 交接文件正文（Markdown）。纯函数，便于单测。 */
+export declare function renderHandoffFile(entries: AiTeamHandoffEntry[], generatedAt: string): string;
+/** 成员步骤的上游交接（依赖步骤）；没有依赖时为 null。 */
+export interface AiTeamUpstream {
+    handoffPath: string;
+    steps: AiTeamHandoffStep[];
+}
+/** 群聊上下文文件里的一段「之前几轮运行」摘要：只列步骤与状态，报告正文在群聊原文里。 */
+export interface AiTeamHistoryRun {
+    status: AiTeamRunStatus;
+    steps: Array<{
+        seq: number;
+        memberName: string;
+        title: string;
+        status: AiTeamStep["status"];
+    }>;
+}
+/**
+ * 群聊续跑的交接文件（Markdown，纯函数便于单测）：先列之前几轮的步骤摘要（含上一轮没做完的），
+ * 再给群聊原文；原文只留最近的这一段，超预算时从最早处丢并注明。
+ */
+export declare function renderChatHistoryFile(input: {
+    runs: AiTeamHistoryRun[];
+    turns: ConversationTurn[];
+    generatedAt: string;
+    maxBytes?: number;
+}): string;
+/**
+ * 一轮提示词：`system` 交给 CLI 的系统提示通道（角色、规则、回复格式），`message` 是这一轮的
+ * 用户消息（目标、指派、报告路径）。provider 支持系统提示时必须走 `system`，不要把规则塞进消息里。
+ */
+export interface AiTeamPrompt {
+    system: string;
+    message: string;
+}
+/** `chatHistoryPath` 有值时说明这一轮是同一个群聊的续跑（见 `aiTeamChatHistoryPath`）。 */
+export declare function buildLeaderKickoffPrompt(run: AiTeamRun, reportPath: string, fresh: boolean, chatHistoryPath?: string | null): AiTeamPrompt;
+export interface AiTeamFinishedStepSummary {
+    step: AiTeamStep;
+    memberName: string;
+}
+export declare function buildLeaderFollowupPrompt(run: AiTeamRun, finished: AiTeamFinishedStepSummary[], reportPath: string, userNote: string | undefined, fresh: boolean, handoffPath?: string | null, chatHistoryPath?: string | null): AiTeamPrompt;
+export declare function buildLeaderFormatRetryPrompt(run: AiTeamRun, error: string, reportPath: string, fresh: boolean, chatHistoryPath?: string | null): AiTeamPrompt;
+/**
+ * fresh=false 时成员会话已有上下文，省掉目标段落。`upstream` 有值时只给交接文件路径与
+ * 各步报告文件，不在提示词里复述上游报告正文（上一个成员的信息走文件交接）。
+ */
+export declare function buildMemberPrompt(run: AiTeamRun, step: AiTeamStep, member: AiTeamMember, fresh: boolean, upstream?: AiTeamUpstream | null, chatHistoryPath?: string | null): AiTeamPrompt;
+export declare function parseLeaderDecision(text: string, team: AiTeam): {
+    ok: true;
+    decision: AiTeamLeaderDecision;
+} | {
+    ok: false;
+    error: string;
+};