@tea-agent/loop-agent 0.16.26 → 0.17.1

package/dist/task/contract/observe.js

@@ -0,0 +1,296 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { CONSTRAINTS_FILE_NAME, CONTRACT_FILE_NAME, REQUIREMENT_FILE_NAME, TRANSACTIONS_DIR_NAME, } from "./constants.js";
+import { computeCanonicalHash, computeSourceHashes, computeTaskConfigSha256, } from "./hash.js";
+import { parseTaskContractRef } from "./schema.js";
+import { getTaskPaths } from "../runtime.js";
+import { parseTaskConfigForRuntime } from "../runtime.js";
+import { getSourceManifestPath, readSourceManifest, } from "../source-references.js";
+async function readTextIfExists(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function loadObservedTaskBytes(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const requirementPath = path.join(paths.sourceDir, REQUIREMENT_FILE_NAME);
+    const constraintsPath = path.join(paths.sourceDir, CONSTRAINTS_FILE_NAME);
+    const [requirementBytes, constraintsBytes, taskConfigText, manifestText] = await Promise.all([
+        readTextIfExists(requirementPath),
+        readTextIfExists(constraintsPath),
+        readTextIfExists(paths.taskConfigPath),
+        readTextIfExists(getSourceManifestPath(paths.sourceDir)),
+    ]);
+    let taskConfigRaw = null;
+    let taskConfigSha256 = null;
+    if (taskConfigText !== null) {
+        taskConfigRaw = JSON.parse(taskConfigText);
+        const parsed = parseTaskConfigForRuntime(taskConfigRaw);
+        taskConfigSha256 = computeTaskConfigSha256(parsed);
+    }
+    return {
+        requirementBytes,
+        constraintsBytes,
+        taskConfigRaw,
+        taskConfigSha256,
+        referenceManifestBytes: manifestText,
+        requirementPath,
+        constraintsPath,
+        taskConfigPath: paths.taskConfigPath,
+        contractPath: paths.contractPath,
+        transactionsDir: paths.transactionsDir,
+    };
+}
+export async function readStoredContractRef(contractPath) {
+    const text = await readTextIfExists(contractPath);
+    if (text === null)
+        return null;
+    try {
+        return parseTaskContractRef(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error(`invalid contract.json at ${contractPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function listUnfinishedTransactionDirs(transactionsDir) {
+    if (!(await pathExists(transactionsDir)))
+        return [];
+    const entries = await readdir(transactionsDir, { withFileTypes: true });
+    const unfinished = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const statePath = path.join(transactionsDir, entry.name, "state.json");
+        const commitPath = path.join(transactionsDir, entry.name, "commit.json");
+        const stateText = await readTextIfExists(statePath);
+        if (!stateText) {
+            unfinished.push(entry.name);
+            continue;
+        }
+        try {
+            const state = JSON.parse(stateText);
+            if (state.phase === "finalized" ||
+                (state.phase === "committed" && (await pathExists(commitPath)))) {
+                // committed without finalized still counts as unfinished for doctor,
+                // but recover only needs finalize — still list it.
+                if (state.phase === "finalized")
+                    continue;
+            }
+            if (state.phase !== "finalized") {
+                unfinished.push(entry.name);
+            }
+        }
+        catch {
+            unfinished.push(entry.name);
+        }
+    }
+    return unfinished;
+}
+/**
+ * Derive TaskContractStateV1 by re-reading actual files (design §5.3.2/5.3.8).
+ * effectiveStatus is always derived at read time — never trusted from disk alone.
+ */
+export async function observeTaskContractState(repoRoot, taskId) {
+    const paths = getTaskPaths(repoRoot, taskId);
+    const errors = [];
+    const taskExists = await pathExists(paths.taskConfigPath);
+    if (!taskExists) {
+        return {
+            effectiveStatus: "legacy-unversioned",
+            observationErrors: [
+                {
+                    code: "NOT_FOUND",
+                    path: paths.taskConfigPath,
+                    message: `task not found: ${taskId}`,
+                },
+            ],
+        };
+    }
+    const unfinished = await listUnfinishedTransactionDirs(paths.transactionsDir);
+    if (unfinished.length > 0) {
+        const observed = await computeObservedCanonicalHashSafe(repoRoot, taskId);
+        let ref;
+        try {
+            ref = (await readStoredContractRef(paths.contractPath)) ?? undefined;
+        }
+        catch (error) {
+            errors.push({
+                code: "INVALID_CONTRACT_JSON",
+                path: paths.contractPath,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return {
+            ref,
+            effectiveStatus: "transaction-incomplete",
+            observedCanonicalHash: observed.hash ?? undefined,
+            observationErrors: [
+                ...errors,
+                ...unfinished.map((txId) => ({
+                    code: "TRANSACTION_INCOMPLETE",
+                    path: path.join(TRANSACTIONS_DIR_NAME, txId),
+                    message: `unfinished transaction: ${txId}`,
+                })),
+                ...(observed.errors ?? []),
+            ],
+        };
+    }
+    let ref = null;
+    try {
+        ref = await readStoredContractRef(paths.contractPath);
+    }
+    catch (error) {
+        errors.push({
+            code: "INVALID_CONTRACT_JSON",
+            path: paths.contractPath,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const observed = await computeObservedCanonicalHashSafe(repoRoot, taskId);
+    errors.push(...(observed.errors ?? []));
+    if (!ref) {
+        return {
+            effectiveStatus: "legacy-unversioned",
+            observedCanonicalHash: observed.hash ?? undefined,
+            observationErrors: errors,
+        };
+    }
+    if (!observed.hash) {
+        return {
+            ref,
+            effectiveStatus: "externally-modified",
+            observationErrors: [
+                ...errors,
+                {
+                    code: "OBSERVE_FAILED",
+                    message: "unable to compute observed canonical hash",
+                },
+            ],
+        };
+    }
+    if (ref.canonicalHash !== observed.hash) {
+        return {
+            ref,
+            effectiveStatus: "externally-modified",
+            observedCanonicalHash: observed.hash,
+            observationErrors: [
+                ...errors,
+                {
+                    code: "EXTERNALLY_MODIFIED",
+                    message: "on-disk source/task config hash does not match contract.json canonicalHash",
+                },
+            ],
+        };
+    }
+    // Optional: verify source-manifest still matches recorded hash when present.
+    if (ref.sourceHashes.referenceManifestSha256) {
+        const manifest = await readSourceManifest(paths.sourceDir);
+        if (!manifest) {
+            return {
+                ref,
+                effectiveStatus: "externally-modified",
+                observedCanonicalHash: observed.hash,
+                observationErrors: [
+                    ...errors,
+                    {
+                        code: "MANIFEST_MISSING",
+                        path: getSourceManifestPath(paths.sourceDir),
+                        message: "contract records referenceManifestSha256 but source-manifest.json is missing",
+                    },
+                ],
+            };
+        }
+    }
+    return {
+        ref,
+        effectiveStatus: "managed",
+        observedCanonicalHash: observed.hash,
+        observationErrors: errors,
+    };
+}
+async function computeObservedCanonicalHashSafe(repoRoot, taskId) {
+    const errors = [];
+    try {
+        const bytes = await loadObservedTaskBytes(repoRoot, taskId);
+        if (bytes.requirementBytes === null ||
+            bytes.constraintsBytes === null ||
+            bytes.taskConfigSha256 === null) {
+            if (bytes.requirementBytes === null) {
+                errors.push({
+                    code: "MISSING_REQUIREMENT",
+                    path: bytes.requirementPath,
+                    message: `missing ${REQUIREMENT_FILE_NAME}`,
+                });
+            }
+            if (bytes.constraintsBytes === null) {
+                errors.push({
+                    code: "MISSING_CONSTRAINTS",
+                    path: bytes.constraintsPath,
+                    message: `missing ${CONSTRAINTS_FILE_NAME}`,
+                });
+            }
+            if (bytes.taskConfigSha256 === null) {
+                errors.push({
+                    code: "MISSING_TASK_CONFIG",
+                    path: bytes.taskConfigPath,
+                    message: "missing or unreadable task.json",
+                });
+            }
+            return { hash: null, errors };
+        }
+        const sourceHashes = computeSourceHashes({
+            requirementBytes: bytes.requirementBytes,
+            constraintsBytes: bytes.constraintsBytes,
+            referenceManifestBytes: bytes.referenceManifestBytes,
+        });
+        const hash = computeCanonicalHash({
+            sourceHashes,
+            taskConfigSha256: bytes.taskConfigSha256,
+        });
+        return { hash, errors };
+    }
+    catch (error) {
+        errors.push({
+            code: "OBSERVE_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { hash: null, errors };
+    }
+}
+export async function computeObservedCanonicalHash(repoRoot, taskId) {
+    const result = await computeObservedCanonicalHashSafe(repoRoot, taskId);
+    if (!result.hash) {
+        throw new Error(`unable to compute observed canonical hash for ${taskId}: ${result.errors
+            .map((e) => e.message)
+            .join("; ")}`);
+    }
+    return result.hash;
+}
+export function logicalRevisionForState(state) {
+    if (!state.ref)
+        return 0;
+    return state.ref.revision;
+}
+/** Object-form entry point used by DAG generate/revalidate. */
+export async function observeTaskContract(input) {
+    return observeTaskContractState(input.repoRoot, input.taskId);
+}
+export { CONTRACT_FILE_NAME };

package/dist/task/contract/paths.js

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { getTaskPaths } from "../runtime.js";
+import { CONTRACT_JSON_BASENAME, REQUEST_LEDGER_BASENAME, TRANSACTIONS_DIRNAME, } from "./constants.js";
+export function getTaskContractPaths(repoRoot, taskId) {
+    const base = getTaskPaths(repoRoot, taskId);
+    return {
+        taskDir: base.taskDir,
+        taskConfigPath: base.taskConfigPath,
+        sourceDir: base.sourceDir,
+        requirementPath: path.join(base.sourceDir, "需求.md"),
+        constraintsPath: path.join(base.sourceDir, "执行约束.md"),
+        sourceManifestPath: path.join(base.sourceDir, "source-manifest.json"),
+        referencesDir: path.join(base.sourceDir, "references"),
+        contractPath: path.join(base.taskDir, CONTRACT_JSON_BASENAME),
+        transactionsDir: path.join(base.taskDir, TRANSACTIONS_DIRNAME),
+        requestLedgerPath: path.join(base.taskDir, REQUEST_LEDGER_BASENAME),
+        lockPath: path.join(base.taskDir, ".contract.lock"),
+    };
+}

package/dist/task/contract/project.js

@@ -0,0 +1,170 @@
+import { canonicalizePathArray, canonicalizeTextProjection, } from "./canonicalize.js";
+/**
+ * Project Draft → source/需求.md (deterministic template, projectionVersion=1).
+ */
+export function projectRequirementMarkdown(draft) {
+    const lines = [
+        `# 需求：${draft.title}`,
+        "",
+        "## Objective",
+        "",
+        draft.requirement.objective,
+        "",
+        "## Scope",
+        "",
+    ];
+    if (draft.requirement.scope.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const item of draft.requirement.scope) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("", "## Non-goals", "");
+    if (draft.requirement.nonGoals.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const item of draft.requirement.nonGoals) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("", "## Acceptance Criteria", "");
+    for (const ac of draft.requirement.acceptanceCriteria) {
+        lines.push(`- ${ac.id}: ${ac.text}`);
+    }
+    if (draft.assumptions && draft.assumptions.length > 0) {
+        lines.push("", "## Assumptions", "");
+        for (const item of draft.assumptions) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (draft.openQuestions && draft.openQuestions.length > 0) {
+        lines.push("", "## Open Questions", "");
+        for (const item of draft.openQuestions) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (draft.sourceResolutions && draft.sourceResolutions.length > 0) {
+        lines.push("", "## Source Resolutions", "");
+        for (const res of draft.sourceResolutions) {
+            lines.push(`- ${res.sourceRef}: ${res.conflict} → ${res.decision} (${res.reason}; decidedBy=${res.decidedBy})`);
+        }
+    }
+    if (draft.references && draft.references.length > 0) {
+        lines.push("", "## References", "");
+        for (const ref of draft.references) {
+            lines.push(`- [${ref.role}] ${ref.ref}`);
+        }
+    }
+    lines.push("");
+    return canonicalizeTextProjection(lines.join("\n"));
+}
+/**
+ * Project Draft → source/执行约束.md.
+ */
+export function projectConstraintsMarkdown(draft) {
+    const lines = [
+        `# 执行约束：${draft.title}`,
+        "",
+        "## Invariants",
+        "",
+    ];
+    const invariants = draft.constraints.invariants.length > 0
+        ? draft.constraints.invariants
+        : draft.hardConstraints ?? [];
+    if (invariants.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const item of invariants) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (draft.constraints.protectedUserChanges &&
+        draft.constraints.protectedUserChanges.length > 0) {
+        lines.push("", "## Protected user changes", "");
+        for (const item of draft.constraints.protectedUserChanges) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("", "## Allowed paths", "");
+    if (draft.constraints.allowedPaths.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const item of draft.constraints.allowedPaths) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("", "## Forbidden paths", "");
+    if (draft.constraints.forbiddenPaths.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const item of draft.constraints.forbiddenPaths) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("", "## Expected verification", "");
+    if (draft.verification.commands.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const cmd of draft.verification.commands) {
+            const timeout = cmd.timeoutMs !== undefined ? ` (timeoutMs=${cmd.timeoutMs})` : "";
+            lines.push(`- ${cmd.label}: \`${cmd.command}\`${timeout}`);
+        }
+    }
+    if (draft.constraints.failureConditions &&
+        draft.constraints.failureConditions.length > 0) {
+        lines.push("", "## Failure conditions", "");
+        for (const item of draft.constraints.failureConditions) {
+            lines.push(`- ${item}`);
+        }
+    }
+    if (draft.constraints.knownRisks && draft.constraints.knownRisks.length > 0) {
+        lines.push("", "## Known risks", "");
+        for (const item of draft.constraints.knownRisks) {
+            lines.push(`- ${item}`);
+        }
+    }
+    lines.push("");
+    return canonicalizeTextProjection(lines.join("\n"));
+}
+/**
+ * Merge managed fields from Draft into existing TaskConfig.
+ * Non-managed fields are preserved byte-for-byte at the object level
+ * (caller still re-serializes via full config schema parse).
+ */
+export function mergeManagedTaskConfigFields(existing, draft) {
+    const hardConstraints = draft.hardConstraints ??
+        (draft.constraints.invariants.length > 0
+            ? draft.constraints.invariants
+            : existing.hardConstraints);
+    const next = {
+        ...existing,
+        title: draft.title,
+        taskKind: draft.taskKind,
+        allowedPaths: canonicalizePathArray(draft.constraints.allowedPaths),
+        forbiddenPaths: canonicalizePathArray(draft.constraints.forbiddenPaths),
+        hardConstraints,
+        verifyCommands: draft.verification.commands.map((cmd) => ({
+            label: cmd.label,
+            command: cmd.command,
+            ...(cmd.timeoutMs !== undefined ? { timeoutMs: cmd.timeoutMs } : {}),
+        })),
+    };
+    if (draft.featureId !== undefined) {
+        next.featureId = draft.featureId;
+    }
+    return next;
+}
+/**
+ * Serialize TaskConfig for on-disk managed write (pretty JSON + trailing newline).
+ * Hashing uses full canonical JSON separately (canonicalizeJsonValue).
+ */
+export function serializeTaskConfigForDisk(config) {
+    return `${JSON.stringify(config, null, 2)}\n`;
+}