@qlingzzy/qling 1.0.0 → 1.1.1

package/dist/execution/failure-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-classifier.d.ts","sourceRoot":"","sources":["../../src/execution/failure-classifier.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEzE,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAiBD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,qBAAqB,CAgCnG;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,aAAa,CAAC,GAAG,MAAM,CAUpG"}

package/dist/execution/failure-classifier.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function normalizeMessage(value) {
+    return value
+        .toLowerCase()
+        .replace(/[a-z]:\\[^\s]+/gi, "<path>")
+        .replace(/(?:\/[^\s]+)+/g, "<path>")
+        .replace(/\d{4}-\d{2}-\d{2}(?:[ t]\d{2}:\d{2}:\d{2})?/g, "<time>")
+        .replace(/\b\d+(?:\.\d+)?\b/g, "<n>")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function classifyFailure(error, context = {}) {
+    const message = errorMessage(error);
+    const lower = message.toLowerCase();
+    const status = typeof error === "object" && error !== null && "status" in error
+        ? Number(error.status)
+        : undefined;
+    let category = context.provider ? "provider_terminal" : "tool_execution";
+    if (status === 429 || (status !== undefined && status >= 500) || /rate limit|econnreset|etimedout|temporar/.test(lower)) {
+        category = "provider_transient";
+    }
+    else if (/approval[_ ]required|requires approval/.test(lower)) {
+        category = "permission_required";
+    }
+    else if (/permission denied|approval denied|forbidden/.test(lower)) {
+        category = "permission_denied";
+    }
+    else if (/sandbox|outside (?:the )?workspace|path.*denied/.test(lower)) {
+        category = "sandbox_denied";
+    }
+    else if (/invalid (?:tool )?arguments?|schema validation|missing required/.test(lower)) {
+        category = "invalid_tool_arguments";
+    }
+    else if (/command not found|is not recognized|enoent/.test(lower)) {
+        category = "tool_not_found";
+    }
+    else if (/verification|test command|build failed|exited with code/.test(lower)) {
+        category = "verification_failed";
+    }
+    else if (/context (?:window )?(?:exhausted|length)|maximum context/.test(lower)) {
+        category = "context_exhausted";
+    }
+    else if (/repeated action|duplicate tool call/.test(lower)) {
+        category = "repeated_action";
+    }
+    else if (/cancel(?:ed|led)/.test(lower)) {
+        category = "user_canceled";
+    }
+    const classification = { category, message, ...context };
+    return { ...classification, fingerprint: createFailureFingerprint(classification) };
+}
+export function createFailureFingerprint(failure) {
+    const target = failure.targetPath ? path.basename(failure.targetPath).toLowerCase() : "";
+    const stable = [
+        failure.category,
+        failure.tool ?? "",
+        normalizeMessage(failure.message),
+        target,
+        normalizeMessage(failure.verificationCommand ?? ""),
+    ].join("|");
+    return createHash("sha256").update(stable).digest("hex").slice(0, 20);
+}

package/dist/execution/progress-detector.d.ts

@@ -0,0 +1,3 @@
+import type { ProgressSnapshot } from "./types.js";
+export declare function hasExecutionProgress(before: ProgressSnapshot | undefined, after: ProgressSnapshot): boolean;
+//# sourceMappingURL=progress-detector.d.ts.map

package/dist/execution/progress-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-detector.d.ts","sourceRoot":"","sources":["../../src/execution/progress-detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAUnD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAW3G"}

package/dist/execution/progress-detector.js

@@ -0,0 +1,23 @@
+function normalizedTests(tests) {
+    return [...new Set(tests ?? [])].sort();
+}
+function normalizedFiles(files) {
+    return [...new Set(files ?? [])].sort();
+}
+export function hasExecutionProgress(before, after) {
+    if (!before)
+        return true;
+    if (before.diffHash !== after.diffHash)
+        return true;
+    if ((after.completedTodos ?? 0) > (before.completedTodos ?? 0))
+        return true;
+    const previousTests = normalizedTests(before.failingTests);
+    const currentTests = normalizedTests(after.failingTests);
+    if (currentTests.length < previousTests.length)
+        return true;
+    const previousFiles = normalizedFiles(before.changedFiles);
+    const currentFiles = normalizedFiles(after.changedFiles);
+    if (previousFiles.join("\0") !== currentFiles.join("\0"))
+        return true;
+    return after.changed === true && before.changed !== true;
+}

package/dist/execution/recovery-controller.d.ts

@@ -0,0 +1,24 @@
+import { RecoveryStrategyPlanner } from "./recovery-strategy-planner.js";
+import type { FailureClassification, ProgressSnapshot, RecoveryDecision, RecoveryState } from "./types.js";
+export type RecoveryAction = "retry" | "next" | "edit" | "cancel";
+export declare class RecoveryController {
+    private readonly sameFingerprintLimit;
+    private readonly strategyAttemptLimit;
+    private readonly fingerprintCounts;
+    private readonly planner;
+    private state;
+    constructor(options?: {
+        sameFingerprintLimit?: number;
+        strategyAttemptLimit?: number;
+        planner?: RecoveryStrategyPlanner;
+    });
+    startRun(input: {
+        runId: string;
+        sessionId: string;
+        originalTask: string;
+    }): RecoveryState;
+    recordFailure(failure: FailureClassification, progress: ProgressSnapshot): RecoveryDecision;
+    getRecoveryState(): RecoveryState;
+    applyAction(action: RecoveryAction): RecoveryState;
+}
+//# sourceMappingURL=recovery-controller.d.ts.map

package/dist/execution/recovery-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-controller.d.ts","sourceRoot":"","sources":["../../src/execution/recovery-controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3G,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAElE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA6B;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,KAAK,CAA4B;gBAE7B,OAAO,GAAE;QAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,uBAAuB,CAAA;KAAO;IAM7H,QAAQ,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,aAAa;IAY1F,aAAa,CAAC,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB;IAyC3F,gBAAgB,IAAI,aAAa;IAYjC,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa;CA+BnD"}

package/dist/execution/recovery-controller.js

@@ -0,0 +1,114 @@
+import { hasExecutionProgress } from "./progress-detector.js";
+import { RecoveryStrategyPlanner } from "./recovery-strategy-planner.js";
+export class RecoveryController {
+    sameFingerprintLimit;
+    strategyAttemptLimit;
+    fingerprintCounts = new Map();
+    planner;
+    state;
+    constructor(options = {}) {
+        this.sameFingerprintLimit = options.sameFingerprintLimit ?? 2;
+        this.strategyAttemptLimit = options.strategyAttemptLimit ?? 4;
+        this.planner = options.planner ?? new RecoveryStrategyPlanner();
+    }
+    startRun(input) {
+        this.fingerprintCounts.clear();
+        this.state = {
+            ...input,
+            status: "running",
+            strategyAttempts: 0,
+            remainingStrategyAttempts: this.strategyAttemptLimit,
+            attemptedStrategies: [],
+        };
+        return this.getRecoveryState();
+    }
+    recordFailure(failure, progress) {
+        if (!this.state)
+            throw new Error("recovery run has not started");
+        const fingerprint = failure.fingerprint ?? "unknown";
+        const count = (this.fingerprintCounts.get(fingerprint) ?? 0) + 1;
+        this.fingerprintCounts.set(fingerprint, count);
+        const madeProgress = hasExecutionProgress(this.state.lastProgress, progress);
+        const strategyAttempts = this.state.strategyAttempts + 1;
+        const remainingStrategyAttempts = Math.max(0, this.strategyAttemptLimit - strategyAttempts);
+        const hardStop = ["provider_terminal", "permission_required", "permission_denied", "sandbox_denied", "repeated_action", "user_canceled"].includes(failure.category);
+        const attempted = this.state.attemptedStrategies;
+        const recommendedStrategy = this.planner.next(failure.category, attempted);
+        let decision;
+        if (hardStop) {
+            decision = { action: "pause", category: failure.category, reason: failure.category, remainingStrategyAttempts };
+        }
+        else if (!recommendedStrategy) {
+            decision = { action: "pause", category: failure.category, reason: "no_recovery_strategy", remainingStrategyAttempts };
+        }
+        else if (strategyAttempts >= this.strategyAttemptLimit) {
+            decision = { action: "pause", category: failure.category, reason: "strategy_budget_exhausted", remainingStrategyAttempts };
+        }
+        else if (count >= this.sameFingerprintLimit && !madeProgress) {
+            decision = { action: "pause", category: "no_progress", reason: "same_failure_without_progress", remainingStrategyAttempts };
+        }
+        else {
+            decision = { action: "recover", category: failure.category, reason: "recovery_available", remainingStrategyAttempts, recommendedStrategy };
+        }
+        const nextState = {
+            ...this.state,
+            status: decision.action === "recover" ? "recovering" : "paused",
+            strategyAttempts,
+            remainingStrategyAttempts,
+            lastFailure: failure,
+            lastProgress: { ...progress, failingTests: progress.failingTests ? [...progress.failingTests] : undefined },
+        };
+        if (decision.recommendedStrategy) {
+            nextState.currentStrategy = decision.recommendedStrategy;
+            nextState.attemptedStrategies = [...attempted, decision.recommendedStrategy];
+        }
+        this.state = nextState;
+        return decision;
+    }
+    getRecoveryState() {
+        if (!this.state)
+            throw new Error("recovery run has not started");
+        return {
+            ...this.state,
+            attemptedStrategies: [...this.state.attemptedStrategies],
+            lastFailure: this.state.lastFailure ? { ...this.state.lastFailure } : undefined,
+            lastProgress: this.state.lastProgress
+                ? { ...this.state.lastProgress, failingTests: this.state.lastProgress.failingTests ? [...this.state.lastProgress.failingTests] : undefined }
+                : undefined,
+        };
+    }
+    applyAction(action) {
+        if (!this.state)
+            throw new Error("recovery run has not started");
+        if (action === "cancel") {
+            this.state = { ...this.state, status: "canceled" };
+            return this.getRecoveryState();
+        }
+        if (this.state.status !== "paused") {
+            throw new Error("no active paused recovery task");
+        }
+        if (action === "edit") {
+            this.state = { ...this.state, status: "canceled" };
+        }
+        else if (action === "next") {
+            const category = this.state.lastFailure?.category;
+            const strategy = category ? this.planner.next(category, this.state.attemptedStrategies) : undefined;
+            this.state = strategy
+                ? {
+                    ...this.state,
+                    status: "recovering",
+                    currentStrategy: strategy,
+                    attemptedStrategies: [...this.state.attemptedStrategies, strategy],
+                }
+                : { ...this.state, status: "paused" };
+            if (!strategy) {
+                throw new Error("no remaining recovery strategy");
+            }
+        }
+        else {
+            // retry: reuse currentStrategy without consuming another budget slot
+            this.state = { ...this.state, status: "recovering" };
+        }
+        return this.getRecoveryState();
+    }
+}

package/dist/execution/recovery-messages.d.ts

@@ -0,0 +1,24 @@
+import type { RecoveryState } from "./types.js";
+export declare function formatRecoveryInstruction(failure: {
+    category: string;
+    message: string;
+}, strategy?: string): string;
+export declare function formatRecoveryPause(options: {
+    reason: string;
+    next: string;
+    state: RecoveryState | null;
+    verificationStagesSummary: string;
+}): string;
+export declare function buildVerificationFailureUserMessage(options: {
+    failedStage?: string;
+    failedCommand: string;
+    failingTests: string[];
+    changedFiles: string[];
+    fingerprint?: string;
+    attemptedStrategies: string[];
+    strategy: string;
+    stdout: string;
+    stderr: string;
+    instructionBody: string;
+}): string;
+//# sourceMappingURL=recovery-messages.d.ts.map

package/dist/execution/recovery-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-messages.d.ts","sourceRoot":"","sources":["../../src/execution/recovery-messages.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiBhD,wBAAgB,yBAAyB,CACvC,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC9C,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAMR;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IAC5B,yBAAyB,EAAE,MAAM,CAAC;CACnC,GAAG,MAAM,CAeT;AAED,wBAAgB,mCAAmC,CAAC,OAAO,EAAE;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAWT"}

package/dist/execution/recovery-messages.js

@@ -0,0 +1,48 @@
+// ============================================================
+// 恢复文案（从 AgentLoop 抽出）— 纯函数，无 IO
+// ============================================================
+const STRATEGY_INSTRUCTIONS = {
+    repair_tool_arguments: "检查工具参数 schema，修正参数后只重试这一次工具调用。",
+    return_tool_schema: "不要继续执行工具；说明缺失或非法字段，并给出正确参数示例。",
+    inspect_command_environment: "先检查 PATH、package scripts 和当前平台可用命令，再选择一个有证据支持的替代命令。",
+    use_supported_command: "改用工作区内已有的 package script 或轻灵已注册工具，不要盲目重复原命令。",
+    inspect_tool_error: "分析工具错误的直接原因，只修改当前失败目标。",
+    retry_tool_once: "在确认参数和目标未变化后，仅重试当前工具一次。",
+    narrow_tool_scope: "缩小工具操作范围到当前失败目标，避免重复无关操作。",
+    return_tool_diagnostics: "停止重复调用，返回可验证的诊断信息和下一步建议。",
+    targeted_verification_repair: "仅修复当前失败测试集合，不重复无关的全量验证。",
+    narrow_verification_scope: "缩小验证范围到受影响文件和失败测试，先取得可观测进展。",
+    compact_context_once: "仅执行一次上下文压缩，保留用户原文、工具链和错误证据，然后继续任务。",
+    transport_retry: "提供方瞬时错误已退避；不要改变任务目标，直接继续。",
+};
+export function formatRecoveryInstruction(failure, strategy) {
+    return (`【定向恢复】失败类别=${failure.category}；失败原因=${failure.message}\n` +
+        `恢复策略=${strategy ?? "暂无"}\n` +
+        (STRATEGY_INSTRUCTIONS[strategy ?? ""] ?? "停止重复动作，基于最新证据选择下一步。"));
+}
+export function formatRecoveryPause(options) {
+    const state = options.state;
+    const files = state?.lastProgress?.changedFiles?.join(", ") || "-";
+    return [
+        "执行已暂停",
+        `原因: ${options.reason}`,
+        `已尝试: ${state?.strategyAttempts ?? 0} 次恢复策略`,
+        `当前策略: ${state?.currentStrategy ?? "-"}`,
+        `已尝试策略: ${(state?.attemptedStrategies ?? []).join(", ") || "-"}`,
+        `当前证据: ${state?.lastFailure?.fingerprint ?? "-"}`,
+        `修改文件: ${files}`,
+        `验证阶段: ${options.verificationStagesSummary}`,
+        `下一步: ${options.next}；使用 /recover retry|next|edit|cancel`,
+        "边界: 本地摘要轨迹已保存，不包含 prompt 或工具正文。",
+    ].join("\n");
+}
+export function buildVerificationFailureUserMessage(options) {
+    const files = options.changedFiles.join(", ") || "-";
+    return (`【定向验证失败】阶段=${options.failedStage ?? "unknown"} 命令=\`${options.failedCommand}\`\n` +
+        `失败测试=${options.failingTests.join(", ") || "unknown"}\n` +
+        `修改文件=${files}\n` +
+        `指纹=${options.fingerprint ?? "-"}\n` +
+        `已尝试策略=${options.attemptedStrategies.join(", ") || "-"}\n` +
+        `恢复策略=${options.strategy}\n[stdout]\n${options.stdout}\n[stderr]\n${options.stderr}\n` +
+        options.instructionBody);
+}

package/dist/execution/recovery-metrics.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionEvent } from "./types.js";
+export interface RecoveryMetrics {
+    runs: number;
+    firstAttemptSuccessRate: number;
+    finalSuccessRate: number;
+    averageStrategyAttempts: number;
+    repeatedFailureRate: number;
+    automaticRecoverySuccessRate: number;
+    noProgressStops: number;
+    /** Runs that entered paused (user intervention surface). */
+    pausedRuns: number;
+    /** Average ms from first failure to first pause event; 0 when unknown. */
+    averageTimeToPauseMs: number;
+}
+export declare function calculateRecoveryMetrics(events: ExecutionEvent[]): RecoveryMetrics;
+//# sourceMappingURL=recovery-metrics.d.ts.map

package/dist/execution/recovery-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-metrics.d.ts","sourceRoot":"","sources":["../../src/execution/recovery-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB,EAAE,MAAM,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4BAA4B,EAAE,MAAM,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,eAAe,CAmElF"}

package/dist/execution/recovery-metrics.js

@@ -0,0 +1,73 @@
+export function calculateRecoveryMetrics(events) {
+    const runs = new Map();
+    for (const event of events) {
+        const current = runs.get(event.runId) ?? [];
+        runs.set(event.runId, [...current, event]);
+    }
+    let firstAttemptSuccesses = 0;
+    let finalSuccesses = 0;
+    let strategyAttempts = 0;
+    let recoveredSuccesses = 0;
+    let runsWithRecovery = 0;
+    let repeatedFailures = 0;
+    let failures = 0;
+    let noProgressStops = 0;
+    let pausedRuns = 0;
+    let timeToPauseTotal = 0;
+    let timeToPauseSamples = 0;
+    for (const runEvents of runs.values()) {
+        const attempts = runEvents.filter((event) => event.type === "attempt_completed");
+        let terminal;
+        for (let index = runEvents.length - 1; index >= 0; index--) {
+            if (runEvents[index].type === "run_completed") {
+                terminal = runEvents[index];
+                break;
+            }
+        }
+        const recoveries = runEvents.filter((event) => event.type === "recovery_started" || event.recoveryAction === "recover");
+        const fingerprints = new Set();
+        if (attempts[0]?.status === "succeeded")
+            firstAttemptSuccesses++;
+        if (terminal?.status === "succeeded")
+            finalSuccesses++;
+        strategyAttempts += recoveries.length;
+        if (recoveries.length > 0) {
+            runsWithRecovery++;
+            if (terminal?.status === "succeeded")
+                recoveredSuccesses++;
+        }
+        const pauseEvent = runEvents.find((event) => event.status === "paused");
+        if (pauseEvent) {
+            pausedRuns++;
+            const firstFailure = runEvents.find((event) => event.type === "failure" || event.type === "verification_failed" || event.status === "failed");
+            if (firstFailure && pauseEvent.timestamp >= firstFailure.timestamp) {
+                timeToPauseTotal += pauseEvent.timestamp - firstFailure.timestamp;
+                timeToPauseSamples++;
+            }
+        }
+        for (const event of runEvents.filter((item) => item.type.includes("failure") || item.type === "failure")) {
+            failures++;
+            if (event.fingerprint && fingerprints.has(event.fingerprint))
+                repeatedFailures++;
+            if (event.fingerprint)
+                fingerprints.add(event.fingerprint);
+            if (event.category === "no_progress")
+                noProgressStops++;
+        }
+    }
+    const runCount = runs.size;
+    return {
+        runs: runCount,
+        firstAttemptSuccessRate: ratio(firstAttemptSuccesses, runCount),
+        finalSuccessRate: ratio(finalSuccesses, runCount),
+        averageStrategyAttempts: ratio(strategyAttempts, runCount),
+        repeatedFailureRate: ratio(repeatedFailures, failures),
+        automaticRecoverySuccessRate: ratio(recoveredSuccesses, runsWithRecovery),
+        noProgressStops,
+        pausedRuns,
+        averageTimeToPauseMs: timeToPauseSamples === 0 ? 0 : Math.round(timeToPauseTotal / timeToPauseSamples),
+    };
+}
+function ratio(value, total) {
+    return total === 0 ? 0 : Number((value / total).toFixed(4));
+}

package/dist/execution/recovery-strategy-planner.d.ts

@@ -0,0 +1,6 @@
+import type { FailureCategory } from "./types.js";
+export declare class RecoveryStrategyPlanner {
+    list(category: FailureCategory): string[];
+    next(category: FailureCategory, attempted?: readonly string[]): string | undefined;
+}
+//# sourceMappingURL=recovery-strategy-planner.d.ts.map

package/dist/execution/recovery-strategy-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-strategy-planner.d.ts","sourceRoot":"","sources":["../../src/execution/recovery-strategy-planner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAmBlD,qBAAa,uBAAuB;IAClC,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE;IAIzC,IAAI,CAAC,QAAQ,EAAE,eAAe,EAAE,SAAS,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,GAAG,SAAS;CAGvF"}

package/dist/execution/recovery-strategy-planner.js

@@ -0,0 +1,24 @@
+/** Deterministic recovery choices. Empty lists are deliberate hard stops. */
+const STRATEGIES = {
+    provider_transient: ["transport_retry"],
+    provider_terminal: [],
+    invalid_tool_arguments: ["repair_tool_arguments", "return_tool_schema"],
+    permission_required: [],
+    permission_denied: [],
+    sandbox_denied: [],
+    tool_not_found: ["inspect_command_environment", "use_supported_command"],
+    tool_execution: ["inspect_tool_error", "retry_tool_once", "narrow_tool_scope", "return_tool_diagnostics"],
+    verification_failed: ["targeted_verification_repair", "narrow_verification_scope"],
+    context_exhausted: ["compact_context_once"],
+    repeated_action: [],
+    no_progress: [],
+    user_canceled: [],
+};
+export class RecoveryStrategyPlanner {
+    list(category) {
+        return [...(STRATEGIES[category] ?? [])];
+    }
+    next(category, attempted = []) {
+        return this.list(category).find((strategy) => !attempted.includes(strategy));
+    }
+}

package/dist/execution/run-trace-store.d.ts

@@ -0,0 +1,29 @@
+import type { ExecutionEvent } from "./types.js";
+export declare class RunTraceStore {
+    private readonly rootDir;
+    private readonly now;
+    private readonly retentionMs;
+    private readonly maxBytes;
+    private appendCount;
+    constructor(options?: {
+        rootDir?: string;
+        now?: () => number;
+        retentionDays?: number;
+        maxBytes?: number;
+    });
+    getRunPath(sessionId: string, runId: string): string;
+    append(value: object): Promise<void>;
+    readRun(sessionId: string, runId: string): Promise<ExecutionEvent[]>;
+    listRunIds(sessionId: string): Promise<string[]>;
+    queryRecent(sessionId: string, runId: string, options?: {
+        limit?: number;
+        maxScanBytes?: number;
+    }): Promise<{
+        events: ExecutionEvent[];
+        scannedBytes: number;
+        truncated: boolean;
+    }>;
+    purge(): Promise<void>;
+    private collectFiles;
+}
+//# sourceMappingURL=run-trace-store.d.ts.map

package/dist/execution/run-trace-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-trace-store.d.ts","sourceRoot":"","sources":["../../src/execution/run-trace-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAOnE,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,WAAW,CAAK;gBAEZ,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO;IAO7G,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAI9C,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBpC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAUpE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAchD,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QACpH,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;IAuBI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAYd,YAAY;CAgB3B"}

package/dist/execution/run-trace-store.js

@@ -0,0 +1,140 @@
+import { readdir, readFile, mkdir, appendFile, rm, stat, open } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const EVENT_KEYS = [
+    "eventId", "runId", "sessionId", "attemptId", "toolCallId", "type", "timestamp", "stage", "status", "tool",
+    "category", "fingerprint", "durationMs", "recoveryAction",
+];
+export class RunTraceStore {
+    rootDir;
+    now;
+    retentionMs;
+    maxBytes;
+    appendCount = 0;
+    constructor(options = {}) {
+        this.rootDir = options.rootDir ?? path.join(os.homedir(), ".qling", "runs");
+        this.now = options.now ?? (() => Date.now());
+        this.retentionMs = (options.retentionDays ?? 30) * 24 * 60 * 60 * 1000;
+        this.maxBytes = options.maxBytes ?? 50 * 1024 * 1024;
+    }
+    getRunPath(sessionId, runId) {
+        return path.join(this.rootDir, safeSegment(sessionId), `${safeSegment(runId)}.jsonl`);
+    }
+    async append(value) {
+        const input = value;
+        const sessionId = typeof input.sessionId === "string" ? input.sessionId : "unknown";
+        const runId = typeof input.runId === "string" ? input.runId : "unknown";
+        const event = {};
+        for (const key of EVENT_KEYS) {
+            if (input[key] !== undefined)
+                event[key] = input[key];
+        }
+        if (input.progress && typeof input.progress === "object") {
+            const value = input.progress;
+            event.progress = {
+                ...(typeof value.changed === "boolean" ? { changed: value.changed } : {}),
+                ...(typeof value.diffHash === "string" ? { diffHash: value.diffHash } : {}),
+                ...(Array.isArray(value.failingTests) ? { failingTests: value.failingTests.filter((item) => typeof item === "string") } : {}),
+                ...(typeof value.completedTodos === "number" ? { completedTodos: value.completedTodos } : {}),
+            };
+        }
+        event.timestamp ??= this.now();
+        const file = this.getRunPath(sessionId, runId);
+        await mkdir(path.dirname(file), { recursive: true });
+        await appendFile(file, `${JSON.stringify(event)}\n`, "utf8");
+        this.appendCount++;
+        if (this.appendCount % 100 === 0)
+            await this.purge();
+    }
+    async readRun(sessionId, runId) {
+        try {
+            const raw = await readFile(this.getRunPath(sessionId, runId), "utf8");
+            return raw.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    async listRunIds(sessionId) {
+        const directory = path.join(this.rootDir, safeSegment(sessionId));
+        try {
+            const names = await readdir(directory);
+            const entries = await Promise.all(names.filter((name) => name.endsWith(".jsonl")).map(async (name) => {
+                const filePath = path.join(directory, name);
+                return { id: name.slice(0, -6), mtimeMs: (await stat(filePath)).mtimeMs };
+            }));
+            return entries.sort((a, b) => b.mtimeMs - a.mtimeMs).map((entry) => entry.id);
+        }
+        catch {
+            return [];
+        }
+    }
+    async queryRecent(sessionId, runId, options = {}) {
+        const limit = Math.max(1, options.limit ?? 50);
+        const maxScanBytes = Math.max(1_024, options.maxScanBytes ?? 1024 * 1024);
+        const filePath = this.getRunPath(sessionId, runId);
+        let handle;
+        try {
+            handle = await open(filePath, "r");
+            const info = await handle.stat();
+            const scannedBytes = Math.min(info.size, maxScanBytes);
+            const buffer = Buffer.alloc(scannedBytes);
+            await handle.read(buffer, 0, scannedBytes, info.size - scannedBytes);
+            let text = buffer.toString("utf8");
+            if (scannedBytes < info.size)
+                text = text.slice(text.indexOf("\n") + 1);
+            const events = text.split(/\r?\n/).filter(Boolean).slice(-limit).map((line) => JSON.parse(line));
+            return { events, scannedBytes, truncated: scannedBytes < info.size };
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { events: [], scannedBytes: 0, truncated: false };
+            throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    async purge() {
+        const files = await this.collectFiles();
+        const cutoff = this.now() - this.retentionMs;
+        let total = files.reduce((sum, file) => sum + file.size, 0);
+        for (const file of files.sort((a, b) => a.mtimeMs - b.mtimeMs)) {
+            if (file.mtimeMs < cutoff || total > this.maxBytes) {
+                await rm(file.path, { force: true });
+                total -= file.size;
+            }
+        }
+    }
+    async collectFiles() {
+        const result = [];
+        let sessions = [];
+        try {
+            sessions = await readdir(this.rootDir);
+        }
+        catch {
+            return result;
+        }
+        for (const session of sessions) {
+            const directory = path.join(this.rootDir, session);
+            let files = [];
+            try {
+                files = await readdir(directory);
+            }
+            catch {
+                continue;
+            }
+            for (const file of files.filter((name) => name.endsWith(".jsonl"))) {
+                const filePath = path.join(directory, file);
+                const info = await stat(filePath);
+                result.push({ path: filePath, size: info.size, mtimeMs: info.mtimeMs });
+            }
+        }
+        return result;
+    }
+}
+function safeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}