@tea-agent/loop-agent 0.41.1-beta.0 → 0.42.0-next.2

package/dist/workflows/dag/context-receipt.js

@@ -0,0 +1,305 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { computeContextDigest, effectiveNodeContextV1Schema, } from "../../shared/context-transfer.js";
+import { writeDagNodeBufferArtifact, writeDagNodeJsonArtifact, writeDagNodeTextArtifact, } from "../../infrastructure/harness/artifact-store.js";
+import { resolveDagTaskSourcePath } from "../../task/dag-source-paths.js";
+import { getTaskPaths } from "../../task/runtime.js";
+import { readStoredContractRef } from "../../task/contract/observe.js";
+import { computeCanonicalHash } from "../../task/contract/hash.js";
+import { readFileBoundarySafe } from "./path-safety.js";
+const CONTEXT_FACT_WRITE_OPTIONS = Object.freeze({
+    mode: 0o600,
+    directoryMode: 0o700,
+});
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function sourceDocumentMediaType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".md" || ext === ".markdown") {
+        return "text/markdown; charset=utf-8";
+    }
+    if (ext === ".txt")
+        return "text/plain; charset=utf-8";
+    if (ext === ".json")
+        return "application/json";
+    return "application/octet-stream";
+}
+/**
+ * Managed Task Contract facts, materialized so a portable bundle can verify
+ * the canonical hash without the run directory. The material carries the full
+ * canonical-hash material (including the source hashes the canonical hash is
+ * computed from), so a bundle consumer can recompute `computeCanonicalHash`
+ * and compare it against the recorded canonicalHash — the JSON is no longer a
+ * self-describing blob. The contract prose itself is not re-inlined here: it
+ * reached the model through the assembled system prompt (component 0), and
+ * declared sources below carry the per-document provenance.
+ */
+async function captureTaskContractComponent(input, materialRoot) {
+    const binding = input.spec?.taskContractBinding;
+    if (!binding)
+        return null;
+    if (!input.repoRoot) {
+        throw new Error("context receipt requires repoRoot to verify managed task contract");
+    }
+    const contractPath = getTaskPaths(path.resolve(input.repoRoot), binding.taskId).contractPath;
+    const ref = await readStoredContractRef(contractPath);
+    if (!ref) {
+        throw new Error(`context task contract unavailable: ${binding.taskId} (no stored contract.json)`);
+    }
+    if (ref.canonicalHash !== binding.canonicalHash) {
+        throw new Error(`context task contract drift: ${binding.taskId}`);
+    }
+    const material = {
+        schemaVersion: binding.schemaVersion,
+        taskId: binding.taskId,
+        revision: binding.revision,
+        projectionVersion: binding.projectionVersion,
+        canonicalizerVersion: binding.canonicalizerVersion,
+        taskConfigSchemaVersion: binding.taskConfigSchemaVersion,
+        sourceHashes: ref.sourceHashes,
+        taskConfigSha256: binding.taskConfigSha256,
+        canonicalHash: binding.canonicalHash,
+    };
+    const recomputed = computeCanonicalHash({
+        sourceHashes: material.sourceHashes,
+        taskConfigSha256: material.taskConfigSha256,
+        projectionVersion: binding.projectionVersion,
+        canonicalizerVersion: binding.canonicalizerVersion,
+        taskConfigSchemaVersion: binding.taskConfigSchemaVersion,
+    });
+    if (recomputed !== binding.canonicalHash) {
+        throw new Error(`context task contract canonical hash mismatch: ${binding.taskId}`);
+    }
+    const materialBytes = Buffer.from(`${JSON.stringify(material, null, 2)}\n`, "utf8");
+    const materializedPath = `${input.nodeId}/${materialRoot}/task-contract-binding.json`;
+    await writeDagNodeBufferArtifact(input.runDir, input.nodeId, `${materialRoot}/task-contract-binding.json`, materialBytes, CONTEXT_FACT_WRITE_OPTIONS);
+    return {
+        kind: "task-contract",
+        logicalName: "managed-task-contract",
+        source: {
+            type: "managed-task-contract-binding",
+            identity: "run.json#taskContractBinding",
+            revision: binding.canonicalHash,
+        },
+        materializedPath,
+        sha256: createHash("sha256").update(materialBytes).digest("hex"),
+        bytes: materialBytes.byteLength,
+        mediaType: "application/json",
+        inclusion: "full",
+        authoritativeSource: {
+            identity: "run.json#taskContractBinding",
+            sha256: binding.canonicalHash,
+        },
+    };
+}
+/**
+ * Declared source bindings are contract-level provenance facts, NOT model
+ * inputs: at dispatch only the assembled system prompt and user message are
+ * sent (dag-pi-executor attaches no files). Their prose is embedded into the
+ * system prompt during prompt assembly. Components are therefore recorded as
+ * reference-only with hash-verified integrity (drift fails closed) and paths
+ * resolved through the authoritative task-source boundary — never as
+ * full/excerpt "effective context".
+ */
+async function captureSourceContextComponents(input, _materialRoot, startIndex) {
+    const binding = input.spec?.sourceBinding;
+    if (!binding || binding.sources.length === 0) {
+        return { components: [], truncations: [] };
+    }
+    if (!input.repoRoot) {
+        throw new Error("context receipt requires repoRoot to verify declared source documents");
+    }
+    const components = [];
+    const truncations = [];
+    for (let i = 0; i < binding.sources.length; i += 1) {
+        const declared = binding.sources[i];
+        const sourcePath = resolveDagTaskSourcePath({
+            workspaceRoot: path.resolve(input.repoRoot),
+            taskId: binding.taskId,
+            sourcePath: declared.path,
+        });
+        const sourceDir = getTaskPaths(path.resolve(input.repoRoot), binding.taskId).sourceDir;
+        const sourceBytes = await readFileBoundarySafe({
+            boundaryRoot: sourceDir,
+            targetPath: sourcePath,
+            label: `context source ${declared.path}`,
+        });
+        const sourceSha256 = createHash("sha256").update(sourceBytes).digest("hex");
+        if (sourceSha256 !== declared.sha256) {
+            throw new Error(`context source drift detected: ${declared.path}`);
+        }
+        components.push({
+            kind: declared.kind === "constraint" ? "execution-constraint" : "context-file",
+            logicalName: declared.path,
+            source: {
+                type: "declared-source-binding",
+                identity: `run.json#sourceBinding/sources/${String(i)}`,
+                revision: declared.sha256,
+            },
+            sha256: sourceSha256,
+            bytes: sourceBytes.byteLength,
+            mediaType: sourceDocumentMediaType(declared.path),
+            inclusion: "reference-only",
+            authoritativeSource: {
+                identity: declared.path,
+                sha256: sourceSha256,
+            },
+            omissionReason: "declared source is contract provenance; its prose was embedded into the assembled system prompt at dispatch and the bytes are not copied into the v1 receipt",
+        });
+    }
+    return { components, truncations };
+}
+async function captureConsumedArtifactComponents(input, _materialRoot, _startIndex) {
+    if (!input.spec || (input.task.consumesArtifacts?.length ?? 0) === 0) {
+        return { components: [], truncations: [] };
+    }
+    const components = [];
+    const resolvedRunDir = path.resolve(input.runDir);
+    for (const binding of input.task.consumesArtifacts ?? []) {
+        const producers = input.spec.tasks.flatMap((task) => (task.producesArtifacts ?? [])
+            .filter((artifact) => artifact.artifactId === binding.artifactId)
+            .map((artifact) => ({ task, artifact })));
+        if (producers.length !== 1) {
+            if (binding.required) {
+                throw new Error(`context artifact binding unavailable: ${binding.artifactId}`);
+            }
+            continue;
+        }
+        const producer = producers[0];
+        const sourcePath = path.resolve(resolvedRunDir, ...producer.artifact.path.split("/"));
+        const sourceBytes = await readFileBoundarySafe({
+            boundaryRoot: resolvedRunDir,
+            targetPath: sourcePath,
+            label: `context artifact ${binding.artifactId}`,
+        }).catch(async (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/missing|no such|ENOENT|not found/i.test(message) && !binding.required) {
+                return undefined;
+            }
+            throw error;
+        });
+        if (sourceBytes === undefined)
+            continue;
+        const sourceSha256 = createHash("sha256").update(sourceBytes).digest("hex");
+        components.push({
+            kind: "upstream-artifact",
+            logicalName: binding.artifactId,
+            source: {
+                type: "frozen-artifact-binding",
+                identity: `run.json#tasks/${producer.task.id}/producesArtifacts/${binding.artifactId}`,
+                revision: sourceSha256,
+            },
+            sha256: sourceSha256,
+            bytes: sourceBytes.byteLength,
+            mediaType: producer.artifact.mediaType,
+            inclusion: "reference-only",
+            authoritativeSource: {
+                identity: `${producer.task.id}:${producer.artifact.path}`,
+                sha256: sourceSha256,
+            },
+            omissionReason: "upstream artifact is dispatched as a read-tool pointer (path + sha256 + use-read instruction), not as inline content; the consumer must read it through the frozen binding and the bytes are not copied into the v1 receipt",
+        });
+    }
+    return { components, truncations: [] };
+}
+/**
+ * Persist the exact Pi dispatch messages before the provider is called. Material
+ * bytes are committed first and the validated receipt last, so a crash can only
+ * leave an ignorable partial material directory — never a receipt that points at
+ * missing bytes.
+ */
+export async function writeEffectiveContextReceipt(input) {
+    if (!Number.isSafeInteger(input.attempt) || input.attempt < 1) {
+        throw new Error("context receipt attempt must be a positive integer");
+    }
+    const materialRoot = `context-materials/attempt-${input.attempt}`;
+    const systemPath = `${input.nodeId}/${materialRoot}/system-prompt.md`;
+    const userPath = `${input.nodeId}/${materialRoot}/user-message.md`;
+    await writeDagNodeTextArtifact(input.runDir, input.nodeId, `${materialRoot}/system-prompt.md`, input.systemPrompt, CONTEXT_FACT_WRITE_OPTIONS);
+    await writeDagNodeTextArtifact(input.runDir, input.nodeId, `${materialRoot}/user-message.md`, input.userMessage, CONTEXT_FACT_WRITE_OPTIONS);
+    const taskContractComponent = await captureTaskContractComponent(input, materialRoot);
+    const sourceCapture = await captureSourceContextComponents(input, materialRoot, 2 + (taskContractComponent ? 1 : 0));
+    const upstreamCapture = await captureConsumedArtifactComponents(input, materialRoot, 2 +
+        (taskContractComponent ? 1 : 0) +
+        sourceCapture.components.length);
+    const extraComponents = [
+        ...(taskContractComponent ? [taskContractComponent] : []),
+        ...sourceCapture.components,
+        ...upstreamCapture.components,
+    ];
+    const truncations = [
+        ...sourceCapture.truncations,
+        ...upstreamCapture.truncations,
+    ];
+    const contextWithoutDigest = {
+        schemaVersion: 1,
+        identity: {
+            runId: input.runId,
+            nodeId: input.nodeId,
+            attempt: input.attempt,
+            capturedAt: input.capturedAt ?? new Date().toISOString(),
+        },
+        orderedComponents: [
+            {
+                index: 0,
+                kind: "system-prompt",
+                logicalName: "dag-pi-system-prompt",
+                source: {
+                    type: "assembled-dag-prompt",
+                    identity: `run.json#tasks/${input.nodeId}`,
+                },
+                materializedPath: systemPath,
+                sha256: sha256(input.systemPrompt),
+                bytes: bytes(input.systemPrompt),
+                mediaType: "text/markdown; charset=utf-8",
+                inclusion: "full",
+            },
+            {
+                index: 1,
+                kind: "user-prompt",
+                logicalName: "dag-pi-user-message",
+                source: {
+                    type: "executor-message",
+                    identity: `dag-pi-user-message/${input.nodeId}`,
+                },
+                materializedPath: userPath,
+                sha256: sha256(input.userMessage),
+                bytes: bytes(input.userMessage),
+                mediaType: "text/plain; charset=utf-8",
+                inclusion: "full",
+            },
+            ...extraComponents.map((component, offset) => ({
+                ...component,
+                index: 2 + offset,
+            })),
+        ],
+        promptAssembly: {
+            strategy: "dag-pi-system-plus-user-v1",
+            finalPromptSha256: sha256(input.systemPrompt),
+            truncations,
+        },
+        boundaries: {
+            allowedPaths: [...(input.task.allowedPaths ?? [])],
+            forbiddenPaths: [...(input.task.forbiddenPaths ?? [])],
+            writeSet: [...(input.task.writeSet ?? [])],
+        },
+        runtime: {
+            executor: "pi",
+            resolvedModel: input.resolvedModel,
+            skills: [...input.resolvedSkills],
+            extensions: [...input.resolvedExtensions],
+            activeTools: [...input.activeTools],
+        },
+    };
+    const receipt = effectiveNodeContextV1Schema.parse({
+        ...contextWithoutDigest,
+        contextDigest: computeContextDigest(contextWithoutDigest),
+    });
+    const receiptFile = `context-receipts/attempt-${input.attempt}.json`;
+    const receiptPath = await writeDagNodeJsonArtifact(input.runDir, input.nodeId, receiptFile, receipt, CONTEXT_FACT_WRITE_OPTIONS);
+    return { receipt, receiptPath };
+}