@tea-agent/loop-agent 0.41.0 → 0.42.0-next.1

package/dist/infrastructure/console/context-export-store.js

@@ -0,0 +1,160 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, mkdir, open, readdir, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { assertSafeAppDataPath, ensureSecureDir, readJsonIfExists, writeSecureJson, } from "./app-data.js";
+export const DEFAULT_CONTEXT_EXPORT_TTL_MS = 60 * 60 * 1000;
+export const DEFAULT_CONTEXT_EXPORT_LEASE_TTL_MS = 5 * 60 * 1000;
+export const CONTEXT_EXPORT_SCHEMA_VERSION = 1;
+const exportWriteChains = new Map();
+function serializeExport(exportId, operation) {
+    const previous = exportWriteChains.get(exportId) ?? Promise.resolve();
+    const next = previous.then(operation, operation);
+    exportWriteChains.set(exportId, next.then(() => undefined, () => undefined));
+    return next;
+}
+function exportRoot(appData) {
+    const root = appData.contextExports;
+    if (!root)
+        throw new Error("console context export root unavailable");
+    return assertSafeAppDataPath(appData.root, root);
+}
+function exportDir(appData, exportId) {
+    if (!/^[a-f0-9]{32}$/.test(exportId))
+        throw new Error("invalid context export id");
+    return assertSafeAppDataPath(exportRoot(appData), path.join(exportRoot(appData), exportId));
+}
+function metadataPath(appData, exportId) {
+    return path.join(exportDir(appData, exportId), "metadata.json");
+}
+export async function createContextExport(input) {
+    const now = input.now ?? new Date();
+    const ttlMs = input.ttlMs ?? DEFAULT_CONTEXT_EXPORT_TTL_MS;
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1)
+        throw new Error("invalid context export TTL");
+    const exportId = randomBytes(16).toString("hex");
+    const dir = exportDir(input.appData, exportId);
+    ensureSecureDir(dir);
+    const payloadPath = assertSafeAppDataPath(dir, path.join(dir, "bundle.zip"));
+    await writeFile(payloadPath, input.bundle.zipBytes, {
+        flag: "wx",
+        mode: 0o600,
+    });
+    await chmod(payloadPath, 0o600).catch(() => undefined);
+    const record = {
+        schemaVersion: CONTEXT_EXPORT_SCHEMA_VERSION,
+        exportId,
+        repoFingerprint: input.appData.fingerprint,
+        bundleId: input.bundle.manifest.bundleId,
+        bundleSha256: input.bundle.manifest.bundleSha256,
+        profile: input.bundle.manifest.profile,
+        target: input.bundle.manifest.target,
+        state: "ready",
+        createdAt: now.toISOString(),
+        expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+        bytes: input.bundle.zipBytes.byteLength,
+    };
+    await writeSecureJson(metadataPath(input.appData, exportId), record);
+    return record;
+}
+export async function readContextExport(appData, exportId) {
+    return readJsonIfExists(metadataPath(appData, exportId));
+}
+export async function acquireContextExportLease(input) {
+    return serializeExport(input.exportId, async () => {
+        const now = input.now ?? new Date();
+        const leaseTtlMs = input.leaseTtlMs ?? DEFAULT_CONTEXT_EXPORT_LEASE_TTL_MS;
+        if (!Number.isSafeInteger(leaseTtlMs) || leaseTtlMs < 1) {
+            throw new Error("invalid context export lease TTL");
+        }
+        const record = await readContextExport(input.appData, input.exportId);
+        if (!record || record.repoFingerprint !== input.appData.fingerprint) {
+            throw new Error("context export not found");
+        }
+        const expiresAt = Date.parse(record.expiresAt);
+        if (record.state !== "ready" ||
+            !Number.isFinite(expiresAt) ||
+            expiresAt <= now.getTime()) {
+            throw new Error("context export expired");
+        }
+        if (record.lease) {
+            const acquiredAt = Date.parse(record.lease.acquiredAt);
+            if (Number.isFinite(acquiredAt) &&
+                acquiredAt + leaseTtlMs > now.getTime()) {
+                throw new Error("context export already leased");
+            }
+        }
+        const payloadPath = path.join(exportDir(input.appData, input.exportId), "bundle.zip");
+        const handle = await open(payloadPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        let bytes;
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1) {
+                throw new Error("context export payload is not an owned regular file");
+            }
+            bytes = await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+        const leaseId = randomBytes(16).toString("hex");
+        const leased = {
+            ...record,
+            lease: { leaseId, acquiredAt: now.toISOString() },
+        };
+        await writeSecureJson(metadataPath(input.appData, input.exportId), leased);
+        return { record: leased, leaseId, bytes };
+    });
+}
+export async function releaseContextExportLease(input) {
+    await serializeExport(input.exportId, async () => {
+        const record = await readContextExport(input.appData, input.exportId);
+        if (!record?.lease || record.lease.leaseId !== input.leaseId)
+            return;
+        const { lease: _lease, ...released } = record;
+        await writeSecureJson(metadataPath(input.appData, input.exportId), released);
+    });
+}
+export async function reconcileContextExports(input) {
+    const root = exportRoot(input.appData);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const now = input.now ?? new Date();
+    const leaseTtlMs = input.leaseTtlMs ?? DEFAULT_CONTEXT_EXPORT_LEASE_TTL_MS;
+    if (!Number.isSafeInteger(leaseTtlMs) || leaseTtlMs < 1) {
+        throw new Error("invalid context export lease TTL");
+    }
+    const removed = [];
+    const retainedLeased = [];
+    for (const name of await readdir(root)) {
+        if (!/^[a-f0-9]{32}$/.test(name))
+            continue;
+        const record = await readContextExport(input.appData, name).catch(() => undefined);
+        let reconciledRecord = record;
+        if (record?.lease) {
+            const acquiredAt = Date.parse(record.lease.acquiredAt);
+            if (Number.isFinite(acquiredAt) &&
+                acquiredAt + leaseTtlMs > now.getTime()) {
+                retainedLeased.push(name);
+                continue;
+            }
+            const { lease: _lease, ...released } = record;
+            reconciledRecord = released;
+        }
+        const expiresAt = reconciledRecord
+            ? Date.parse(reconciledRecord.expiresAt)
+            : Number.NaN;
+        if (!reconciledRecord ||
+            !Number.isFinite(expiresAt) ||
+            expiresAt <= now.getTime()) {
+            await rm(exportDir(input.appData, name), {
+                recursive: true,
+                force: true,
+            });
+            removed.push(name);
+        }
+        else if (record?.lease) {
+            await writeSecureJson(metadataPath(input.appData, name), reconciledRecord);
+        }
+    }
+    return { removed, retainedLeased };
+}

package/dist/infrastructure/console/dir-lock.js

@@ -0,0 +1,132 @@
+import { randomBytes } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, utimes, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ensureSecureDir } from "./app-data.js";
+const OWNER_FILE = "owner";
+const DEFAULT_STALE_MS = 30_000;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function freshToken() {
+    return randomBytes(16).toString("hex");
+}
+function ownerPath(lockDir) {
+    return path.join(lockDir, OWNER_FILE);
+}
+/**
+ * A lock's freshness is the owner-file heartbeat, not the containing
+ * directory mtime. Creating or editing a file does not refresh the directory
+ * mtime, so using the latter could make a healthy long-running lock appear
+ * stale and permit a second holder into its critical section.
+ */
+async function lockTimestamp(lockDir) {
+    const ownerStat = await lstat(ownerPath(lockDir)).catch(() => undefined);
+    if (ownerStat?.isFile())
+        return ownerStat.mtimeMs;
+    return (await lstat(lockDir).catch(() => undefined))?.mtimeMs;
+}
+export async function isDirLockStale(lockDir, staleMs, nowMs = Date.now()) {
+    const timestamp = await lockTimestamp(lockDir);
+    return timestamp === undefined || nowMs - timestamp > staleMs;
+}
+async function refreshDirLock(lockDir, token) {
+    const owner = await readFile(ownerPath(lockDir), "utf-8").catch(() => undefined);
+    if (owner !== token)
+        return;
+    const now = new Date();
+    await utimes(ownerPath(lockDir), now, now).catch(() => { });
+}
+/**
+ * Cross-process exclusive directory lock (mkdir-based). Ownership is
+ * token-guarded: each holder writes a unique owner file inside the lock
+ * directory and only ever removes a lock whose owner token matches its own.
+ *
+ * Release protocol (B2): verify owner AND freshness BEFORE touching the lock
+ * path. Takeover only ever targets a stale lock, so a holder that releases a
+ * lock it still owns (fresh) cannot have been taken over between the verify
+ * and the rename — it moves its own lock, never a successor's. A stale lock is
+ * deliberately left alone (a takeover may be in flight); only the post-rename
+ * tombstone check restores a lock moved by an unexpected race, never deletes a
+ * successor's live lock.
+ */
+export async function acquireDirLock(lockDir, options) {
+    const token = options?.token ?? freshToken();
+    const staleMs = options?.staleMs ?? DEFAULT_STALE_MS;
+    ensureSecureDir(path.dirname(lockDir));
+    for (;;) {
+        try {
+            await mkdir(lockDir);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "EEXIST")
+                throw error;
+            const stat = await lstat(lockDir).catch(() => undefined);
+            if (stat?.isDirectory() && await isDirLockStale(lockDir, staleMs)) {
+                const tombstone = `${lockDir}.${freshToken()}.tomb`;
+                try {
+                    await rename(lockDir, tombstone);
+                    await rm(tombstone, { recursive: true, force: true });
+                }
+                catch {
+                    // another process won the takeover; retry the loop
+                }
+                continue;
+            }
+            await delay(20);
+            continue;
+        }
+        try {
+            await writeFile(ownerPath(lockDir), token, {
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        catch {
+            await rm(lockDir, { recursive: true, force: true });
+            continue;
+        }
+        break;
+    }
+    const heartbeat = setInterval(() => { void refreshDirLock(lockDir, token); }, Math.max(10, Math.floor(staleMs / 3)));
+    heartbeat.unref();
+    let released = false;
+    const release = async () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(heartbeat);
+        // Verify the lock is still ours AND fresh before renaming it away. If the
+        // owner no longer matches, a successor holds the lock — never touch it.
+        const stat = await lstat(lockDir).catch(() => undefined);
+        if (!stat?.isDirectory())
+            return;
+        if (await isDirLockStale(lockDir, staleMs)) {
+            // Our lock went stale: a takeover may be in flight or imminent. Leave
+            // it alone — removing it now could delete a successor's live lock.
+            return;
+        }
+        const owner = await readFile(ownerPath(lockDir), "utf-8").catch(() => undefined);
+        if (owner !== token)
+            return;
+        const tombstone = `${lockDir}.${token}.release`;
+        try {
+            await rename(lockDir, tombstone);
+        }
+        catch {
+            // lock path already gone (a takeover removed it); nothing of ours.
+            return;
+        }
+        const movedOwner = await readFile(path.join(tombstone, OWNER_FILE), "utf-8").catch(() => undefined);
+        if (movedOwner !== token) {
+            // Raced with a takeover in the microsecond window between the fresh
+            // verify and the rename: restore the moved lock if the path is still
+            // free; otherwise leave the tombstone for reconcile — never delete a
+            // successor's live lock.
+            await rename(tombstone, lockDir).catch(() => { });
+            return;
+        }
+        await rm(tombstone, { recursive: true, force: true }).catch(() => { });
+    };
+    return { token, release };
+}

package/dist/{worker → infrastructure}/console/operation-store.js

@@ -139,6 +139,21 @@ export class OperationStore {
         for (const op of await this.list()) {
             if (TERMINAL_OPERATION_STATES.has(op.state))
                 continue;
+            // A consoleUpdateAndInit whose record already proves a requested
+            // handoff died before writing its terminal state: the update and
+            // restart themselves succeeded — the booting process IS the
+            // handoff target. Mark it succeeded instead of surfacing the
+            // generic needs-reconcile failure copy to the operator.
+            if (op.action === "consoleUpdateAndInit" &&
+                op.state === "needs-reconcile" &&
+                isProvenConsoleUpdateHandoff(op.result)) {
+                changed.push(await this.update(op.operationId, {
+                    state: "succeeded",
+                    errorCode: undefined,
+                    errorMessage: undefined,
+                }));
+                continue;
+            }
             if (op.state === "needs-reconcile")
                 continue;
             let next;
@@ -162,6 +177,19 @@ export class OperationStore {
 export function isTerminalOperationState(state) {
     return TERMINAL_OPERATION_STATES.has(state);
 }
+/**
+ * True when a consoleUpdateAndInit result proves the handoff was requested
+ * (install verified + init clean + new Console spawned). Used by boot
+ * reconcile to close the record as succeeded even though the old process
+ * died before writing its terminal state.
+ */
+function isProvenConsoleUpdateHandoff(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const shape = result;
+    return (shape.state === "restarting" &&
+        shape.maintenance?.handoff?.status === "requested");
+}
 export function clipPreview(text, max = 4096) {
     if (text.length <= max)
         return text;

package/dist/infrastructure/harness/artifact-store.js

@@ -1,6 +1,6 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { writeJsonAtomic, writeTextAtomic, } from "./atomic-write.js";
+import { writeJsonAtomic, writeBufferAtomic, writeTextAtomic, } from "./atomic-write.js";
 function resolveRepoRootFromDagRunDir(runDir) {
     const normalized = path.resolve(runDir);
     const lifecycleDir = path.dirname(normalized);
@@ -26,12 +26,16 @@ function dagWriteOptions(runDir, options) {
     return {
         repoRoot: options?.repoRoot ?? resolveRepoRootFromDagRunDir(runDir),
         allowCompletedFactsWrite: options?.allowCompletedFactsWrite,
+        mode: options?.mode,
+        directoryMode: options?.directoryMode,
     };
 }
 function pathWriteOptions(targetPath, options) {
     return {
         repoRoot: options?.repoRoot ?? resolveRepoRootFromHarnessPath(targetPath),
         allowCompletedFactsWrite: options?.allowCompletedFactsWrite,
+        mode: options?.mode,
+        directoryMode: options?.directoryMode,
     };
 }
 function completedRelocationWriteOptions(runDir) {
@@ -48,6 +52,11 @@ export async function writeDagNodeTextArtifact(runDir, nodeId, fileName, content
     await writeTextAtomic(targetPath, content, dagWriteOptions(runDir, options));
     return targetPath;
 }
+export async function writeDagNodeBufferArtifact(runDir, nodeId, fileName, bytes, options) {
+    const targetPath = path.join(runDir, nodeId, fileName);
+    await writeBufferAtomic(targetPath, bytes, dagWriteOptions(runDir, options));
+    return targetPath;
+}
 export async function writeDagNodeJsonArtifact(runDir, nodeId, fileName, value, options) {
     const targetPath = path.join(runDir, nodeId, fileName);
     await writeJsonAtomic(targetPath, value, dagWriteOptions(runDir, options));

package/dist/infrastructure/harness/atomic-write.js

@@ -30,10 +30,17 @@ async function writeAtomic(targetPath, content, options) {
     const resolved = options?.repoRoot && !path.isAbsolute(targetPath)
         ? path.resolve(options.repoRoot, targetPath)
         : path.resolve(targetPath);
-    await mkdir(path.dirname(resolved), { recursive: true });
+    await mkdir(path.dirname(resolved), {
+        recursive: true,
+        ...(options?.directoryMode !== undefined
+            ? { mode: options.directoryMode }
+            : {}),
+    });
     const tempPath = `${resolved}.${process.pid}.${(atomicWriteSequence += 1)}.tmp`;
     try {
-        await writeFile(tempPath, content, "utf-8");
+        await writeFile(tempPath, content, {
+            ...(options?.mode !== undefined ? { mode: options.mode } : {}),
+        });
         try {
             await rename(tempPath, resolved);
         }
@@ -54,6 +61,9 @@ export async function writeJsonAtomic(targetPath, value, options) {
 export async function writeTextAtomic(targetPath, text, options) {
     await writeAtomic(targetPath, text, options);
 }
+export async function writeBufferAtomic(targetPath, bytes, options) {
+    await writeAtomic(targetPath, bytes, options);
+}
 export function serializeJsonl(entries) {
     if (entries.length === 0)
         return "";

package/dist/shared/context-transfer/artifact-revision.js

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import { artifactRevisionV1Schema } from "../context-transfer.js";
+import { redactSecretsWithFindings } from "../preview.js";
+export const ARTIFACT_REVISION_LIMITS = Object.freeze({
+    singleFileBytes: 10 * 1024 * 1024,
+    diffPreviewBytes: 64 * 1024,
+});
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isTextMedia(mediaType) {
+    return mediaType.startsWith("text/") || mediaType.includes("json") || mediaType.includes("xml");
+}
+function stableJson(bytes) {
+    try {
+        const value = JSON.parse(bytes.toString("utf8"));
+        const sort = (input) => {
+            if (Array.isArray(input))
+                return input.map(sort);
+            if (input && typeof input === "object") {
+                return Object.fromEntries(Object.entries(input)
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([key, child]) => [key, sort(child)]));
+            }
+            return input;
+        };
+        return `${JSON.stringify(sort(value), null, 2)}\n`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function boundedLineDiff(before, after) {
+    const beforeLines = before.split(/\r?\n/);
+    const afterLines = after.split(/\r?\n/);
+    const rows = [];
+    const limit = Math.max(beforeLines.length, afterLines.length);
+    for (let index = 0; index < limit; index += 1) {
+        if (beforeLines[index] === afterLines[index])
+            continue;
+        if (beforeLines[index] !== undefined)
+            rows.push(`- ${beforeLines[index]}`);
+        if (afterLines[index] !== undefined)
+            rows.push(`+ ${afterLines[index]}`);
+    }
+    const complete = rows.join("\n");
+    const preview = Buffer.from(complete, "utf8");
+    if (preview.byteLength <= ARTIFACT_REVISION_LIMITS.diffPreviewBytes) {
+        return { summary: complete, truncated: false };
+    }
+    return {
+        summary: preview.subarray(0, ARTIFACT_REVISION_LIMITS.diffPreviewBytes).toString("utf8") + "\n[diff truncated]",
+        truncated: true,
+    };
+}
+export function validateAndDescribeArtifactRevision(input) {
+    if (input.declaration.revisionPolicy !== "replace-file") {
+        throw new Error("ARTIFACT_NOT_REVISION_ELIGIBLE");
+    }
+    if (input.candidateBytes.byteLength > ARTIFACT_REVISION_LIMITS.singleFileBytes) {
+        throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: candidate exceeds size limit");
+    }
+    if (sha256(input.parentBytes) !== input.parentSha256) {
+        throw new Error("ARTIFACT_REVISION_DRIFT: parent artifact hash mismatch");
+    }
+    if (input.mediaType !== input.declaration.mediaType) {
+        throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: media type mismatch");
+    }
+    const textCandidate = isTextMedia(input.mediaType);
+    if (textCandidate &&
+        redactSecretsWithFindings(input.candidateBytes.toString("utf8"))
+            .findingCount > 0) {
+        throw new Error("SECRET_SCAN_CONFIRMATION_REQUIRED");
+    }
+    const candidateSha256 = sha256(input.candidateBytes);
+    if (candidateSha256 === input.parentSha256) {
+        throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: replacement is unchanged");
+    }
+    let kind = "binary";
+    let summary = `binary ${input.parentBytes.byteLength} -> ${input.candidateBytes.byteLength} bytes; ${input.parentSha256} -> ${candidateSha256}`;
+    let truncated = false;
+    let diffPreview;
+    const schemaChecks = [];
+    if (input.declaration.schemaId || input.mediaType.includes("json")) {
+        const before = stableJson(input.parentBytes);
+        const after = stableJson(input.candidateBytes);
+        if (!before || !after) {
+            throw new Error("ARTIFACT_REVISION_SCHEMA_INVALID: expected valid JSON");
+        }
+        kind = "json";
+        const declaredSchemaId = input.declaration.schemaId;
+        if (declaredSchemaId) {
+            const validator = input.artifactSchemaResolver?.(declaredSchemaId);
+            if (!validator) {
+                // Fail closed (W4.3): a declared schema without a registered
+                // validator must not pass as "JSON syntax only" — revision
+                // eligibility would silently outrun actual verification.
+                throw new Error(`ARTIFACT_REVISION_SCHEMA_INVALID: no registered revision validator for ${declaredSchemaId}; artifact cannot be staged until its schema is registered`);
+            }
+            const parsed = JSON.parse(after);
+            const result = validator.safeParse(parsed);
+            if (!result.success) {
+                const issue = result.error.issues[0];
+                const issuePath = issue
+                    ? issue.path.map((part) => String(part)).join(".")
+                    : "(root)";
+                throw new Error(`ARTIFACT_REVISION_SCHEMA_INVALID: candidate does not satisfy ${declaredSchemaId} at ${issuePath}: ${issue?.message ?? "schema violation"}`);
+            }
+            schemaChecks.push({
+                id: "artifact-schema",
+                status: "pass",
+                detail: declaredSchemaId,
+            });
+        }
+        const diff = boundedLineDiff(before, after);
+        summary = diff.summary;
+        truncated = diff.truncated;
+        diffPreview = Buffer.from(diff.summary, "utf8");
+    }
+    else if (isTextMedia(input.mediaType)) {
+        kind = "text";
+        const diff = boundedLineDiff(input.parentBytes.toString("utf8"), input.candidateBytes.toString("utf8"));
+        summary = diff.summary;
+        truncated = diff.truncated;
+        diffPreview = Buffer.from(diff.summary, "utf8");
+    }
+    const revision = artifactRevisionV1Schema.parse({
+        schemaVersion: 1,
+        revisionId: input.revisionId,
+        state: "validated",
+        parent: {
+            runId: input.parentRunId,
+            nodeId: input.producerNodeId,
+            artifactPath: input.declaration.path,
+            artifactSha256: input.parentSha256,
+            ...(input.declaration.schemaId ? { artifactSchemaId: input.declaration.schemaId } : {}),
+        },
+        candidate: {
+            stagingPath: input.stagingPath,
+            sha256: candidateSha256,
+            bytes: input.candidateBytes.byteLength,
+            mediaType: input.mediaType,
+            uploadedAt: input.uploadedAt,
+            uploadedBy: "operator",
+        },
+        validation: {
+            status: "pass",
+            checks: [
+                { id: "parent-hash", status: "pass" },
+                { id: "declared-path", status: "pass" },
+                { id: "media-type", status: "pass" },
+                textCandidate
+                    ? { id: "secret-scan", status: "pass" }
+                    : {
+                        id: "secret-scan",
+                        status: "warning",
+                        detail: "binary candidate was not decoded for text secret scanning",
+                    },
+                ...(kind === "json" ? [{ id: "json-syntax", status: "pass" }] : []),
+                ...schemaChecks,
+            ],
+        },
+        diff: {
+            kind,
+            summary,
+            ...(diffPreview ? { previewPath: `artifact-revisions/${input.revisionId}/diff.txt` } : {}),
+            truncated,
+        },
+        expiresAt: input.expiresAt,
+    });
+    return { revision, ...(diffPreview ? { diffPreview } : {}) };
+}