@tea-agent/loop-agent 0.16.26 → 0.17.1

package/dist/task/contract/import-revision.js

@@ -0,0 +1,96 @@
+/**
+ * After managed import-prd updates source-manifest / task.json, bump contract revision.
+ * import-prd owns reference bytes; this only refreshes TaskContractRefV1.
+ */
+import { CANONICALIZER_VERSION, PROJECTION_VERSION, TASK_CONFIG_SCHEMA_VERSION, TASK_CONTRACT_REF_SCHEMA_VERSION, } from "./constants.js";
+import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, } from "./hash.js";
+import { acquireTaskContractLock } from "./lock.js";
+import { loadObservedTaskBytes, logicalRevisionForState, observeTaskContractState, } from "./observe.js";
+import { serializeTaskConfigForDisk } from "./project.js";
+import { finalizeTransaction, runJournaledContractCommit } from "./transaction.js";
+import { parseTaskConfigForRuntime } from "../runtime.js";
+export async function refreshManagedContractAfterImport(input) {
+    const state = await observeTaskContractState(input.repoRoot, input.taskId);
+    // Only refresh when already managed (or externally-modified with a ref).
+    // legacy-unversioned: first apply/adopt will capture manifest.
+    if (!state.ref) {
+        return null;
+    }
+    if (state.effectiveStatus === "transaction-incomplete") {
+        throw new Error(`TRANSACTION_INCOMPLETE: cannot refresh contract after import-prd for ${input.taskId}; run task contract recover first`);
+    }
+    const requestId = input.requestId ??
+        `import-prd-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+    const requestPayloadSha256 = "0".repeat(64); // import path uses synthetic payload
+    const lock = await acquireTaskContractLock({
+        repoRoot: input.repoRoot,
+        taskId: input.taskId,
+        requestId,
+        operation: "import-prd-revision",
+    });
+    try {
+        const state2 = await observeTaskContractState(input.repoRoot, input.taskId);
+        if (!state2.ref)
+            return null;
+        const currentRevision = logicalRevisionForState(state2);
+        const bytes = await loadObservedTaskBytes(input.repoRoot, input.taskId);
+        if (bytes.requirementBytes === null ||
+            bytes.constraintsBytes === null ||
+            bytes.taskConfigRaw === null) {
+            throw new Error("import-prd revision refresh requires 需求.md, 执行约束.md, and task.json");
+        }
+        const fullConfig = parseTaskConfigForRuntime(bytes.taskConfigRaw);
+        const taskConfigContent = serializeTaskConfigForDisk(fullConfig);
+        const sourceHashes = computeSourceHashes({
+            requirementBytes: bytes.requirementBytes,
+            constraintsBytes: bytes.constraintsBytes,
+            referenceManifestBytes: bytes.referenceManifestBytes,
+        });
+        const taskConfigSha256 = computeTaskConfigSha256(fullConfig);
+        const canonicalHash = computeCanonicalHash({
+            sourceHashes,
+            taskConfigSha256,
+        });
+        const nextRevision = currentRevision + 1;
+        const nextRef = {
+            schemaVersion: TASK_CONTRACT_REF_SCHEMA_VERSION,
+            taskId: input.taskId,
+            revision: nextRevision,
+            projectionVersion: PROJECTION_VERSION,
+            canonicalizerVersion: CANONICALIZER_VERSION,
+            taskConfigSchemaVersion: TASK_CONFIG_SCHEMA_VERSION,
+            sourceHashes,
+            taskConfigSha256,
+            canonicalHash,
+            updatedAt: new Date().toISOString(),
+            lastRequestId: requestId,
+        };
+        const expectedHash = state2.observedCanonicalHash ?? state2.ref.canonicalHash;
+        const { txId } = await runJournaledContractCommit({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            operation: "import-prd-revision",
+            requestId,
+            requestPayloadSha256,
+            expectedRevision: currentRevision,
+            expectedObservedCanonicalHash: expectedHash,
+            nextRevision,
+            fencingToken: lock.record.fencingToken,
+            targets: {
+                requirementContent: bytes.requirementBytes,
+                constraintsContent: bytes.constraintsBytes,
+                taskConfigContent,
+                contractRef: nextRef,
+            },
+        });
+        await finalizeTransaction({
+            repoRoot: input.repoRoot,
+            taskId: input.taskId,
+            txId,
+        });
+        return nextRef;
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/task/contract/index.js

@@ -0,0 +1,17 @@
+export * from "./constants.js";
+export * from "./types.js";
+export * from "./canonicalize.js";
+export * from "./hash.js";
+export * from "./schema.js";
+export * from "./project.js";
+export * from "./paths.js";
+export * from "./observe.js";
+export * from "./lock.js";
+export * from "./journal.js";
+export * from "./transaction.js";
+export * from "./request-ledger.js";
+// apply.ts owns diffTaskContract / validateDraftForTask / applyTaskContract surface
+export * from "./apply.js";
+export * from "./adopt.js";
+export * from "./recover.js";
+export * from "./import-revision.js";

package/dist/task/contract/journal.js

@@ -0,0 +1,155 @@
+import { copyFile, mkdir, readFile, readdir, rename, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic, writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { getTaskPaths } from "../runtime.js";
+export function getTransactionPaths(repoRoot, taskId, txId) {
+    const { transactionsDir } = getTaskPaths(repoRoot, taskId);
+    const root = path.join(transactionsDir, txId);
+    return {
+        txId,
+        root,
+        statePath: path.join(root, "state.json"),
+        intentPath: path.join(root, "intent.json"),
+        commitPath: path.join(root, "commit.json"),
+        stagedDir: path.join(root, "staged"),
+        originalsDir: path.join(root, "originals"),
+    };
+}
+export async function ensureTransactionDirs(txPaths) {
+    await mkdir(txPaths.stagedDir, { recursive: true });
+    await mkdir(txPaths.originalsDir, { recursive: true });
+}
+export async function writeTransactionState(txPaths, phase, error) {
+    const state = {
+        schemaVersion: 1,
+        txId: txPaths.txId,
+        phase,
+        updatedAt: new Date().toISOString(),
+        ...(error ? { error } : {}),
+    };
+    await writeJsonAtomic(txPaths.statePath, state);
+}
+export async function readTransactionState(txPaths) {
+    try {
+        const raw = await readFile(txPaths.statePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeTransactionIntent(txPaths, intent) {
+    await writeJsonAtomic(txPaths.intentPath, intent);
+}
+export async function readTransactionIntent(txPaths) {
+    try {
+        const raw = await readFile(txPaths.intentPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeCommitMarker(txPaths, commit) {
+    await writeJsonAtomic(txPaths.commitPath, {
+        schemaVersion: 1,
+        ...commit,
+    });
+}
+export async function commitMarkerExists(txPaths) {
+    try {
+        await readFile(txPaths.commitPath, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function stageTextFile(txPaths, relativePath, content, _repoRoot) {
+    const target = path.join(txPaths.stagedDir, relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeTextAtomic(target, content);
+    return target;
+}
+export async function stageJsonFile(txPaths, relativePath, value, _repoRoot) {
+    const target = path.join(txPaths.stagedDir, relativePath);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeJsonAtomic(target, value);
+    return target;
+}
+export async function backupOriginalIfExists(txPaths, absoluteTarget, relativePath) {
+    const backupPath = path.join(txPaths.originalsDir, relativePath);
+    await mkdir(path.dirname(backupPath), { recursive: true });
+    try {
+        const content = await readFile(absoluteTarget, "utf-8");
+        await writeTextAtomic(backupPath, content);
+        return { existed: true, content };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            await writeTextAtomic(`${backupPath}.missing`, "missing\n");
+            return { existed: false, content: null };
+        }
+        throw error;
+    }
+}
+async function replaceFile(targetPath, content) {
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    const tempPath = `${targetPath}.${process.pid}.tmp`;
+    await writeFile(tempPath, content, "utf-8");
+    try {
+        await rename(tempPath, targetPath);
+    }
+    catch {
+        await copyFile(tempPath, targetPath);
+        await unlink(tempPath).catch(() => { });
+    }
+}
+export async function applyStagedToTarget(txPaths, relativePath, absoluteTarget) {
+    const stagedPath = path.join(txPaths.stagedDir, relativePath);
+    const content = await readFile(stagedPath, "utf-8");
+    await replaceFile(absoluteTarget, content);
+}
+export async function restoreOriginal(txPaths, relativePath, absoluteTarget, existedBefore) {
+    const backupPath = path.join(txPaths.originalsDir, relativePath);
+    const missingMarker = `${backupPath}.missing`;
+    if (!existedBefore) {
+        await unlink(absoluteTarget).catch(() => { });
+        return;
+    }
+    try {
+        await readFile(missingMarker, "utf-8");
+        await unlink(absoluteTarget).catch(() => { });
+        return;
+    }
+    catch {
+        // not missing
+    }
+    const content = await readFile(backupPath, "utf-8");
+    await replaceFile(absoluteTarget, content);
+}
+export async function listTransactionIds(repoRoot, taskId) {
+    const { transactionsDir } = getTaskPaths(repoRoot, taskId);
+    try {
+        const entries = await readdir(transactionsDir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/task/contract/lock.js

@@ -0,0 +1,153 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getTaskContractPaths } from "./paths.js";
+function processStartIdentity() {
+    return `${process.pid}:${process.ppid ?? 0}:${process.env.LOOP_AGENT_PROCESS_START ?? "na"}`;
+}
+async function readLock(lockPath) {
+    try {
+        const raw = await readFile(lockPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Acquire per-task contract lock with fencing token.
+ * Repo-wide mutation lease (when needed) must be taken *before* calling this.
+ */
+export async function acquireTaskContractLock(input) {
+    const paths = getTaskContractPaths(input.repoRoot, input.taskId);
+    await mkdir(paths.taskDir, { recursive: true });
+    const lockPath = paths.lockPath;
+    const fencingToken = randomBytes(16).toString("hex");
+    const ownerPid = process.pid;
+    const ownerStartIdentity = processStartIdentity();
+    const now = new Date().toISOString();
+    const record = {
+        schemaVersion: 1,
+        taskId: input.taskId,
+        fencingToken,
+        ownerPid,
+        ownerStartIdentity,
+        acquiredAt: now,
+        heartbeatAt: now,
+        requestId: input.requestId,
+        operation: input.operation,
+    };
+    const tempPath = `${lockPath}.${ownerPid}.${fencingToken}.tmp`;
+    await writeFile(tempPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+    try {
+        const existing = await readLock(lockPath);
+        if (existing) {
+            // Never steal from a still-alive owner. Heartbeat age alone is not enough:
+            // long journaled applies do not refresh heartbeat continuously.
+            const ownerAlive = isProcessAlive(existing.ownerPid);
+            if (ownerAlive) {
+                await unlink(tempPath).catch(() => { });
+                const err = new Error(`task contract lock held by pid=${existing.ownerPid} token=${existing.fencingToken} requestId=${existing.requestId ?? ""}`);
+                err.code = "LEASE_HELD";
+                throw err;
+            }
+            // Owner PID is dead — reclaim after optional grace (default 0 for dead owners).
+            const staleMs = input.staleMs ?? 0;
+            const heartbeat = Date.parse(existing.heartbeatAt);
+            const oldEnough = !Number.isFinite(heartbeat) || Date.now() - heartbeat >= staleMs;
+            if (!oldEnough) {
+                await unlink(tempPath).catch(() => { });
+                const err = new Error(`task contract lock held by dead pid=${existing.ownerPid} but not yet reclaimable`);
+                err.code = "LEASE_HELD";
+                throw err;
+            }
+            await unlink(lockPath).catch(() => { });
+        }
+        await rename(tempPath, lockPath);
+    }
+    catch (error) {
+        await unlink(tempPath).catch(() => { });
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "LEASE_HELD") {
+            throw error;
+        }
+        const existing = await readLock(lockPath);
+        if (existing && existing.fencingToken !== fencingToken) {
+            const err = new Error(`task contract lock held by pid=${existing.ownerPid} token=${existing.fencingToken}`);
+            err.code = "LEASE_HELD";
+            throw err;
+        }
+        throw error;
+    }
+    const confirmed = await readLock(lockPath);
+    if (!confirmed || confirmed.fencingToken !== fencingToken) {
+        const err = new Error("task contract lock acquisition race lost");
+        err.code = "LEASE_HELD";
+        throw err;
+    }
+    return {
+        taskId: input.taskId,
+        lockPath,
+        fencingToken,
+        ownerPid,
+        ownerStartIdentity,
+        record: confirmed,
+        release: async () => {
+            const current = await readLock(lockPath);
+            if (current && current.fencingToken === fencingToken) {
+                await unlink(lockPath).catch(() => { });
+            }
+        },
+    };
+}
+export async function assertLockHeld(handle) {
+    const current = await readLock(handle.lockPath);
+    if (!current || current.fencingToken !== handle.fencingToken) {
+        const err = new Error("task contract lock fencing token mismatch");
+        err.code = "LEASE_HELD";
+        throw err;
+    }
+}
+export async function acquireRepoMutationLease(input) {
+    const leaseDir = path.join(input.repoRoot, ".harness");
+    await mkdir(leaseDir, { recursive: true });
+    const lockPath = path.join(leaseDir, ".repo-mutation.lock");
+    const handle = await acquireTaskContractLock({
+        repoRoot: input.repoRoot,
+        taskId: "__repo__",
+        requestId: input.requestId,
+        operation: "repo-lease",
+    });
+    await writeFile(lockPath, `${JSON.stringify({
+        schemaVersion: 1,
+        fencingToken: handle.fencingToken,
+        ownerPid: handle.ownerPid,
+        ownerStartIdentity: handle.ownerStartIdentity,
+        acquiredAt: new Date().toISOString(),
+        requestId: input.requestId,
+    }, null, 2)}\n`, "utf-8").catch(() => { });
+    return {
+        fencingToken: handle.fencingToken,
+        release: async () => {
+            await handle.release();
+            await unlink(lockPath).catch(() => { });
+        },
+    };
+}