@tea-agent/loop-agent 0.10.0 → 0.11.0

package/dist/shared/artifacts-core.js

@@ -2,13 +2,25 @@ import path from 'node:path';
 import { resolveTaskContextFromDir, writeTaskArtifactFile, } from '../infrastructure/harness/task-store.js';
 export const ARTIFACTS_DIR = 'artifacts';
 const SPEC_ARTIFACT_STEPS = ['analyze', 'plan'];
-const DEFAULT_ARTIFACTS = {
-    '分析报告.md': '# 分析报告\n\n## 1. 任务目标\n\n## 2. 当前现状\n\n## 3. 受影响模块与文件\n\n## 4. 关键约束与不变式\n\n## 5. 硬约束摘要\n\n## 6. 允许修改范围 / 禁止修改范围\n\n## 7. 风险点\n\n## 8. 待确认问题\n',
-    '实现计划.md': '# 实现计划\n\n## 1. 修改目标\n\n## 2. 修改范围\n\n## 3. 允许修改文件 / 目录\n\n## 4. 明确不做的内容\n\n## 5. 关键决策\n\n## 6. 不变式\n\n## 7. 风险与回滚点\n\n## 8. 测试与验证方案\n\n## 9. 不在本次范围内的事项\n\n## 10. 待确认事项\n',
+/** Promote-run / closeout bridge templates seeded by new-task. */
+const SEEDED_ARTIFACTS = {
     '修改记录.md': '# 修改记录\n\n## 1. 修改文件清单\n\n## 2. 关键改动说明\n',
     '验证结果.md': '# 验证结果\n\n## 1. 执行的命令\n\n## 2. 通过项\n\n## 3. 失败项\n',
+};
+/**
+ * Legacy L1 analyze/plan/retrospective templates.
+ * Kept only so validateArtifactContent can recognize unchanged historical files.
+ * new-task must not seed these.
+ */
+const LEGACY_ARTIFACT_TEMPLATES = {
+    '分析报告.md': '# 分析报告\n\n## 1. 任务目标\n\n## 2. 当前现状\n\n## 3. 受影响模块与文件\n\n## 4. 关键约束与不变式\n\n## 5. 硬约束摘要\n\n## 6. 允许修改范围 / 禁止修改范围\n\n## 7. 风险点\n\n## 8. 待确认问题\n',
+    '实现计划.md': '# 实现计划\n\n## 1. 修改目标\n\n## 2. 修改范围\n\n## 3. 允许修改文件 / 目录\n\n## 4. 明确不做的内容\n\n## 5. 关键决策\n\n## 6. 不变式\n\n## 7. 风险与回滚点\n\n## 8. 测试与验证方案\n\n## 9. 不在本次范围内的事项\n\n## 10. 待确认事项\n',
     '复盘报告.md': '# 复盘报告\n\n## 1. 质量复盘\n\n## 2. 流程问题\n\n## 3. 下次建议\n',
 };
+const ARTIFACT_TEMPLATES = {
+    ...LEGACY_ARTIFACT_TEMPLATES,
+    ...SEEDED_ARTIFACTS,
+};
 const ARTIFACT_NAME_BY_STEP = {
     analyze: '分析报告.md',
     plan: '实现计划.md',
@@ -16,6 +28,8 @@ const ARTIFACT_NAME_BY_STEP = {
     verify: '验证结果.md',
     retrospective: '复盘报告.md',
 };
+/** Steps whose artifact files are seeded by new-task (promote/closeout bridge). */
+export const SEEDED_ARTIFACT_STEPS = ['implement', 'verify'];
 export function getArtifactFileName(step) {
     return ARTIFACT_NAME_BY_STEP[step];
 }
@@ -35,6 +49,9 @@ export function formatSpecArtifactRelativePaths() {
 export function formatSpecArtifactDisplayNames() {
     return SPEC_ARTIFACT_STEPS.map((step) => getArtifactDisplayName(step)).join(' + ');
 }
+export function listSeededArtifactFileNames() {
+    return Object.keys(SEEDED_ARTIFACTS);
+}
 const REQUIRED_HEADINGS = {
     analyze: ['# 分析报告', '## 1. 任务目标'],
     plan: ['# 实现计划', '## 1. 修改目标'],
@@ -43,7 +60,7 @@ const REQUIRED_HEADINGS = {
 };
 export async function initializeArtifacts(taskDir) {
     const { repoRoot, taskId } = resolveTaskContextFromDir(taskDir);
-    await Promise.all(Object.entries(DEFAULT_ARTIFACTS).map(([name, content]) => writeTaskArtifactFile(repoRoot, taskId, name, content)));
+    await Promise.all(Object.entries(SEEDED_ARTIFACTS).map(([name, content]) => writeTaskArtifactFile(repoRoot, taskId, name, content)));
 }
 export function getArtifactPath(taskDir, step) {
     return path.join(taskDir, ARTIFACTS_DIR, getArtifactFileName(step));
@@ -57,7 +74,9 @@ function normalizeArtifactContent(content) {
 }
 function isUnchangedNewTaskTemplate(step, content) {
     const artifactName = ARTIFACT_NAME_BY_STEP[step];
-    const template = DEFAULT_ARTIFACTS[artifactName];
+    const template = ARTIFACT_TEMPLATES[artifactName];
+    if (!template)
+        return false;
     return normalizeArtifactContent(content) === normalizeArtifactContent(template);
 }
 function firstRequiredSectionIsEmpty(step, content) {

package/dist/shared/output-truncation.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+export function truncateOutput(text, maxBytes) {
+    if (!text)
+        return { text, truncated: false };
+    if (maxBytes <= 0) {
+        return { text: "\n...[truncated]", truncated: true };
+    }
+    if (Buffer.byteLength(text, "utf-8") <= maxBytes) {
+        return { text, truncated: false };
+    }
+    let low = 0;
+    let high = text.length;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (Buffer.byteLength(text.slice(0, mid), "utf-8") <= maxBytes) {
+            low = mid;
+        }
+        else {
+            high = mid - 1;
+        }
+    }
+    let end = low;
+    // Avoid ending the prefix on a dangling UTF-16 high surrogate.
+    if (end > 0) {
+        const code = text.charCodeAt(end - 1);
+        if (code >= 0xd800 && code <= 0xdbff)
+            end -= 1;
+    }
+    return {
+        text: `${text.slice(0, end)}\n...[truncated]`,
+        truncated: true,
+    };
+}
+export function redactPromptForLog(prompt) {
+    const hash = createHash("sha256").update(prompt).digest("hex").slice(0, 12);
+    return `<prompt sha256=${hash} len=${prompt.length}>`;
+}

package/dist/shared/package-metadata.js

@@ -0,0 +1,353 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { platform } from "node:os";
+// ---------------------------------------------------------------------------
+// Public helpers
+// ---------------------------------------------------------------------------
+/**
+ * Read the `version` field from a package.json file.
+ *
+ * Returns `undefined` when the file is missing, unreadable, or lacks a
+ * string `version` field — callers must treat `undefined` as a hard failure
+ * for identity construction.
+ */
+export function readPackageVersion(packageDir) {
+    try {
+        const raw = readFileSync(path.join(packageDir, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string")
+            return parsed.version;
+    }
+    catch {
+        // file missing or unreadable
+    }
+    return undefined;
+}
+/**
+ * Read the `name` field from a package.json file.
+ *
+ * Returns `undefined` when the file is missing, unreadable, or lacks a
+ * string `name` field.
+ */
+export function readPackageName(packageDir) {
+    try {
+        const raw = readFileSync(path.join(packageDir, "package.json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.name === "string")
+            return parsed.name;
+    }
+    catch {
+        // file missing or unreadable
+    }
+    return undefined;
+}
+/**
+ * Compute the SHA-256 hash of a file on disk.
+ *
+ * Returns `undefined` when the file is unreadable — callers must treat this
+ * as a hard failure for identity construction.
+ */
+export function computeBinarySha256(filePath) {
+    try {
+        const buffer = readFileSync(filePath);
+        return createHash("sha256").update(buffer).digest("hex");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compute a portable, deterministic content fingerprint for the installed
+ * package rooted at `packageRoot`.
+ *
+ * The fingerprint covers four scopes (package.json, bin/**, dist/**,
+ * skills/**) and is independent of the absolute installation path.
+ *
+ * Sorting uses code-point order (UTF-8 byte comparison), NOT localeCompare,
+ * to ensure deterministic behaviour across locales.
+ */
+export function computePackageFingerprint(packageRoot) {
+    const scope = [
+        "package.json",
+        "bin/**",
+        "dist/**",
+        "skills/**",
+    ];
+    // Collecting entries ---------------------------------------------------
+    const entries = [];
+    // 1) package.json (required single file)
+    addRequiredFile(entries, path.join(packageRoot, "package.json"), "");
+    // 2) bin/**, dist/**, skills/** via recursive walk
+    for (const dir of ["bin", "dist", "skills"]) {
+        const absoluteDir = path.join(packageRoot, dir);
+        collectTree(entries, absoluteDir, dir);
+    }
+    // 3) Deterministic sort by relative path (code-point / byte order)
+    entries.sort((a, b) => {
+        const aBuf = Buffer.from(a.relativePath, "utf-8");
+        const bBuf = Buffer.from(b.relativePath, "utf-8");
+        const minLen = Math.min(aBuf.length, bBuf.length);
+        for (let i = 0; i < minLen; i++) {
+            if (aBuf[i] !== bBuf[i])
+                return aBuf[i] - bBuf[i];
+        }
+        return aBuf.length - bBuf.length;
+    });
+    // 4) Cumulative hash: hash of (<relativePath> + "\t" + <contentHash>) lines
+    const cumulative = createHash("sha256");
+    for (const entry of entries) {
+        cumulative.update(`${entry.relativePath}\t${entry.contentHash}\n`);
+    }
+    return {
+        algorithm: "sha256",
+        scopeVersion: 1,
+        scope,
+        value: `sha256:${cumulative.digest("hex")}`,
+        fileCount: entries.length,
+    };
+}
+/**
+ * Resolve a requested bin name or path to the absolute executable.
+ *
+ * Resolution strategy:
+ * 1. If `requested` is already an absolute path, use it directly.
+ * 2. If `requested` contains a path separator (/, \\), resolve against cwd.
+ * 3. Otherwise, search PATH directories (with optional PATHEXT on Windows).
+ * PATH misses fail closed; a bare command name is never invented relative to
+ * cwd when it was not actually found.
+ *
+ * After this call, the result must be treated as frozen — subsequent PATH
+ * mutations must not trigger a new resolution.
+ */
+export function resolveBinPaths(requested, resolvedAt, inputs) {
+    const cwd = inputs?.cwd ?? process.cwd();
+    const env = inputs?.env ?? process.env;
+    const osPlatform = inputs?.platform ?? platform();
+    if (path.isAbsolute(requested)) {
+        const entry = path.resolve(requested);
+        assertRegularFile(entry, requested);
+        return { requested, entry, realEntry: realpathSync(entry), resolvedAt };
+    }
+    // Path-like relative (contains / or \)
+    if (requested.includes("/") || requested.includes("\\")) {
+        const resolved = path.resolve(cwd, requested);
+        assertRegularFile(resolved, requested);
+        return { requested, entry: resolved, realEntry: realpathSync(resolved), resolvedAt };
+    }
+    // Search PATH
+    const pathEnv = env.PATH ?? env.Path ?? env.path ?? "";
+    const candidates = resolveFromPath(requested, pathEnv, osPlatform, env.PATHEXT ?? env.Pathext ?? env.pathext, cwd);
+    if (candidates.length > 0) {
+        const entry = candidates[0];
+        assertRegularFile(entry, requested);
+        return { requested, entry, realEntry: realpathSync(entry), resolvedAt };
+    }
+    throw new Error(`controller identity: cannot resolve executable ${JSON.stringify(requested)}`);
+}
+/**
+ * Resolve an npm-generated Windows `.cmd` shim to the referenced JavaScript
+ * bin entry within the same package.
+ *
+ * On Windows, npm creates `.cmd` wrappers like:
+ * ```
+ * @IF EXIST "%~dp0\node.exe" (
+ *   "%~dp0\node.exe"  "%~dp0\..\package\bin\cli.js" %*
+ * ) ELSE (
+ *   ...
+ * )
+ * ```
+ *
+ * This function parses the `.cmd` shim, extracts the JS script reference, and
+ * returns the resolved absolute path. Returns `undefined` if the shim cannot
+ * be parsed or the referenced script does not exist.
+ *
+ * Pure function: does not require a Windows host to execute.
+ */
+export function resolveCmdShim(shimPath) {
+    try {
+        const content = readFileSync(shimPath, "utf-8");
+        const matches = content.matchAll(/"(?:%dp0%|%~dp0)([^"]+\.(?:js|mjs|cjs))"/gi);
+        for (const match of matches) {
+            if (!match[1])
+                continue;
+            const windowsRelative = match[1].replace(/^[/\\]+/, "");
+            const scriptPath = path.resolve(path.dirname(shimPath), ...windowsRelative.split(/[\\/]+/));
+            try {
+                if (statSync(scriptPath).isFile())
+                    return realpathSync(scriptPath);
+            }
+            catch {
+                // Try the next JavaScript reference in the shim.
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Check whether a file is a JavaScript script (node shebang or JS extension). */
+export function isJavaScriptScript(filePath) {
+    try {
+        const header = readFileSync(filePath).subarray(0, 256).toString("utf-8").trimStart();
+        if (header.startsWith("#!/usr/bin/env node") || header.startsWith("#!/usr/bin/node") || header.startsWith("#!node")) {
+            return true;
+        }
+    }
+    catch {
+        // can't read — check by extension only
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    return ext === ".js" || ext === ".mjs" || ext === ".cjs" || ext === ".ts";
+}
+// ---------------------------------------------------------------------------
+// Package root resolution
+// ---------------------------------------------------------------------------
+/**
+ * Find the nearest package root by walking upward from `startDir` until a
+ * `package.json` is found.
+ *
+ * Returns `undefined` if no package.json was found at any ancestor (up to 100
+ * levels). Callers must treat `undefined` as a hard failure for identity
+ * construction.
+ */
+export function findPackageRoot(startDir) {
+    let current = path.resolve(startDir);
+    for (let i = 0; i < 100; i++) {
+        try {
+            statSync(path.join(current, "package.json"));
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// PATHEXT resolution
+// ---------------------------------------------------------------------------
+/**
+ * Expand a Windows executable name into candidate entries using PATHEXT.
+ *
+ * Example: on a system with `PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.JS`,
+ * resolving "loop-agent" produces:
+ *   ["loop-agent.COM", "loop-agent.EXE", "loop-agent.BAT", "loop-agent.CMD", ...]
+ *
+ * If the name already has an extension matching a PATHEXT entry, no expansion
+ * is performed and the name is used as-is.
+ *
+ * Pure function for testability.
+ */
+export function expandPathext(bin, pathext) {
+    if (!pathext)
+        return [bin];
+    const extensions = pathext
+        .split(";")
+        .map((ext) => ext.trim())
+        .filter(Boolean);
+    if (extensions.length === 0)
+        return [bin];
+    const binLower = bin.toLowerCase();
+    const alreadyHasExt = extensions.some((ext) => binLower.endsWith(ext.toLowerCase()));
+    if (alreadyHasExt)
+        return [bin];
+    return extensions.map((ext) => bin + ext);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function addRequiredFile(entries, absolutePath, relativeDir) {
+    const buffer = readFileSync(absolutePath);
+    const contentHash = createHash("sha256").update(buffer).digest("hex");
+    const relativePath = relativeDir
+        ? path.posix.join(relativeDir, path.basename(absolutePath))
+        : path.basename(absolutePath);
+    entries.push({ relativePath, contentHash });
+}
+function collectTree(entries, absoluteDir, relativeDir) {
+    let stats;
+    try {
+        stats = statSync(absoluteDir);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return; // optional scope directory does not exist
+        throw error;
+    }
+    if (!stats.isDirectory())
+        return;
+    const dirents = readdirSync(absoluteDir, { withFileTypes: true });
+    for (const dirent of dirents) {
+        const childAbs = path.join(absoluteDir, dirent.name);
+        const childRel = path.posix.join(relativeDir, dirent.name);
+        if (dirent.isFile()) {
+            addRequiredFile(entries, childAbs, relativeDir);
+        }
+        else if (dirent.isDirectory()) {
+            collectTree(entries, childAbs, childRel);
+        }
+        // Ignore symlinks, sockets, etc.
+    }
+}
+function isNotFound(error) {
+    return Boolean(error
+        && typeof error === "object"
+        && "code" in error
+        && error.code === "ENOENT");
+}
+// ---------------------------------------------------------------------------
+// Internal: PATH resolution (synchronous, no external dependencies)
+// ---------------------------------------------------------------------------
+function resolveFromPath(bin, pathEnv, osPlatform, pathext, cwd) {
+    const results = [];
+    const dirs = pathEnv.split(osPlatform === "win32" ? ";" : path.delimiter);
+    // On Windows, expand with PATHEXT
+    const isWindows = osPlatform === "win32";
+    for (const rawDir of dirs) {
+        const dir = rawDir || cwd;
+        if (isWindows) {
+            // Get PATHEXT from a well-known env var — in tests, passed via the
+            // merged env through ResolutionInputs. Here we fall back to process.env.
+            const candidates = expandPathext(bin, pathext ?? ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC");
+            for (const candidate of candidates) {
+                const filePath = path.join(dir, candidate);
+                try {
+                    if (!statSync(filePath).isFile())
+                        continue;
+                    results.push(filePath);
+                }
+                catch {
+                    // not found in this PATH entry
+                }
+            }
+        }
+        else {
+            const candidate = path.join(dir, bin);
+            try {
+                if (!statSync(candidate).isFile())
+                    continue;
+                results.push(candidate);
+            }
+            catch {
+                // not found in this PATH entry
+            }
+        }
+    }
+    return results;
+}
+function assertRegularFile(filePath, requested) {
+    try {
+        if (statSync(filePath).isFile())
+            return;
+    }
+    catch {
+        // Fall through to the stable error below.
+    }
+    throw new Error(`controller identity: resolved executable for ${JSON.stringify(requested)} is not a readable file: ${filePath}`);
+}

package/dist/{executors/cursor-executor.js → sidecars/cursor-prompt/executor.js}

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
-import { referencePathJoin } from "../shared/path-refs.js";
+import { referencePathJoin } from "../../shared/path-refs.js";
+import { truncateOutput, redactPromptForLog } from "../../shared/output-truncation.js";
 /** Cursor SDK account default (user → team → system). Override per call when needed. */
 export const DEFAULT_CURSOR_MODEL = "default";
 export const DEFAULT_CURSOR_TIMEOUT_MS = 1_800_000;
@@ -48,47 +48,11 @@ export function buildCursorPrompt(userTask, artifactOptions) {
         userTask,
     ].join("\n");
 }
-export function truncateOutput(text, maxBytes) {
-    if (!text)
-        return { text, truncated: false };
-    if (maxBytes <= 0) {
-        return { text: "\n...[truncated]", truncated: true };
-    }
-    if (Buffer.byteLength(text, "utf-8") <= maxBytes) {
-        return { text, truncated: false };
-    }
-    let low = 0;
-    let high = text.length;
-    while (low < high) {
-        const mid = Math.ceil((low + high) / 2);
-        if (Buffer.byteLength(text.slice(0, mid), "utf-8") <= maxBytes) {
-            low = mid;
-        }
-        else {
-            high = mid - 1;
-        }
-    }
-    let end = low;
-    // Avoid ending the prefix on a dangling UTF-16 high surrogate.
-    if (end > 0) {
-        const code = text.charCodeAt(end - 1);
-        if (code >= 0xd800 && code <= 0xdbff)
-            end -= 1;
-    }
-    return {
-        text: `${text.slice(0, end)}\n...[truncated]`,
-        truncated: true,
-    };
-}
 export function redactApiKey(text, apiKey) {
     if (!apiKey)
         return text;
     return text.split(apiKey).join("<redacted-api-key>");
 }
-export function redactPromptForLog(prompt) {
-    const hash = createHash("sha256").update(prompt).digest("hex").slice(0, 12);
-    return `<prompt sha256=${hash} len=${prompt.length}>`;
-}
 export function buildRedactedExecutorRecord(input) {
     const apiKey = input.apiKey ?? process.env.CURSOR_API_KEY;
     const stdout = truncateOutput(redactApiKey(input.result.stdout, apiKey), 2_000);
@@ -239,10 +203,6 @@ function applyTokenUsageToResult(result, usage) {
     }
 }
 export async function executeCursorTask(options) {
-    const { shouldUseCursorWorker, executeCursorTaskViaWorker } = await import("./cursor-worker-client.js");
-    if (shouldUseCursorWorker(options)) {
-        return executeCursorTaskViaWorker(options);
-    }
     const model = options.model ?? DEFAULT_CURSOR_MODEL;
     const timeoutMs = options.timeoutMs ?? DEFAULT_CURSOR_TIMEOUT_MS;
     const apiKey = options.apiKey ?? process.env.CURSOR_API_KEY;

package/dist/sidecars/cursor-prompt/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_CURSOR_MODEL, DEFAULT_CURSOR_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_IDLE_TIMEOUT_MS, WAIT_AFTER_STREAM_GRACE_MS, MAX_CURSOR_STDOUT_BYTES, MAX_CURSOR_STDERR_BYTES, buildCursorPrompt, buildArtifactPathPrompt, resolveArtifactWriteDir, buildRedactedExecutorRecord, buildCursorExecutorEnv, classifyCursorFailure, mapRunStatusToExecutionStatus, CursorTimeoutError, isCursorTimeoutError, withCursorTimeout, buildStreamIdleTimeoutMessage, bestEffortCancelRun, extractCursorTokenUsage, executeCursorTask, redactApiKey, } from "./executor.js";
+export { truncateOutput, redactPromptForLog, } from "../../shared/output-truncation.js";
+export { executeCursorPromptStream, } from "./stream.js";

package/dist/sidecars/cursor-prompt/stream.js

@@ -0,0 +1,121 @@
+import { bestEffortCancelRun, buildCursorPrompt, classifyCursorFailure, mapRunStatusToExecutionStatus, } from "./executor.js";
+async function createCursorStreamAgent(input) {
+    const { Agent } = await import("@cursor/sdk");
+    return Agent.create({
+        apiKey: input.apiKey,
+        name: "pi-cursor-prompt",
+        model: { id: input.model },
+        local: { cwd: input.cwd },
+    });
+}
+/**
+ * One-shot streaming path for cursor-prompt CLI. Loads @cursor/sdk only here.
+ */
+export async function executeCursorPromptStream(input) {
+    const apiKey = input.apiKey ?? process.env.CURSOR_API_KEY;
+    if (!apiKey?.trim()) {
+        return {
+            ok: false,
+            status: "failed",
+            failureCategory: "missing-api-key",
+            model: input.model,
+            durationMs: 0,
+            stdout: "",
+            stderr: "CURSOR_API_KEY environment variable is not set.",
+            details: { startupError: true },
+        };
+    }
+    const prompt = buildCursorPrompt(input.task, { runDir: input.runDir });
+    const startedAt = Date.now();
+    let timeoutHandle;
+    let agent;
+    let run;
+    let timedOut = false;
+    try {
+        agent = await (input.agentFactory ?? createCursorStreamAgent)({
+            apiKey,
+            cwd: input.cwd,
+            model: input.model,
+        });
+        const runPromise = (async () => {
+            run = await agent.send(prompt);
+            for await (const event of run.stream()) {
+                if (event.type === "assistant") {
+                    for (const block of event.message.content) {
+                        if (block.type === "text" && block.text) {
+                            input.callbacks?.onAssistantText?.(block.text);
+                        }
+                    }
+                }
+            }
+            return run.wait();
+        })();
+        const timeoutRace = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => resolve("timeout"), input.timeoutMs);
+        });
+        const raced = await Promise.race([
+            runPromise.then((value) => ({ kind: "done", value })),
+            timeoutRace.then(() => ({ kind: "timeout" })),
+        ]);
+        if (raced.kind === "timeout") {
+            timedOut = true;
+            await bestEffortCancelRun(run);
+            return {
+                ok: false,
+                status: "timeout",
+                failureCategory: "timeout",
+                model: input.model,
+                durationMs: Date.now() - startedAt,
+                stdout: "",
+                stderr: `Cursor execution timed out after ${input.timeoutMs}ms`,
+                details: { timedOut: true, timeoutKind: "total" },
+            };
+        }
+        const sdkResult = raced.value;
+        const runStatus = String(sdkResult.status ?? "");
+        const status = mapRunStatusToExecutionStatus(runStatus, false);
+        const ok = status === "completed";
+        return {
+            ok,
+            status,
+            failureCategory: ok
+                ? "success"
+                : classifyCursorFailure({ runStatus, stderr: "", stdout: "" }),
+            model: input.model,
+            durationMs: sdkResult.durationMs ?? Date.now() - startedAt,
+            stdout: "",
+            stderr: "",
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            status: "failed",
+            failureCategory: classifyCursorFailure({
+                startupError: message,
+                stderr: message,
+            }),
+            model: input.model,
+            durationMs: Date.now() - startedAt,
+            stdout: "",
+            stderr: message,
+            details: { startupError: true },
+        };
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        if (!timedOut && run?.status === "running") {
+            await bestEffortCancelRun(run);
+        }
+        if (agent) {
+            try {
+                await agent[Symbol.asyncDispose]();
+            }
+            catch {
+                // The one-shot result remains authoritative; disposal is best effort.
+            }
+        }
+    }
+}