@tea-agent/loop-agent 0.37.0 → 0.37.1-beta.0

package/dist/workflows/dag/interrupt-request.js

@@ -1,559 +0,0 @@
-import { watch } from "node:fs";
-import { mkdir, readFile } from "node:fs/promises";
-import { hostname as localHostname } from "node:os";
-import path from "node:path";
-import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
-import { assessDagRunLiveness, getDagRunDir, locateDagRun, readDagRunState, } from "./lifecycle.js";
-export const INTERRUPT_ARTIFACT_REL = path.posix.join(".runtime", "interrupt.json");
-export const INTERRUPT_REASON_CODES = [
-    "requirements-changed",
-    "suspected-runaway",
-    "resource-protection",
-    "operator-request",
-    "other",
-];
-export const INTERRUPT_ERROR_CODES = [
-    "RUN_NOT_ACTIVE",
-    "RUN_NOT_CONSOLE_OWNED",
-    "RUNNER_IDENTITY_MISMATCH",
-    "INTERRUPT_ALREADY_PENDING",
-    "RUN_ALREADY_TERMINAL",
-    "INTERRUPT_NEEDS_RECONCILE",
-    "INVALID_INPUT",
-];
-export const INTERRUPT_ERROR_MESSAGES = {
-    RUN_NOT_ACTIVE: "这次运行不在本机活动目录，或已经不是 running，不能协作中止。",
-    RUN_NOT_CONSOLE_OWNED: "此运行不由当前 Console 持有，暂不支持协作中止。请用 Doctor / 报告查看。",
-    RUNNER_IDENTITY_MISMATCH: "运行身份已变化，不能中止这份过期请求。请刷新资格后再试。",
-    INTERRUPT_ALREADY_PENDING: "已有一条中止请求等待结算。请等待当前节点安全收敛，或用 Doctor 对账。",
-    RUN_ALREADY_TERMINAL: "运行已经结束，没有可中止的活 runner。",
-    INTERRUPT_NEEDS_RECONCILE: "中止请求已登记，但无法确认 runner 已处理。请用 Doctor 对账，不要当成已经中止。",
-    INVALID_INPUT: "中止请求参数不完整或格式不正确。",
-};
-export class DagInterruptError extends Error {
-    code;
-    constructor(code, message) {
-        super(message ?? INTERRUPT_ERROR_MESSAGES[code]);
-        this.name = "DagInterruptError";
-        this.code = code;
-    }
-}
-export function interruptArtifactPath(runDir) {
-    return path.join(runDir, ".runtime", "interrupt.json");
-}
-export function isInterruptReasonCode(value) {
-    return INTERRUPT_REASON_CODES.includes(value);
-}
-export function normalizeInterruptReasonDetail(raw) {
-    const detail = raw.trim();
-    if (detail.length < 10 || detail.length > 500) {
-        throw new DagInterruptError("INVALID_INPUT", "reasonDetail 去首尾空白后必须是 10–500 个字符，且不能是无意义占位。");
-    }
-    return detail;
-}
-export function runnerIdentityFromState(state) {
-    const runner = state.runner;
-    const fingerprint = state.controllerIdentityRef?.packageFingerprint?.trim();
-    if (!runner || !fingerprint)
-        return undefined;
-    if (!Number.isInteger(runner.pid) ||
-        runner.pid <= 0 ||
-        !runner.hostname?.trim() ||
-        !runner.startedAt?.trim()) {
-        return undefined;
-    }
-    return {
-        pid: runner.pid,
-        hostname: runner.hostname,
-        startedAt: runner.startedAt,
-        controllerFingerprint: fingerprint,
-    };
-}
-export function runnerIdentitiesMatch(left, right) {
-    return (left.pid === right.pid &&
-        left.hostname === right.hostname &&
-        left.startedAt === right.startedAt &&
-        left.controllerFingerprint === right.controllerFingerprint);
-}
-export function parseInterruptRequest(raw) {
-    if (!raw || typeof raw !== "object") {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json 不是对象");
-    }
-    const rec = raw;
-    if (rec.schemaVersion !== 1) {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json schemaVersion 必须为 1");
-    }
-    const identity = rec.expectedRunnerIdentity;
-    if (!identity || typeof identity !== "object") {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json 缺少 expectedRunnerIdentity");
-    }
-    const ident = identity;
-    const reasonCode = String(rec.reasonCode ?? "");
-    if (!isInterruptReasonCode(reasonCode)) {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json reasonCode 非法");
-    }
-    const status = String(rec.status ?? "");
-    if (status !== "requested" &&
-        status !== "acknowledged" &&
-        status !== "settled" &&
-        status !== "needs-reconcile") {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json status 非法");
-    }
-    const requestedBy = rec.requestedBy;
-    if (!requestedBy || typeof requestedBy !== "object") {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json 缺少 requestedBy");
-    }
-    const by = requestedBy;
-    const source = by.source === "cli" ? "cli" : "operator-console";
-    const pid = Number(ident.pid);
-    if (!Number.isInteger(pid) || pid <= 0) {
-        throw new DagInterruptError("INVALID_INPUT", "interrupt.json expectedRunnerIdentity.pid 非法");
-    }
-    return {
-        schemaVersion: 1,
-        revision: Number(rec.revision) || 1,
-        requestId: String(rec.requestId ?? ""),
-        runId: String(rec.runId ?? ""),
-        targetOperationId: String(rec.targetOperationId ?? ""),
-        reasonCode,
-        reasonDetail: String(rec.reasonDetail ?? ""),
-        requestedAt: String(rec.requestedAt ?? ""),
-        requestedBy: {
-            source,
-            ...(typeof by.operatorSessionId === "string" && by.operatorSessionId.trim()
-                ? { operatorSessionId: by.operatorSessionId.trim() }
-                : {}),
-        },
-        expectedRunnerIdentity: {
-            pid,
-            hostname: String(ident.hostname ?? ""),
-            startedAt: String(ident.startedAt ?? ""),
-            controllerFingerprint: String(ident.controllerFingerprint ?? ""),
-        },
-        status,
-        ...(typeof rec.acknowledgedAt === "string"
-            ? { acknowledgedAt: rec.acknowledgedAt }
-            : {}),
-        ...(typeof rec.settledAt === "string" ? { settledAt: rec.settledAt } : {}),
-        ...(typeof rec.outcome === "string" ? { outcome: rec.outcome } : {}),
-    };
-}
-export async function readInterruptRequest(runDir) {
-    try {
-        const raw = JSON.parse(await readFile(interruptArtifactPath(runDir), "utf-8"));
-        return parseInterruptRequest(raw);
-    }
-    catch (error) {
-        if (error &&
-            typeof error === "object" &&
-            "code" in error &&
-            error.code === "ENOENT") {
-            return undefined;
-        }
-        if (error instanceof DagInterruptError)
-            throw error;
-        throw new DagInterruptError("INVALID_INPUT", `无法读取 interrupt.json: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-async function writeInterruptRequest(runDir, request) {
-    await mkdir(path.join(runDir, ".runtime"), { recursive: true });
-    await writeJsonAtomic(interruptArtifactPath(runDir), request);
-}
-function requestPayloadKey(request) {
-    const ident = request.expectedRunnerIdentity;
-    return [
-        request.runId,
-        request.targetOperationId,
-        request.reasonCode,
-        request.reasonDetail,
-        ident.pid,
-        ident.hostname,
-        ident.startedAt,
-        ident.controllerFingerprint,
-    ].join("\0");
-}
-function assertKernelRunEligible(input) {
-    if (input.lifecycle !== "active") {
-        if (input.lifecycle === "completed" ||
-            input.lifecycle === "paused" ||
-            isTerminalRunStatus(input.state.status)) {
-            throw new DagInterruptError("RUN_ALREADY_TERMINAL");
-        }
-        throw new DagInterruptError("RUN_NOT_ACTIVE");
-    }
-    if (input.state.status !== "running") {
-        if (isTerminalRunStatus(input.state.status) || input.state.status === "paused") {
-            throw new DagInterruptError("RUN_ALREADY_TERMINAL");
-        }
-        throw new DagInterruptError("RUN_NOT_ACTIVE");
-    }
-    if (input.state.workerAssociation) {
-        throw new DagInterruptError("RUN_NOT_CONSOLE_OWNED");
-    }
-    const live = runnerIdentityFromState(input.state);
-    if (!live || !runnerIdentitiesMatch(live, input.expected)) {
-        throw new DagInterruptError("RUNNER_IDENTITY_MISMATCH");
-    }
-    const liveness = assessDagRunLiveness({ state: input.state });
-    if (liveness.status === "orphaned" || liveness.status === "unknown-host") {
-        throw new DagInterruptError("RUN_NOT_ACTIVE");
-    }
-}
-function isTerminalRunStatus(status) {
-    return (status === "finished" ||
-        status === "failed" ||
-        status === "partial_failed" ||
-        status === "superseded" ||
-        status === "abandoned");
-}
-export async function requestDagInterrupt(input) {
-    const requestId = input.requestId.trim();
-    const targetOperationId = input.targetOperationId.trim();
-    const runId = input.runId.trim();
-    if (!requestId || !targetOperationId || !runId) {
-        throw new DagInterruptError("INVALID_INPUT");
-    }
-    const reasonDetail = normalizeInterruptReasonDetail(input.reasonDetail);
-    const located = await locateDagRun(input.cwd, runId);
-    if (!located) {
-        throw new DagInterruptError("RUN_NOT_ACTIVE");
-    }
-    const state = await readDagRunState(located.runDir);
-    if (state.runId !== runId) {
-        throw new DagInterruptError("RUNNER_IDENTITY_MISMATCH");
-    }
-    assertKernelRunEligible({
-        lifecycle: located.lifecycle,
-        state,
-        expected: input.expectedRunnerIdentity,
-    });
-    const existing = await readInterruptRequest(located.runDir);
-    const next = {
-        schemaVersion: 1,
-        revision: (existing?.revision ?? 0) + 1,
-        requestId,
-        runId,
-        targetOperationId,
-        reasonCode: input.reasonCode,
-        reasonDetail,
-        requestedAt: (input.now ?? new Date()).toISOString(),
-        requestedBy: input.requestedBy ?? { source: "cli" },
-        expectedRunnerIdentity: input.expectedRunnerIdentity,
-        status: "requested",
-    };
-    if (existing) {
-        if (existing.status === "requested" ||
-            existing.status === "acknowledged") {
-            if (existing.requestId === requestId &&
-                requestPayloadKey(existing) === requestPayloadKey(next)) {
-                return {
-                    ok: true,
-                    interruptStatus: "requested",
-                    request: existing,
-                    runDir: located.runDir,
-                    lifecycle: located.lifecycle,
-                };
-            }
-            if (existing.requestId === requestId) {
-                throw new DagInterruptError("INVALID_INPUT", "同一 requestId 不能绑定不同的中止内容。");
-            }
-            throw new DagInterruptError("INTERRUPT_ALREADY_PENDING");
-        }
-        if (existing.status === "needs-reconcile") {
-            throw new DagInterruptError("INTERRUPT_NEEDS_RECONCILE");
-        }
-    }
-    await writeInterruptRequest(located.runDir, next);
-    const confirmed = await readInterruptRequest(located.runDir);
-    if (!confirmed ||
-        confirmed.requestId !== requestId ||
-        requestPayloadKey(confirmed) !== requestPayloadKey(next)) {
-        throw new DagInterruptError("INTERRUPT_ALREADY_PENDING");
-    }
-    return {
-        ok: true,
-        interruptStatus: "requested",
-        request: confirmed,
-        runDir: located.runDir,
-        lifecycle: located.lifecycle,
-    };
-}
-export async function acknowledgeDagInterrupt(input) {
-    const existing = await readInterruptRequest(input.runDir);
-    if (!existing)
-        return undefined;
-    if (existing.runId !== input.runId) {
-        throw new DagInterruptError("RUNNER_IDENTITY_MISMATCH");
-    }
-    if (existing.status === "settled" || existing.status === "needs-reconcile") {
-        return existing;
-    }
-    if (!runnerIdentitiesMatch(existing.expectedRunnerIdentity, input.expectedRunnerIdentity)) {
-        throw new DagInterruptError("RUNNER_IDENTITY_MISMATCH");
-    }
-    if (existing.status === "acknowledged")
-        return existing;
-    const next = {
-        ...existing,
-        revision: existing.revision + 1,
-        status: "acknowledged",
-        acknowledgedAt: (input.now ?? new Date()).toISOString(),
-    };
-    await writeInterruptRequest(input.runDir, next);
-    return next;
-}
-export async function settleDagInterrupt(input) {
-    const existing = await readInterruptRequest(input.runDir);
-    if (!existing)
-        return undefined;
-    if (existing.status === "settled")
-        return existing;
-    if (existing.status === "requested") {
-        const next = {
-            ...existing,
-            revision: existing.revision + 1,
-            status: "needs-reconcile",
-            outcome: "runner-did-not-acknowledge",
-        };
-        await writeInterruptRequest(input.runDir, next);
-        return next;
-    }
-    const next = {
-        ...existing,
-        revision: existing.revision + 1,
-        status: "settled",
-        settledAt: (input.now ?? new Date()).toISOString(),
-        outcome: input.outcome ?? "controller-interrupted",
-    };
-    await writeInterruptRequest(input.runDir, next);
-    return next;
-}
-export async function markInterruptNeedsReconcile(input) {
-    const existing = await readInterruptRequest(input.runDir);
-    if (!existing)
-        return undefined;
-    if (existing.status === "settled")
-        return existing;
-    const next = {
-        ...existing,
-        revision: existing.revision + 1,
-        status: "needs-reconcile",
-        outcome: input.outcome,
-    };
-    await writeInterruptRequest(input.runDir, next);
-    return next;
-}
-export function projectedInterruptStatus(request) {
-    return request?.status ?? "none";
-}
-export function mergeAbortSignals(left, right) {
-    if (!left)
-        return right;
-    if (!right)
-        return left;
-    const anyFn = AbortSignal.any;
-    if (typeof anyFn === "function")
-        return anyFn([left, right]);
-    const merged = new AbortController();
-    const onAbort = () => {
-        if (!merged.signal.aborted)
-            merged.abort();
-    };
-    if (left.aborted || right.aborted) {
-        merged.abort();
-        return merged.signal;
-    }
-    left.addEventListener("abort", onAbort, { once: true });
-    right.addEventListener("abort", onAbort, { once: true });
-    return merged.signal;
-}
-export function startInterruptWatcher(input) {
-    let stopped = false;
-    const tick = () => {
-        if (stopped || input.controller.signal.aborted)
-            return;
-        void (async () => {
-            try {
-                const existing = await readInterruptRequest(input.runDir);
-                if (!existing || existing.runId !== input.runId)
-                    return;
-                if (existing.status !== "requested" && existing.status !== "acknowledged") {
-                    return;
-                }
-                const acknowledged = await acknowledgeDagInterrupt({
-                    runDir: input.runDir,
-                    runId: input.runId,
-                    expectedRunnerIdentity: input.expectedRunnerIdentity,
-                });
-                if (acknowledged &&
-                    (acknowledged.status === "acknowledged" ||
-                        acknowledged.status === "settled") &&
-                    !input.controller.signal.aborted) {
-                    input.controller.abort(acknowledged.reasonCode);
-                }
-            }
-            catch {
-                // Identity drift or corrupt artifact: do not abort. Leave requested
-                // for doctor / needs-reconcile at terminal.
-            }
-        })();
-    };
-    void mkdir(path.join(input.runDir, ".runtime"), { recursive: true }).then(() => {
-        if (!stopped)
-            tick();
-    }, () => {
-        if (!stopped)
-            tick();
-    });
-    const timer = setInterval(tick, 400);
-    timer.unref();
-    let watcher;
-    try {
-        watcher = watch(path.join(input.runDir, ".runtime"), () => tick());
-        watcher.unref?.();
-    }
-    catch {
-        // Polling is the guaranteed path; fs.watch is best-effort.
-    }
-    return {
-        stop: () => {
-            stopped = true;
-            clearInterval(timer);
-            watcher?.close();
-        },
-    };
-}
-function readFlag(args, index, name) {
-    const arg = args[index.value];
-    if (arg === `--${name}`) {
-        index.value += 1;
-        return args[index.value];
-    }
-    if (arg?.startsWith(`--${name}=`)) {
-        return arg.slice(`--${name}=`.length);
-    }
-    return undefined;
-}
-export function parseDagRequestInterruptArgs(args) {
-    let runId;
-    let requestId;
-    let targetOperationId;
-    let reasonCode;
-    let reason;
-    let pid;
-    let hostname;
-    let startedAt;
-    let fingerprint;
-    for (let i = 0; i < args.length; i += 1) {
-        const cursor = { value: i };
-        const arg = args[i];
-        const runIdValue = readFlag(args, cursor, "run-id");
-        if (runIdValue !== undefined) {
-            runId = runIdValue;
-            i = cursor.value;
-            continue;
-        }
-        const requestIdValue = readFlag(args, cursor, "request-id");
-        if (requestIdValue !== undefined) {
-            requestId = requestIdValue;
-            i = cursor.value;
-            continue;
-        }
-        const opValue = readFlag(args, cursor, "target-operation-id");
-        if (opValue !== undefined) {
-            targetOperationId = opValue;
-            i = cursor.value;
-            continue;
-        }
-        const reasonCodeValue = readFlag(args, cursor, "reason-code");
-        if (reasonCodeValue !== undefined) {
-            reasonCode = reasonCodeValue;
-            i = cursor.value;
-            continue;
-        }
-        const reasonValue = readFlag(args, cursor, "reason");
-        if (reasonValue !== undefined) {
-            reason = reasonValue;
-            i = cursor.value;
-            continue;
-        }
-        const pidValue = readFlag(args, cursor, "expected-runner-pid");
-        if (pidValue !== undefined) {
-            pid = pidValue;
-            i = cursor.value;
-            continue;
-        }
-        const hostValue = readFlag(args, cursor, "expected-runner-hostname");
-        if (hostValue !== undefined) {
-            hostname = hostValue;
-            i = cursor.value;
-            continue;
-        }
-        const startedValue = readFlag(args, cursor, "expected-runner-started-at");
-        if (startedValue !== undefined) {
-            startedAt = startedValue;
-            i = cursor.value;
-            continue;
-        }
-        const fpValue = readFlag(args, cursor, "expected-controller-fingerprint");
-        if (fpValue !== undefined) {
-            fingerprint = fpValue;
-            i = cursor.value;
-            continue;
-        }
-        if (arg === "--json")
-            continue;
-        if (arg?.startsWith("-")) {
-            throw new DagInterruptError("INVALID_INPUT", `unknown dag request-interrupt flag: ${arg}`);
-        }
-        throw new DagInterruptError("INVALID_INPUT", `unexpected positional argument: ${arg}`);
-    }
-    const parsedPid = Number(pid);
-    if (!runId?.trim() ||
-        !requestId?.trim() ||
-        !targetOperationId?.trim() ||
-        !reasonCode ||
-        !reason ||
-        !hostname?.trim() ||
-        !startedAt?.trim() ||
-        !fingerprint?.trim() ||
-        !Number.isInteger(parsedPid) ||
-        parsedPid <= 0) {
-        throw new DagInterruptError("INVALID_INPUT", "dag request-interrupt requires --run-id, --request-id, --target-operation-id, --reason-code, --reason, --expected-runner-pid, --expected-runner-hostname, --expected-runner-started-at, --expected-controller-fingerprint");
-    }
-    if (!isInterruptReasonCode(reasonCode)) {
-        throw new DagInterruptError("INVALID_INPUT", `reason-code must be one of ${INTERRUPT_REASON_CODES.join("|")}`);
-    }
-    return {
-        runId: runId.trim(),
-        requestId: requestId.trim(),
-        targetOperationId: targetOperationId.trim(),
-        reasonCode,
-        reason,
-        expectedRunnerIdentity: {
-            pid: parsedPid,
-            hostname: hostname.trim(),
-            startedAt: startedAt.trim(),
-            controllerFingerprint: fingerprint.trim(),
-        },
-    };
-}
-export async function executeDagRequestInterrupt(repoRoot, rawArgs) {
-    const parsed = parseDagRequestInterruptArgs(rawArgs);
-    return requestDagInterrupt({
-        cwd: repoRoot,
-        runId: parsed.runId,
-        requestId: parsed.requestId,
-        targetOperationId: parsed.targetOperationId,
-        reasonCode: parsed.reasonCode,
-        reasonDetail: parsed.reason,
-        expectedRunnerIdentity: parsed.expectedRunnerIdentity,
-        requestedBy: { source: "cli" },
-    });
-}
-export function defaultLocalHostname() {
-    return localHostname();
-}
-export function getActiveRunDir(cwd, runId) {
-    return getDagRunDir(cwd, "active", runId);
-}