@qlingzzy/qling 1.0.0 → 1.1.0

package/dist/agent/main-loop.js

@@ -0,0 +1,279 @@
+// ============================================================
+// Agent 主循环：外层 transport 恢复 + 内层 turn 迭代（从 AgentLoop 抽出）
+// ============================================================
+import { resolveRoundTokenUsage, } from "../token-usage.js";
+import { classifyFailure } from "../execution/failure-classifier.js";
+import { executePreparedTools, prepareToolCalls, } from "./tool-orchestrator.js";
+import { runWriteToolVerification } from "../execution/verification-loop.js";
+import { findLastUserMessageContent } from "./system-prompt.js";
+export function applyProviderUsage(counters, usage) {
+    const tokenUsage = resolveRoundTokenUsage(usage);
+    if (tokenUsage.source !== "provider")
+        return counters;
+    return {
+        sessionTokens: counters.sessionTokens + tokenUsage.tokens,
+        sessionPromptTokens: counters.sessionPromptTokens + tokenUsage.promptTokens,
+        sessionCompletionTokens: counters.sessionCompletionTokens + tokenUsage.completionTokens,
+        tokenUsageSource: "provider",
+    };
+}
+export function logTurnTelemetry(metrics, totals) {
+    const toolCallTotal = totals.toolCallTotal + metrics.toolCalls;
+    const toolFailureTotal = totals.toolFailureTotal + metrics.toolFailures;
+    const turnFailureRate = metrics.toolCalls === 0 ? 0 : Math.round((metrics.toolFailures / metrics.toolCalls) * 100);
+    const totalFailureRate = toolCallTotal === 0 ? 0 : Math.round((toolFailureTotal / toolCallTotal) * 100);
+    if (totals.format === "json") {
+        console.error(JSON.stringify({
+            type: "observability",
+            turn: metrics.turn,
+            toolCalls: metrics.toolCalls,
+            turnFailureRate,
+            totalFailureRate,
+            compactions: totals.compactionCount,
+            retries: totals.retryCountTotal,
+        }));
+    }
+    else {
+        console.error("📊 [Obs] turn=" +
+            metrics.turn +
+            " tools=" +
+            metrics.toolCalls +
+            " turnFailRate=" +
+            turnFailureRate +
+            "% totalFailRate=" +
+            totalFailureRate +
+            "% compactions=" +
+            totals.compactionCount +
+            " retries=" +
+            totals.retryCountTotal);
+    }
+    return { toolCallTotal, toolFailureTotal };
+}
+function toolMessageIsError(messages, toolCallId) {
+    for (const m of messages) {
+        if (m.tool_call_id !== toolCallId || m.role !== "tool")
+            continue;
+        try {
+            return Boolean(JSON.parse(m.content).is_error);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+export function distillSuccessfulBashPractices(preparedCalls, messages, memoryStore) {
+    const hasError = preparedCalls.some((p) => Boolean(p.immediateResult?.is_error) ||
+        (p.call.id ? toolMessageIsError(messages, p.call.id) : false));
+    if (hasError)
+        return;
+    const successfulCmds = preparedCalls
+        .filter((p) => p.call.name === "bash")
+        .map((p) => {
+        const args = p.call.arguments;
+        return args.cmd || args.command;
+    })
+        .filter((cmd) => Boolean(cmd));
+    if (successfulCmds.length === 0)
+        return;
+    const lastUserMsg = findLastUserMessageContent(messages);
+    const files = preparedCalls
+        .map((p) => {
+        const args = p.call.arguments;
+        return args.path || args.file;
+    })
+        .filter((f) => Boolean(f));
+    memoryStore.addPractice(lastUserMsg.slice(0, 100), successfulCmds, files);
+    console.error(`✨ [认知] 已将 ${successfulCmds.length} 条成功指令蒸馏为最佳实践`);
+}
+/**
+ * Inner maxIterations loop: compact → prompt → chat → tools → verify.
+ * Mutates host.messages / counters / turnCount in place.
+ */
+export async function runInnerIterationLoop(host) {
+    const toolSignatureCounts = new Map();
+    for (let i = 0; i < host.maxIterations; i++) {
+        host.turnCount++;
+        const runId = host.activeRunId ?? `run_untracked_${host.turnCount}`;
+        const attemptId = `attempt_${runId}_${host.turnCount}`;
+        host.executionEventBus.startAttempt({ runId, sessionId: host.sessionId, attemptId });
+        const lastUserMsg = findLastUserMessageContent(host.messages);
+        if (host.compactor.needsCompaction(host.messages)) {
+            console.error("\n📦 上下文压缩中...（" + host.messages.length + " 条消息）");
+            const compacted = await host.compactor.compact(host.messages);
+            host.messages.splice(0, host.messages.length, ...compacted);
+            host.compactionCount++;
+            console.error("📦 压缩完成 → " + host.messages.length + " 条消息\n");
+        }
+        const conflicts = host.compactor.scanConflicts(host.messages);
+        if (conflicts.length > 0) {
+            console.error("⚠️ 检测到 " + conflicts.length + " 处指令冲突");
+        }
+        const poison = host.compactor.scanPoison(host.messages);
+        if (poison.length > 0) {
+            console.error("🚨 检测到 " + poison.length + " 处可能的提示注入");
+        }
+        const systemPrompt = await host.buildSystemPrompt();
+        if (process.env.QLING_FEATURES_WORKFLOW_RUNTIME === "true") {
+            await host.workflowRuntime.updateContext(host.messages);
+        }
+        const { content, tool_calls, usage } = await host.chat(systemPrompt);
+        host.counters = applyProviderUsage(host.counters, usage);
+        host.messages.push({ role: "assistant", content, tool_calls });
+        host.emit("thinking", content || "正在思考...");
+        if (!tool_calls || tool_calls.length === 0) {
+            host.knowledgeAdapter.onAssistantMessage(content);
+            await host.checkAutoDream();
+            await host.knowledgeAdapter.onTurnEnd(host.turnCount);
+            const totals = logTurnTelemetry({ turn: host.turnCount, toolCalls: 0, toolFailures: 0 }, {
+                toolCallTotal: host.toolCallTotal,
+                toolFailureTotal: host.toolFailureTotal,
+                compactionCount: host.compactionCount,
+                retryCountTotal: host.retryCountTotal,
+                format: host.loggingFormat,
+            });
+            host.toolCallTotal = totals.toolCallTotal;
+            host.toolFailureTotal = totals.toolFailureTotal;
+            host.executionEventBus.completeAttempt(runId, "succeeded");
+            return content;
+        }
+        console.error("\n🔧 执行 " + tool_calls.length + " 个工具...\n");
+        const preparedCalls = prepareToolCalls(tool_calls, {
+            parseRetries: host.parseRetries,
+            toolRepeatLimit: host.toolRepeatLimit,
+            signatureCounts: toolSignatureCounts,
+        });
+        const { turnToolCalls, turnToolFailures } = await executePreparedTools({
+            pipeline: host.pipeline,
+            tools: host.tools,
+            guardConfig: host.guardConfig,
+            channel: host.channel,
+            approvalGate: host.approvalGate,
+            knowledgeAdapter: host.knowledgeAdapter,
+            memoryStore: host.memoryStore,
+            workspaceDir: host.workspaceDir,
+            workflowRuntime: host.workflowRuntime,
+            executionEventBus: host.executionEventBus,
+            emit: host.emit,
+            reflectiveThink: host.reflectiveThink,
+        }, {
+            preparedCalls,
+            messages: host.messages,
+            runId,
+            attemptId,
+        });
+        const verifyOutcome = await runWriteToolVerification(preparedCalls, {
+            verificationCommand: host.verificationCommand,
+            runCommand: host.runVerificationCommand,
+            recoveryController: host.recoveryController,
+            executionEventBus: host.executionEventBus,
+            emit: host.emit,
+            getRecoveryState: host.getRecoveryState,
+            verifier: host.verifier,
+            messages: host.messages,
+            runId,
+        });
+        if (verifyOutcome.kind === "pause") {
+            return verifyOutcome.text;
+        }
+        if (verifyOutcome.kind === "recover") {
+            host.messages.push({ role: "user", content: verifyOutcome.userMessage });
+            host.emit("repair", verifyOutcome.failureMessage, verifyOutcome.strategy, verifyOutcome.strategyAttempts);
+            host.executionEventBus.completeAttempt(runId, "recovering");
+            continue;
+        }
+        await host.checkAutoDream();
+        if (host.turnCount > 0) {
+            distillSuccessfulBashPractices(preparedCalls, host.messages, host.memoryStore);
+        }
+        host.memoryStore.addConversationTurn("user", lastUserMsg);
+        host.memoryStore.addConversationTurn("assistant", content);
+        host.knowledgeAdapter.onAssistantMessage(content);
+        await host.knowledgeAdapter.onTurnEnd(host.turnCount);
+        const totals = logTurnTelemetry({ turn: host.turnCount, toolCalls: turnToolCalls, toolFailures: turnToolFailures }, {
+            toolCallTotal: host.toolCallTotal,
+            toolFailureTotal: host.toolFailureTotal,
+            compactionCount: host.compactionCount,
+            retryCountTotal: host.retryCountTotal,
+            format: host.loggingFormat,
+        });
+        host.toolCallTotal = totals.toolCallTotal;
+        host.toolFailureTotal = totals.toolFailureTotal;
+        host.executionEventBus.completeAttempt(runId, "succeeded");
+    }
+    return "⚠️ 达到最大迭代次数，任务未完成。";
+}
+/**
+ * Outer loop: start run, handle provider transport retries + recovery strategy.
+ */
+export async function runOuterAgentLoop(host) {
+    const recoveryState = host.getRecoveryState();
+    const resumable = host.activeRun && recoveryState?.status === "recovering";
+    const originalTask = resumable
+        ? host.activeRun.originalTask
+        : findLastUserMessageContent(host.messages);
+    const runId = resumable
+        ? host.activeRun.runId
+        : `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+    if (!resumable) {
+        host.setActiveRun({
+            runId,
+            sessionId: host.sessionId,
+            originalTask,
+            startedAt: Date.now(),
+        });
+        host.recoveryController.startRun({ runId, sessionId: host.sessionId, originalTask });
+        host.executionEventBus.startRun({ runId, sessionId: host.sessionId });
+    }
+    let transportAttempts = 0;
+    while (true) {
+        try {
+            const response = await host.executeInner();
+            if (host.getRecoveryState()?.status === "paused")
+                return response;
+            host.executionEventBus.completeRun(runId, "succeeded");
+            host.setActiveRun(null);
+            return response;
+        }
+        catch (error) {
+            host.executionEventBus.completeAttempt(runId, "failed");
+            const failure = classifyFailure(error, { provider: true });
+            if (failure.category === "provider_transient" && transportAttempts < 3) {
+                transportAttempts++;
+                const delay = Math.min(4_000, 250 * 2 ** (transportAttempts - 1)) + Math.floor(Math.random() * 100);
+                host.executionEventBus.emit({
+                    runId,
+                    sessionId: host.sessionId,
+                    type: "recovery_started",
+                    status: "recovering",
+                    stage: "provider",
+                    category: failure.category,
+                    fingerprint: failure.fingerprint,
+                    recoveryAction: "transport_retry",
+                });
+                host.emit("repair", failure.message, "provider transport retry", transportAttempts);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            const decision = host.recoveryController.recordFailure(failure, {});
+            const state = host.recoveryController.getRecoveryState();
+            host.executionEventBus.emit({
+                runId,
+                sessionId: host.sessionId,
+                type: "failure",
+                status: decision.action === "pause" ? "paused" : "recovering",
+                stage: "agent",
+                category: decision.category,
+                fingerprint: failure.fingerprint,
+                recoveryAction: decision.recommendedStrategy ?? decision.action,
+            });
+            host.emit("recovery_paused", state, decision);
+            if (decision.action === "pause") {
+                return host.formatRecoveryPause(failure.message, decision.reason);
+            }
+            await host.applyRecoveryStrategy(failure, decision.recommendedStrategy);
+            host.emit("repair", failure.message, decision.recommendedStrategy ?? decision.reason, state.strategyAttempts);
+            continue;
+        }
+    }
+}

package/dist/agent/subtask-parallel.d.ts

@@ -0,0 +1,29 @@
+import type { SubtaskResult } from "./subtask.js";
+import { type SubAgentRole } from "../agents/roles.js";
+export declare function isSubtaskParallelEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
+export declare function resolveParallelMax(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): number;
+/**
+ * 解析并行任务列表：优先 tasks 数组，否则空。
+ */
+export declare function parseParallelTasks(raw: unknown): string[];
+export interface ParallelExploreGate {
+    ok: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    tasks: string[];
+    role: SubAgentRole;
+}
+/**
+ * 校验是否允许并行：仅 explore/review 只读角色；须显式开启。
+ */
+export declare function gateParallelExplore(options: {
+    tasks: string[];
+    role?: unknown;
+    enabled?: boolean;
+    max?: number;
+}): ParallelExploreGate;
+export declare function formatParallelExploreReport(results: Array<{
+    task: string;
+    result: SubtaskResult;
+}>): string;
+//# sourceMappingURL=subtask-parallel.d.ts.map

package/dist/agent/subtask-parallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtask-parallel.d.ts","sourceRoot":"","sources":["../../src/agent/subtask-parallel.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI9E,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,OAAO,CAGT;AAED,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACxE,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAsBzD;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,mBAAmB,CAiDtB;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC,GACtD,MAAM,CAeR"}

package/dist/agent/subtask-parallel.js

@@ -0,0 +1,107 @@
+// ============================================================
+// Phase 3.2+ — 只读 explore 并行（默认关闭）
+// 启用：QLING_SUBTASK_PARALLEL=1
+// ============================================================
+import { normalizeSubAgentRole } from "../agents/roles.js";
+const ENABLED = new Set(["1", "true", "on", "yes"]);
+export function isSubtaskParallelEnabled(env = process.env) {
+    const raw = String(env.QLING_SUBTASK_PARALLEL ?? "").trim().toLowerCase();
+    return ENABLED.has(raw);
+}
+export function resolveParallelMax(env = process.env) {
+    const n = Number(env.QLING_SUBTASK_PARALLEL_MAX ?? 3);
+    if (!Number.isFinite(n) || n < 1)
+        return 3;
+    return Math.min(5, Math.floor(n));
+}
+/**
+ * 解析并行任务列表：优先 tasks 数组，否则空。
+ */
+export function parseParallelTasks(raw) {
+    if (!raw)
+        return [];
+    if (Array.isArray(raw)) {
+        return raw.map((t) => String(t ?? "").trim()).filter(Boolean);
+    }
+    if (typeof raw === "string") {
+        const s = raw.trim();
+        if (!s)
+            return [];
+        try {
+            const parsed = JSON.parse(s);
+            if (Array.isArray(parsed)) {
+                return parsed.map((t) => String(t ?? "").trim()).filter(Boolean);
+            }
+        }
+        catch {
+            // 按换行或 || 分割
+            return s
+                .split(/\n+|\|\|/)
+                .map((t) => t.trim())
+                .filter(Boolean);
+        }
+    }
+    return [];
+}
+/**
+ * 校验是否允许并行：仅 explore/review 只读角色；须显式开启。
+ */
+export function gateParallelExplore(options) {
+    const enabled = options.enabled ?? isSubtaskParallelEnabled();
+    const max = options.max ?? resolveParallelMax();
+    const tasks = options.tasks.filter(Boolean);
+    const role = normalizeSubAgentRole(options.role ?? "explore");
+    if (tasks.length === 0) {
+        return {
+            ok: false,
+            errorCode: "SUBTASK_PARALLEL_EMPTY",
+            errorMessage: "tasks 为空",
+            tasks: [],
+            role,
+        };
+    }
+    if (!enabled) {
+        return {
+            ok: false,
+            errorCode: "SUBTASK_PARALLEL_DISABLED",
+            errorMessage: "并行 subtask 默认关闭。启用: QLING_SUBTASK_PARALLEL=1（仅 explore/review 只读角色）",
+            tasks,
+            role,
+        };
+    }
+    if (role === "implement") {
+        return {
+            ok: false,
+            errorCode: "SUBTASK_PARALLEL_ROLE",
+            errorMessage: "并行仅允许 role=explore 或 review（只读）。写操作必须串行 implement。",
+            tasks,
+            role,
+        };
+    }
+    if (tasks.length > max) {
+        return {
+            ok: false,
+            errorCode: "SUBTASK_PARALLEL_TOO_MANY",
+            errorMessage: `并行任务过多: ${tasks.length} > max ${max}（QLING_SUBTASK_PARALLEL_MAX）`,
+            tasks,
+            role,
+        };
+    }
+    return { ok: true, tasks, role };
+}
+export function formatParallelExploreReport(results) {
+    const lines = [
+        "【并行探索回传】",
+        `count: ${results.length}`,
+        `ok: ${results.filter((r) => r.result.success).length}`,
+        `fail: ${results.filter((r) => !r.result.success).length}`,
+        "",
+    ];
+    results.forEach((item, i) => {
+        lines.push(`--- task[${i + 1}] ${item.result.success ? "OK" : "FAIL"} ---`);
+        lines.push(`goal: ${item.task.slice(0, 200)}`);
+        lines.push(item.result.contractText || item.result.output);
+        lines.push("");
+    });
+    return lines.join("\n").trim();
+}

package/dist/agent/subtask.d.ts

@@ -1,4 +1,5 @@
 import type { AgentConfig } from "../types.js";
+import { type SubAgentRole } from "../agents/roles.js";
 export interface SubtaskConfig {
     task: string;
     parentContext?: string;
@@ -6,16 +7,28 @@ export interface SubtaskConfig {
     depth?: number;
     tools?: AgentConfig["tools"];
     timeoutMs?: number;
+    /** explore | implement | review */
+    role?: SubAgentRole | string;
 }
 export interface SubtaskResult {
     success: boolean;
     output: string;
     iterations: number;
     durationMs: number;
+    role: SubAgentRole;
+    filesTouched: string[];
+    /** 已格式化的回传契约（父代理应优先使用） */
+    contractText: string;
 }
+interface TimeoutController {
+    setTimeout(callback: () => void, timeoutMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export declare function runWithTimeout<T>(operation: Promise<T>, timeoutMs: number, timers?: TimeoutController): Promise<T>;
 export declare class SubtaskRunner {
     private parentConfig;
     constructor(parentConfig: Partial<AgentConfig>);
     run(config: SubtaskConfig): Promise<SubtaskResult>;
 }
+export {};
 //# sourceMappingURL=subtask.d.ts.map

package/dist/agent/subtask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subtask.d.ts","sourceRoot":"","sources":["../../src/agent/subtask.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,aAAa,CAAC;AAGxD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,YAAY,CAAuB;gBAE/B,YAAY,EAAE,OAAO,CAAC,WAAW,CAAC;IAIxC,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;CAkDzD"}
+{"version":3,"file":"subtask.d.ts","sourceRoot":"","sources":["../../src/agent/subtask.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,KAAK,YAAY,EAOlB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0BAA0B;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,iBAAiB;IACzB,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAOD,wBAAsB,cAAc,CAAC,CAAC,EACpC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EACrB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,iBAA4C,GACnD,OAAO,CAAC,CAAC,CAAC,CAcZ;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,YAAY,CAAuB;gBAE/B,YAAY,EAAE,OAAO,CAAC,WAAW,CAAC;IAIxC,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;CA2EzD"}

package/dist/agent/subtask.js

@@ -1,8 +1,26 @@
 // ============================================================
 // 轻灵 - Subtask 隔离执行器
-// 在同进程内创建独立 AgentLoop 实例，共享 MemoryStore
+// 在同进程内创建独立 AgentLoop 实例；Phase 3.2 支持角色与回传契约
 // ============================================================
 import { AgentLoop } from "../agent-loop.js";
+import { buildRoleSystemPreamble, extractEvidenceHints, extractFilesTouchedFromMessages, filterToolsForRole, formatSubAgentReturnContract, normalizeSubAgentRole, } from "../agents/roles.js";
+const defaultTimeoutController = {
+    setTimeout: (callback, timeoutMs) => setTimeout(callback, timeoutMs),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export async function runWithTimeout(operation, timeoutMs, timers = defaultTimeoutController) {
+    let handle;
+    const timeout = new Promise((_, reject) => {
+        handle = timers.setTimeout(() => reject(new Error(`Subtask timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (handle !== undefined)
+            timers.clearTimeout(handle);
+    }
+}
 export class SubtaskRunner {
     parentConfig;
     constructor(parentConfig) {
@@ -12,9 +30,11 @@ export class SubtaskRunner {
         const start = Date.now();
         const maxIter = config.maxIterations ?? 10;
         const timeout = config.timeoutMs ?? 120_000;
-        const depth = config.depth ?? 1;
-        // depth enforcement: if depth >= 1, subtask cannot spawn further subtasks
-        const tools = config.tools ?? this.parentConfig.tools?.filter((t) => t.name !== "subtask") ?? [];
+        const role = normalizeSubAgentRole(config.role);
+        const baseTools = config.tools ??
+            this.parentConfig.tools?.filter((t) => t.name !== "subtask") ??
+            [];
+        const tools = filterToolsForRole(baseTools, role);
         const subtaskConfig = {
             ...this.parentConfig,
             tools,
@@ -22,34 +42,69 @@ export class SubtaskRunner {
         };
         const subAgent = new AgentLoop(subtaskConfig);
         await subAgent.waitForInit();
-        // inject parent context + task
-        let prompt = config.task;
+        const preamble = buildRoleSystemPreamble(role);
+        let prompt = `${preamble}\n\n[子任务]\n${config.task}`;
         if (config.parentContext) {
-            prompt = "[父任务上下文]\n" + config.parentContext + "\n\n[子任务]\n" + config.task;
+            prompt =
+                `${preamble}\n\n[父任务上下文]\n${config.parentContext}\n\n[子任务]\n${config.task}`;
         }
         subAgent.addUserMessage(prompt);
+        let rawOutput = "";
+        let success = false;
         try {
-            const output = await Promise.race([
-                subAgent.run(),
-                new Promise((_, reject) => setTimeout(() => reject(new Error("Subtask timeout")), timeout)),
-            ]);
-            return {
-                success: true,
-                output,
-                iterations: maxIter,
-                durationMs: Date.now() - start,
-            };
+            rawOutput = await runWithTimeout(subAgent.run(), timeout);
+            success = true;
         }
         catch (err) {
-            return {
-                success: false,
-                output: err.message,
-                iterations: maxIter,
-                durationMs: Date.now() - start,
-            };
+            rawOutput = err.message;
+            success = false;
         }
         finally {
-            await subAgent.shutdown();
+            try {
+                await subAgent.shutdown();
+            }
+            catch {
+                // ignore shutdown errors
+            }
+        }
+        const messages = subAgent.getMessagesSnapshot?.() ?? [];
+        const filesTouched = extractFilesTouchedFromMessages(messages);
+        const summary = buildSummary(rawOutput, success, role, filesTouched);
+        const evidence = extractEvidenceHints(rawOutput);
+        if (!success) {
+            evidence.unshift(`失败: ${rawOutput.slice(0, 200)}`);
         }
+        const durationMs = Date.now() - start;
+        const contractText = formatSubAgentReturnContract({
+            role,
+            success,
+            durationMs,
+            iterations: maxIter,
+            summary,
+            filesTouched,
+            evidence,
+            rawOutput,
+        });
+        return {
+            success,
+            output: contractText,
+            iterations: maxIter,
+            durationMs,
+            role,
+            filesTouched,
+            contractText,
+        };
+    }
+}
+function buildSummary(raw, success, role, files) {
+    const firstLine = raw
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0 && !l.startsWith("【")) ?? "";
+    const fileHint = files.length > 0 ? ` 触及 ${files.length} 个文件` : "";
+    if (!success) {
+        return `角色 ${role} 未完成${fileHint}: ${firstLine.slice(0, 120) || "见 evidence"}`;
     }
+    return (firstLine.slice(0, 200) ||
+        `角色 ${role} 已完成${fileHint}`);
 }

package/dist/agent/system-prompt.d.ts

@@ -0,0 +1,39 @@
+import type { PromptSectionRegistry } from "../types.js";
+import type { Message, ToolCall } from "../types.js";
+import type { MemoryStore } from "../memory.js";
+import type { LlmChatResponse } from "../providers/llm-client.js";
+export declare function findLastUserMessageContent(messages: Message[]): string;
+export declare function buildRuntimeMetaSection(options: {
+    provider?: string;
+    endpoint?: string;
+    workspaceDir?: string | null;
+    fileCacheDir?: string;
+    fileStateDir?: string;
+    runtimeRootDir: string;
+}): string;
+export declare function assembleSystemPrompt(options: {
+    baseSystemPrompt: string;
+    sectionRegistry: PromptSectionRegistry;
+    memoryStore: MemoryStore;
+    messages: Message[];
+    provider?: string;
+    endpoint?: string;
+    workspaceDir?: string | null;
+    fileCacheDir?: string;
+    fileStateDir?: string;
+    runtimeRootDir: string;
+}): Promise<string>;
+export type ReflectionDecision = "proceed" | "ask" | "block" | "warn";
+export declare function heuristicReflect(tc: ToolCall): {
+    decision: ReflectionDecision;
+    reason: string;
+};
+/**
+ * Self-reflective pre-check for high-risk tools.
+ * Uses optional chat callback; falls back to heuristics on failure.
+ */
+export declare function reflectiveThink(tc: ToolCall, chat: (systemPrompt: string, overrides?: Record<string, unknown>) => Promise<LlmChatResponse>): Promise<{
+    decision: ReflectionDecision;
+    reason: string;
+}>;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/agent/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agent/system-prompt.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAKtE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAYT;AAED,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,qBAAqB,CAAC;IACvC,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqClB;AAED,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAEtE,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAO/F;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,eAAe,CAAC,GAC5F,OAAO,CAAC;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAa3D"}