@tea-agent/loop-agent 0.39.0-next.8 → 0.39.0

package/dist/worker/observe/node-input.js

@@ -2,7 +2,8 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { resolveDagNodeSkills } from "../../workflows/dag/skills.js";
-import { resolveDagNodePromptRedacted, resolveDagRunJson, } from "./dag-run-artifacts.js";
+import { resolveDagNodePromptRedacted, resolveDagRunArtifact, resolveDagRunJson, } from "./dag-run-artifacts.js";
+import { namedShellHandlers } from "./shell-handler-keys.js";
 export const NODE_INPUT_SCHEMA_VERSION = 1;
 export const NODE_INPUT_PREVIEW_MAX_BYTES = 64 * 1024;
 const SHELL_GATE_KEYS = [
@@ -33,6 +34,7 @@ function unavailableBody(dagRunId, nodeId, reason, warnings = []) {
         executorInput: null,
         boundaries: null,
         promptFingerprint: null,
+        piExtensionRunFacts: null,
         warnings,
     };
 }
@@ -137,7 +139,7 @@ function resolveModelHint(spec, task) {
     }
     return null;
 }
-function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warnings) {
+function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, piExtensionRunFacts, warnings) {
     const defaults = spec.defaults && typeof spec.defaults === "object"
         ? spec.defaults
         : undefined;
@@ -216,6 +218,7 @@ function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warni
                 : null,
             failFast: typeof shellRaw.failFast === "boolean" ? shellRaw.failFast : null,
             gates: shellGateNames(shellRaw),
+            handlers: namedShellHandlers(shellRaw),
         }
         : null;
     const staticPreview = staticRaw && typeof staticRaw.resultMarkdown === "string"
@@ -268,6 +271,7 @@ function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warni
             kind,
             skills,
             modelHint: resolveModelHint(spec, task),
+            piExtensions: redactStringList(task.piExtensions),
             shell,
             static: staticBlock,
         },
@@ -284,9 +288,72 @@ function projectTask(dagRunId, nodeId, lifecycle, spec, task, fingerprint, warni
                 : null,
         },
         promptFingerprint: fingerprint,
+        piExtensionRunFacts,
         warnings,
     };
 }
+/**
+ * Load run-time Pi extension facts from <node>/pi-extensions.json (plan
+ * 2026-08-22 R2). Returns null when the node declares no piExtensions
+ * (no expected artifact). Never throws: unreadable/corrupt artifacts degrade
+ * to parseError stubs so the node-input endpoint stays 200.
+ */
+async function loadPiExtensionRunFacts(repoRoot, dagRunId, nodeId, declared, warnings) {
+    if (declared.length === 0)
+        return null;
+    const artifact = path.posix.join(nodeId, "pi-extensions.json");
+    const resolved = resolveDagRunArtifact(repoRoot, dagRunId, [
+        nodeId,
+        "pi-extensions.json",
+    ]);
+    if (!resolved.ok) {
+        if (resolved.reason === "ambiguous") {
+            warnings.push("Ambiguous pi-extensions.json lifecycle copies.");
+        }
+        return {
+            artifact,
+            exists: false,
+            requested: [...declared],
+            resolved: [],
+            missing: [],
+        };
+    }
+    const empty = {
+        artifact,
+        exists: false,
+        requested: [...declared],
+        resolved: [],
+        missing: [],
+    };
+    try {
+        const raw = JSON.parse(await readFile(resolved.result.absolutePath, "utf-8"));
+        const resolvedList = Array.isArray(raw.resolved) ? raw.resolved : [];
+        const missingList = Array.isArray(raw.missing) ? raw.missing : [];
+        const projected = resolvedList
+            .filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry))
+            .map((entry) => ({
+            id: redactSecrets(String(entry.id ?? "")),
+            packageName: redactSecrets(String(entry.packageName ?? "")),
+            version: redactSecrets(String(entry.version ?? "")),
+        }));
+        const missingProjected = missingList
+            .filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry))
+            .map((entry) => ({
+            id: redactSecrets(String(entry.id ?? "")),
+            reason: redactSecrets(String(entry.reason ?? "")),
+        }));
+        return {
+            artifact,
+            exists: true,
+            requested: redactStringList(raw.requested ?? declared),
+            resolved: projected,
+            missing: missingProjected,
+        };
+    }
+    catch {
+        return { ...empty, parseError: "read-failed" };
+    }
+}
 async function loadPromptFingerprint(repoRoot, dagRunId, nodeId, warnings) {
     const resolved = resolveDagNodePromptRedacted(repoRoot, dagRunId, nodeId);
     if (!resolved.ok) {
@@ -415,8 +482,12 @@ export async function buildDagNodeInput(repoRoot, dagRunId, nodeId) {
     }
     const warnings = [];
     const fingerprint = await loadPromptFingerprint(repoRoot, dagRunId, nodeId, warnings);
+    const declaredPiExtensions = Array.isArray(task.piExtensions)
+        ? task.piExtensions.filter((item) => typeof item === "string")
+        : [];
+    const piExtensionRunFacts = await loadPiExtensionRunFacts(repoRoot, dagRunId, nodeId, declaredPiExtensions, warnings);
     // Reject unknown nested leakage by projecting only through allowlist helpers.
-    const body = projectTask(dagRunId, nodeId, runResolved.result.lifecycle, spec, task, fingerprint, warnings);
+    const body = projectTask(dagRunId, nodeId, runResolved.result.lifecycle, spec, task, fingerprint, piExtensionRunFacts, warnings);
     // Defense-in-depth: ensure raw task never sneaks in.
     if ("task" in body) {
         return {

package/dist/worker/observe/node-process.js

@@ -0,0 +1,377 @@
+import { readFile } from "node:fs/promises";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
+import { isSafeObservabilityIdentifier } from "../observability/event-store.js";
+import { parseExecutionOutputKey, } from "./dag-node-execution-output.js";
+import { resolveDagRunArtifact, resolveDagRunJson, } from "./dag-run-artifacts.js";
+import { namedShellHandlers } from "./shell-handler-keys.js";
+export const NODE_PROCESS_SCHEMA_VERSION = 1;
+export const NODE_PROCESS_FIELD_MAX_BYTES = 16 * 1024;
+function boundField(value) {
+    if (value == null || value === "")
+        return { text: null, truncated: false };
+    const redacted = redactSecrets(value);
+    const truncated = truncateUtf8Preview(redacted, NODE_PROCESS_FIELD_MAX_BYTES);
+    return {
+        text: truncated,
+        truncated: truncated !== redacted,
+    };
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function asBoolean(value) {
+    return value === true;
+}
+async function readJsonArtifact(repoRoot, dagRunId, segments) {
+    const resolved = resolveDagRunArtifact(repoRoot, dagRunId, segments);
+    if (!resolved.ok)
+        return null;
+    try {
+        const raw = await readFile(resolved.result.absolutePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return asRecord(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+async function readTextArtifact(repoRoot, dagRunId, segments) {
+    const resolved = resolveDagRunArtifact(repoRoot, dagRunId, segments);
+    if (!resolved.ok)
+        return { text: null, truncated: false };
+    try {
+        const raw = await readFile(resolved.result.absolutePath, "utf8");
+        return boundField(raw);
+    }
+    catch {
+        return { text: null, truncated: false };
+    }
+}
+function emptyBody(dagRunId, nodeId, kind, emptyReason, extras = {}) {
+    return {
+        schemaVersion: NODE_PROCESS_SCHEMA_VERSION,
+        dagRunId,
+        nodeId,
+        kind,
+        executor: extras.executor ?? null,
+        handler: extras.handler ?? null,
+        emptyReason,
+        key: extras.key ?? null,
+        commands: extras.commands ?? [],
+        steps: extras.steps ?? [],
+    };
+}
+function classifyKind(task) {
+    const executor = asString(task.executor);
+    const shell = asRecord(task.shell);
+    const handlers = namedShellHandlers(shell);
+    const handler = handlers[0] ?? null;
+    const commands = shell?.commands;
+    const commandsDeclared = Array.isArray(commands) &&
+        commands.some((item) => typeof item === "string" && item.trim());
+    if (executor === "static" || task.static) {
+        return { kind: "static", executor: executor ?? "static", handler, commandsDeclared };
+    }
+    if (executor === "shell" || shell) {
+        if (commandsDeclared) {
+            return { kind: "shell-commands", executor: executor ?? "shell", handler, commandsDeclared };
+        }
+        if (handler) {
+            return { kind: "shell-preset", executor: executor ?? "shell", handler, commandsDeclared };
+        }
+        return { kind: "shell-commands", executor: executor ?? "shell", handler, commandsDeclared };
+    }
+    return {
+        kind: "pi-session",
+        executor: executor ?? "pi",
+        handler,
+        commandsDeclared,
+    };
+}
+function receiptAttemptSegments(nodeId, parsed) {
+    if (parsed?.kind === "attempt") {
+        return [nodeId, `attempt-${parsed.index}`, "shell-command-receipt.json"];
+    }
+    return [nodeId, "shell-command-receipt.json"];
+}
+async function loadShellCommands(repoRoot, dagRunId, nodeId, parsed) {
+    const preferred = await readJsonArtifact(repoRoot, dagRunId, receiptAttemptSegments(nodeId, parsed));
+    const receipt = preferred ??
+        (parsed
+            ? await readJsonArtifact(repoRoot, dagRunId, [
+                nodeId,
+                "shell-command-receipt.json",
+            ])
+            : null);
+    if (!receipt)
+        return null;
+    const rawCommands = Array.isArray(receipt.commands) ? receipt.commands : [];
+    const commands = [];
+    for (let i = 0; i < rawCommands.length; i += 1) {
+        const entry = asRecord(rawCommands[i]) ?? {};
+        const stdout = await readTextArtifact(repoRoot, dagRunId, [
+            nodeId,
+            "commands",
+            `${i + 1}.stdout.txt`,
+        ]);
+        const stderr = await readTextArtifact(repoRoot, dagRunId, [
+            nodeId,
+            "commands",
+            `${i + 1}.stderr.txt`,
+        ]);
+        const commandBound = boundField(asString(entry.command) ?? "");
+        commands.push({
+            index: i + 1,
+            command: commandBound.text ?? "(command)",
+            ok: asBoolean(entry.ok),
+            exitCode: asNumber(entry.exitCode),
+            failureCategory: asString(entry.failureCategory),
+            startedAt: asString(entry.startedAt),
+            finishedAt: asString(entry.finishedAt),
+            durationMs: asNumber(entry.wallDurationMs) ??
+                asNumber(entry.executionDurationMs) ??
+                null,
+            reused: asBoolean(entry.reused),
+            stdout: stdout.text,
+            stderr: stderr.text,
+            truncated: commandBound.truncated || stdout.truncated || stderr.truncated,
+        });
+    }
+    return commands;
+}
+function handlerLabel(handler) {
+    if (handler === "frontendBrowserToolPreflight")
+        return "浏览器工具能力探测";
+    if (handler === "frontendTestStandardScenarios")
+        return "标准场景物化";
+    if (handler === "frontendTestEnvironmentProbe")
+        return "前端环境探测";
+    if (handler === "frontendTestCaseChecklist")
+        return "用例清单校验";
+    if (handler === "frontendTestCaseManifest")
+        return "用例清单物化";
+    if (handler === "frontendTestEvidenceValidation")
+        return "证据校验";
+    if (handler === "frontendTestResultFinalize")
+        return "结果定稿";
+    if (handler === "frontendTestReports" || handler === "frontendTestL5Report" || handler === "frontendTestHtmlReport") {
+        return "测试报告";
+    }
+    if (handler === "frontendPrewriteGate")
+        return "前端预写门禁";
+    if (handler === "finalWriteSetApprovalGate")
+        return "writeSet 终态批准";
+    return handler;
+}
+async function loadPresetSteps(repoRoot, dagRunId, nodeId, handler, parsed) {
+    const written = await readJsonArtifact(repoRoot, dagRunId, [
+        nodeId,
+        "process-receipt.json",
+    ]);
+    if (written && Array.isArray(written.steps)) {
+        return written.steps.flatMap((item, index) => {
+            const step = asRecord(item);
+            if (!step)
+                return [];
+            const detail = boundField(asString(step.detail));
+            return [
+                {
+                    id: asString(step.id) ?? `step-${index + 1}`,
+                    label: asString(step.label) ?? handlerLabel(handler ?? "preset"),
+                    ok: asBoolean(step.ok),
+                    detail: detail.text,
+                    durationMs: asNumber(step.durationMs),
+                    truncated: detail.truncated,
+                },
+            ];
+        });
+    }
+    const capability = await readJsonArtifact(repoRoot, dagRunId, [
+        nodeId,
+        "frontend-browser-capability.json",
+    ]);
+    if (capability && handler === "frontendBrowserToolPreflight") {
+        const detail = boundField(JSON.stringify(capability, null, 2));
+        return [
+            {
+                id: "capability",
+                label: handlerLabel(handler),
+                ok: asString(capability.status) !== "failed",
+                detail: detail.text,
+                durationMs: null,
+                truncated: detail.truncated,
+            },
+        ];
+    }
+    const attemptIndex = parsed?.kind === "attempt" ? parsed.index : 1;
+    const attempt = await readJsonArtifact(repoRoot, dagRunId, [
+        nodeId,
+        `attempt-${attemptIndex}.json`,
+    ]);
+    if (attempt) {
+        const ok = asBoolean(attempt.ok);
+        const detail = boundField(ok
+            ? (asString(attempt.stdout) ?? asString(attempt.assistantText))
+            : (asString(attempt.stderr) ?? asString(attempt.stdout)));
+        return [
+            {
+                id: "run",
+                label: handlerLabel(handler ?? "preset"),
+                ok,
+                detail: detail.text,
+                durationMs: asNumber(attempt.durationMs),
+                truncated: detail.truncated,
+            },
+        ];
+    }
+    return [];
+}
+export async function loadDagNodeProcess(repoRoot, dagRunId, nodeId, rawKey) {
+    if (!isSafeObservabilityIdentifier(dagRunId) ||
+        !isSafeObservabilityIdentifier(nodeId)) {
+        return {
+            status: 400,
+            body: { error: "Invalid dag run or node identifier", reason: "invalid-id" },
+        };
+    }
+    let parsedKey = null;
+    if (rawKey != null && String(rawKey).trim() !== "") {
+        const parsed = parseExecutionOutputKey(rawKey);
+        if (!parsed.ok) {
+            return {
+                status: 400,
+                body: {
+                    error: "Invalid execution key (expected attempt-N or pass-N)",
+                    reason: "invalid-key",
+                },
+            };
+        }
+        parsedKey = parsed;
+    }
+    const runResolved = resolveDagRunJson(repoRoot, dagRunId);
+    if (!runResolved.ok) {
+        if (runResolved.reason === "invalid-id") {
+            return {
+                status: 400,
+                body: { error: "Invalid dag run or node identifier", reason: "invalid-id" },
+            };
+        }
+        if (runResolved.reason === "ambiguous") {
+            return {
+                status: 409,
+                body: { error: "Ambiguous dag run lifecycle", reason: "ambiguous" },
+            };
+        }
+        return {
+            status: 404,
+            body: { error: "DAG run not found", reason: "not-found" },
+        };
+    }
+    let spec = {};
+    try {
+        const raw = JSON.parse(await readFile(runResolved.result.absolutePath, "utf8"));
+        spec = asRecord(raw) ?? {};
+    }
+    catch {
+        return {
+            status: 404,
+            body: { error: "run.json is unreadable", reason: "not-found" },
+        };
+    }
+    const tasks = Array.isArray(spec.tasks) ? spec.tasks : [];
+    const task = tasks
+        .map((item) => asRecord(item))
+        .find((item) => item && asString(item.id) === nodeId);
+    if (!task) {
+        return {
+            status: 200,
+            body: emptyBody(dagRunId, nodeId, "none", "not-executed"),
+        };
+    }
+    const classified = classifyKind(task);
+    const key = parsedKey?.key ?? null;
+    if (classified.kind === "pi-session") {
+        return {
+            status: 200,
+            body: emptyBody(dagRunId, nodeId, "pi-session", "pi-session", {
+                executor: classified.executor,
+                key,
+            }),
+        };
+    }
+    if (classified.kind === "static") {
+        return {
+            status: 200,
+            body: emptyBody(dagRunId, nodeId, "static", "static-no-process", {
+                executor: classified.executor,
+                key,
+            }),
+        };
+    }
+    if (classified.kind === "shell-commands" || classified.kind === "shell-preset") {
+        const commands = await loadShellCommands(repoRoot, dagRunId, nodeId, parsedKey);
+        if (commands && commands.length > 0) {
+            return {
+                status: 200,
+                body: {
+                    schemaVersion: NODE_PROCESS_SCHEMA_VERSION,
+                    dagRunId,
+                    nodeId,
+                    kind: "shell-commands",
+                    executor: classified.executor,
+                    handler: classified.handler,
+                    emptyReason: null,
+                    key,
+                    commands,
+                    steps: [],
+                },
+            };
+        }
+        if (classified.handler || classified.kind === "shell-preset") {
+            const steps = await loadPresetSteps(repoRoot, dagRunId, nodeId, classified.handler, parsedKey);
+            if (steps.length > 0) {
+                return {
+                    status: 200,
+                    body: {
+                        schemaVersion: NODE_PROCESS_SCHEMA_VERSION,
+                        dagRunId,
+                        nodeId,
+                        kind: "shell-preset",
+                        executor: classified.executor,
+                        handler: classified.handler,
+                        emptyReason: null,
+                        key,
+                        commands: [],
+                        steps,
+                    },
+                };
+            }
+        }
+        return {
+            status: 200,
+            body: emptyBody(dagRunId, nodeId, classified.kind, classified.kind === "shell-preset"
+                ? "shell-preset-pending"
+                : "shell-receipt-missing", {
+                executor: classified.executor,
+                handler: classified.handler,
+                key,
+            }),
+        };
+    }
+    return {
+        status: 200,
+        body: emptyBody(dagRunId, nodeId, "none", "not-executed", {
+            executor: classified.executor,
+            handler: classified.handler,
+            key,
+        }),
+    };
+}

package/dist/worker/observe/routes.js

@@ -16,6 +16,7 @@ import { isAllowedArtifactTextPath, resolveArtifactPath, resolveRepoFilePreview,
 import { extractSpecEvidence, extractSpecReadContent, } from "./spec-evidence.js";
 import { buildDagNodeInput } from "./node-input.js";
 import { loadDagNodeExecutionOutput } from "./dag-node-execution-output.js";
+import { loadDagNodeProcess } from "./node-process.js";
 import { buildObserveHealthV1 } from "./health.js";
 import { buildNightJobDetail, buildNightJobsDoctor, buildNightJobsList, buildNightJobsMorning, } from "./night-jobs.js";
 const ARTIFACT_PREVIEW_MAX_BYTES = 64 * 1024;
@@ -100,6 +101,11 @@ export const ROUTES = [
         pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/execution-output$/,
         handler: handleDagNodeExecutionOutput,
     },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/process$/,
+        handler: handleDagNodeProcess,
+    },
     {
         method: "GET",
         pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/spec-evidence$/,
@@ -221,14 +227,23 @@ export async function serveObserveStatic(req, res, staticDir, options = {}) {
         sendJson(res, 404, { error: "Not found" });
         return;
     }
-    const content = await readFile(resolvedFile);
+    let content = await readFile(resolvedFile);
     const contentType = contentTypeFor(pathname);
-    res.writeHead(200, {
+    const headers = {
         "Content-Type": contentType,
         "Content-Length": content.byteLength,
         "X-Content-Type-Options": "nosniff",
         "X-Frame-Options": "SAMEORIGIN",
-    });
+    };
+    if (contentType.startsWith("text/html") && options.htmlEnhancer) {
+        const enhanced = options.htmlEnhancer(Buffer.from(content));
+        content = enhanced.content;
+        headers["Content-Length"] = content.byteLength;
+        if (enhanced.setCookie) {
+            headers["Set-Cookie"] = enhanced.setCookie;
+        }
+    }
+    res.writeHead(200, headers);
     res.end(content);
 }
 async function handleHealth(_req, res, _match, ctx) {
@@ -570,6 +585,24 @@ async function handleDagNodeExecutionOutput(_req, res, match, ctx) {
     const result = await loadDagNodeExecutionOutput(ctx.repoRoot, dagRunId, nodeId, key);
     sendJson(res, result.status, result.body);
 }
+async function handleDagNodeProcess(_req, res, match, ctx) {
+    const dagRunId = match.params.id;
+    const nodeId = match.params.sub;
+    if (!isSafeObservabilityIdentifier(dagRunId) ||
+        !isSafeObservabilityIdentifier(nodeId)) {
+        sendJson(res, 400, { error: "Invalid dag run or node identifier" });
+        return;
+    }
+    if (match.query.has("path") || match.query.has("artifactPath")) {
+        sendJson(res, 400, {
+            error: "Artifact path is not accepted; use optional key=attempt-N|pass-N",
+            reason: "path-not-allowed",
+        });
+        return;
+    }
+    const result = await loadDagNodeProcess(ctx.repoRoot, dagRunId, nodeId, match.query.get("key"));
+    sendJson(res, result.status, result.body);
+}
 async function handleDagNodeSessionEvents(_req, res, match, ctx) {
     const dagRunId = match.params.id;
     const nodeId = match.params.sub;

package/dist/worker/observe/shell-handler-keys.js

@@ -0,0 +1,34 @@
+/**
+ * Allowlist of in-process shell handlers (preset/gate flags on task.shell).
+ * Observe projects these names; the executor writes process receipts for them.
+ */
+export const SHELL_NAMED_HANDLER_KEYS = [
+    "verdictGate",
+    "projectGovernanceGate",
+    "requirementCoverageGate",
+    "jsonArtifactGate",
+    "frontendPrewriteGate",
+    "frontendLintBaseline",
+    "frontendVerificationBundle",
+    "frontendReviewContext",
+    "frontendTestCaseChecklist",
+    "frontendBrowserToolPreflight",
+    "frontendTestStandardScenarios",
+    "frontendTestEnvironmentProbe",
+    "frontendTestEvidenceValidation",
+    "finalWriteSetApprovalGate",
+    "frontendTestL5Report",
+    "frontendTestHtmlReport",
+    "frontendTestCaseManifest",
+    "frontendTestResultFinalize",
+    "frontendTestReports",
+    "backendTestPipeline",
+    "jacocoCoverage",
+    "verifyEvidence",
+    "repairArtifactGate",
+];
+export function namedShellHandlers(shell) {
+    if (!shell)
+        return [];
+    return SHELL_NAMED_HANDLER_KEYS.filter((key) => shell[key] != null);
+}

package/dist/worker/observe/static/api.js

@@ -77,6 +77,14 @@ export async function fetchDagNodeInput(runId, nodeId) {
 	return fetchJsonResult(url);
 }
 
+export async function fetchDagNodeProcess(runId, nodeId, key) {
+	const params = new URLSearchParams();
+	if (key) params.set("key", String(key));
+	const qs = params.toString();
+	const url = `/api/dag-runs/${encodeURIComponent(runId)}/nodes/${encodeURIComponent(nodeId)}/process${qs ? `?${qs}` : ""}`;
+	return fetchJsonResult(url);
+}
+
 /**
  * Fetch a spec-evidence file preview (binding source or successful read).
  * Resolves to the parsed JSON body, or throws an Error carrying the HTTP
@@ -104,6 +112,64 @@ export function artifactUrl(artifactPath) {
 	return `/api/artifacts?path=${encodeURIComponent(artifactPath)}&tail=200`;
 }
 
+/**
+ * Experimental (prompt-override rerun only): POST one allowlisted operator
+ * action through the Console mutation gate using the SCOPED inspect token
+ * (window.__INSPECT_MUTATION_TOKEN__). The server injects it into /inspect
+ * HTML only when HARNESS_DAG_RERUN_PROMPT_OVERRIDE is enabled, and it only
+ * authorizes dagRerunPlan / dagRerun — never general Console mutations.
+ * Absent token → the call is not attempted.
+ */
+export async function postOperatorAction(action, actionParams = {}) {
+	const token = globalThis.__INSPECT_MUTATION_TOKEN__;
+	if (!token) {
+		return {
+			ok: false,
+			status: 0,
+			body: { error: { code: "PROMPT_OVERRIDE_DISABLED", message: "提示词重启未启用（服务端未注入确认 token）" } },
+		};
+	}
+	try {
+		const res = await fetch("/api/operator/v1/operations", {
+			method: "POST",
+			credentials: "same-origin",
+			headers: {
+				"Content-Type": "application/json",
+				"x-loop-console-confirmation": token,
+			},
+			body: JSON.stringify({ action, actionParams }),
+		});
+		let body = null;
+		try {
+			body = await res.json();
+		} catch {
+			body = null;
+		}
+		return { ok: res.ok, status: res.status, body };
+	} catch {
+		return { ok: false, status: 0, body: null };
+	}
+}
+
+/** Poll a Console operation snapshot (read-only GET). */
+export async function fetchOperatorOperation(operationId) {
+	try {
+		const res = await fetch(
+			`/api/operator/v1/operations/${encodeURIComponent(operationId)}`,
+			{ credentials: "same-origin" },
+		);
+		let body = null;
+		try {
+			body = await res.json();
+		} catch {
+			body = null;
+		}
+		return { ok: res.ok, status: res.status, body };
+	} catch {
+		return { ok: false, status: 0, body: null };
+	}
+}
+
 export function parseArtifactPreviewResponse(text) {
 	const parsed = JSON.parse(text);
 	if (!parsed || typeof parsed.content !== "string") {