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

package/dist/worker/observe/node-transparency.js

@@ -0,0 +1,572 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
+import { effectiveNodeContextV1Schema, } from "../../shared/context-transfer.js";
+import { buildArtifactBindingGraph, } from "../../workflows/dag/artifact-bindings.js";
+import { dagSpecSchema } from "../../workflows/dag/types.js";
+import { isSafeObservabilityIdentifier } from "../observability/event-store.js";
+import { resolveDagRunArtifact, resolveDagRunJson, } from "./dag-run-artifacts.js";
+export const NODE_TRANSPARENCY_SCHEMA_VERSION = 1;
+export const DAG_ARTIFACT_PREVIEW_MAX_BYTES = 64 * 1024;
+function failureForResolution(reason) {
+    if (reason === "invalid-id" || reason === "unsafe-path") {
+        return {
+            status: 400,
+            body: { error: "Invalid or unsafe DAG run identifier", reason },
+        };
+    }
+    if (reason === "ambiguous") {
+        return {
+            status: 409,
+            body: { error: "Ambiguous DAG run lifecycle", reason },
+        };
+    }
+    return { status: 404, body: { error: "DAG run not found", reason } };
+}
+async function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse(await readFile(filePath, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function loadRunFacts(repoRoot, dagRunId) {
+    const resolved = resolveDagRunJson(repoRoot, dagRunId);
+    if (!resolved.ok) {
+        return { ok: false, failure: failureForResolution(resolved.reason) };
+    }
+    const raw = await readJsonObject(resolved.result.absolutePath);
+    if (!raw) {
+        return {
+            ok: false,
+            failure: { status: 422, body: { error: "run.json is unreadable" } },
+        };
+    }
+    const parsed = dagSpecSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            failure: {
+                status: 422,
+                body: { error: "run.json does not satisfy the frozen DAG schema" },
+            },
+        };
+    }
+    const state = await readJsonObject(`${resolved.result.runDir}/state.json`);
+    return {
+        ok: true,
+        facts: {
+            lifecycle: resolved.result.lifecycle,
+            runDir: resolved.result.runDir,
+            spec: parsed.data,
+            state,
+        },
+    };
+}
+function stateNode(state, nodeId) {
+    const nodes = state?.nodes;
+    if (!nodes || typeof nodes !== "object" || Array.isArray(nodes))
+        return null;
+    const node = nodes[nodeId];
+    return node && typeof node === "object" && !Array.isArray(node)
+        ? node
+        : null;
+}
+function normalizedAttempt(rawAttempt, node) {
+    if (Number.isSafeInteger(rawAttempt) && (rawAttempt ?? 0) > 0)
+        return rawAttempt;
+    const current = node?.currentAttempt;
+    if (typeof current === "number" &&
+        Number.isSafeInteger(current) &&
+        current > 0) {
+        return current;
+    }
+    const attempts = node?.attempts;
+    return Array.isArray(attempts) && attempts.length > 0 ? attempts.length : 1;
+}
+function nodeStatus(node) {
+    return typeof node?.status === "string" ? node.status : null;
+}
+function wasDispatched(node) {
+    const status = nodeStatus(node)?.toUpperCase();
+    return Boolean((status && !["PENDING", "READY", "BLOCKED"].includes(status)) ||
+        typeof node?.startedAt === "string" ||
+        typeof node?.currentAttempt === "number");
+}
+export async function loadDagNodeContextSummary(repoRoot, dagRunId, nodeId, attempt) {
+    if (!isSafeObservabilityIdentifier(nodeId)) {
+        return {
+            status: 400,
+            body: { error: "Invalid node identifier", reason: "invalid-id" },
+        };
+    }
+    const loaded = await loadRunFacts(repoRoot, dagRunId);
+    if (!loaded.ok)
+        return loaded.failure;
+    const task = loaded.facts.spec.tasks.find((candidate) => candidate.id === nodeId);
+    if (!task) {
+        return {
+            status: 404,
+            body: { error: "DAG node not found", reason: "not-found" },
+        };
+    }
+    const runtimeNode = stateNode(loaded.facts.state, nodeId);
+    const selectedAttempt = normalizedAttempt(attempt, runtimeNode);
+    const receiptSegments = [
+        nodeId,
+        "context-receipts",
+        `attempt-${selectedAttempt}.json`,
+    ];
+    const receiptArtifact = receiptSegments.join("/");
+    const receiptResolved = resolveDagRunArtifact(repoRoot, dagRunId, receiptSegments);
+    let effectiveContext;
+    if (!receiptResolved.ok) {
+        effectiveContext = {
+            status: "not-captured",
+            reasonCode: "CONTEXT_RECEIPT_MISSING",
+            receiptArtifact,
+        };
+    }
+    else {
+        const rawReceipt = await readJsonObject(receiptResolved.result.absolutePath);
+        const parsedReceipt = effectiveNodeContextV1Schema.safeParse(rawReceipt);
+        if (!parsedReceipt.success ||
+            parsedReceipt.data.identity.runId !== dagRunId ||
+            parsedReceipt.data.identity.nodeId !== nodeId ||
+            parsedReceipt.data.identity.attempt !== selectedAttempt) {
+            effectiveContext = {
+                status: "invalid",
+                reasonCode: "CONTEXT_COMPONENT_UNAVAILABLE",
+                receiptArtifact,
+            };
+        }
+        else {
+            const receipt = parsedReceipt.data;
+            const componentKinds = {};
+            const inclusionCounts = {};
+            for (const component of receipt.orderedComponents) {
+                componentKinds[component.kind] =
+                    (componentKinds[component.kind] ?? 0) + 1;
+                inclusionCounts[component.inclusion] =
+                    (inclusionCounts[component.inclusion] ?? 0) + 1;
+            }
+            effectiveContext = {
+                status: "captured",
+                contextDigest: receipt.contextDigest,
+                capturedAt: receipt.identity.capturedAt,
+                componentCount: receipt.orderedComponents.length,
+                componentKinds,
+                inclusionCounts,
+                truncationCount: receipt.promptAssembly.truncations.length,
+                runtime: {
+                    executor: receipt.runtime.executor,
+                    model: receipt.runtime.resolvedModel ?? receipt.runtime.modelHint ?? null,
+                    skillCount: receipt.runtime.skills.length,
+                    extensionCount: receipt.runtime.extensions.length,
+                    toolCount: receipt.runtime.activeTools.length,
+                },
+            };
+        }
+    }
+    return {
+        status: 200,
+        body: {
+            schemaVersion: NODE_TRANSPARENCY_SCHEMA_VERSION,
+            dagRunId,
+            nodeId,
+            attempt: selectedAttempt,
+            declared: { status: "available", source: "frozen-run-spec" },
+            dispatched: {
+                status: wasDispatched(runtimeNode) ? "dispatched" : "not-dispatched",
+                nodeStatus: nodeStatus(runtimeNode),
+            },
+            effectiveContext,
+        },
+    };
+}
+async function loadNodeRecord(repoRoot, dagRunId, nodeId) {
+    const resolved = resolveDagRunArtifact(repoRoot, dagRunId, [
+        `${nodeId}.json`,
+    ]);
+    return resolved.ok ? readJsonObject(resolved.result.absolutePath) : null;
+}
+function declaredArtifactFacts(record) {
+    const facts = new Map();
+    for (const value of Array.isArray(record?.declaredArtifacts)
+        ? record.declaredArtifacts
+        : []) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        const fact = value;
+        if (typeof fact.artifactId === "string")
+            facts.set(fact.artifactId, fact);
+    }
+    return facts;
+}
+function projectOrigin(record, runtimeNode) {
+    const raw = record?.origin ?? runtimeNode?.origin;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const origin = raw;
+        if (origin.kind === "imported") {
+            return {
+                kind: "imported",
+                ...(typeof origin.parentRunId === "string"
+                    ? { parentRunId: origin.parentRunId }
+                    : {}),
+            };
+        }
+        if (origin.kind === "executed")
+            return { kind: "executed" };
+    }
+    if (!record && !wasDispatched(runtimeNode))
+        return { kind: "pending" };
+    return { kind: "unknown" };
+}
+export async function loadDagNodeArtifactInventory(repoRoot, dagRunId, nodeId) {
+    if (!isSafeObservabilityIdentifier(nodeId)) {
+        return {
+            status: 400,
+            body: { error: "Invalid node identifier", reason: "invalid-id" },
+        };
+    }
+    const loaded = await loadRunFacts(repoRoot, dagRunId);
+    if (!loaded.ok)
+        return loaded.failure;
+    const task = loaded.facts.spec.tasks.find((candidate) => candidate.id === nodeId);
+    if (!task) {
+        return {
+            status: 404,
+            body: { error: "DAG node not found", reason: "not-found" },
+        };
+    }
+    const graph = buildArtifactBindingGraph(loaded.facts.spec);
+    const byId = new Map(graph.artifacts.map((artifact) => [artifact.artifactId, artifact]));
+    const record = await loadNodeRecord(repoRoot, dagRunId, nodeId);
+    const materialized = declaredArtifactFacts(record);
+    const produces = graph.artifacts
+        .filter((artifact) => artifact.producerNodeId === nodeId)
+        .map((artifact) => {
+        const fact = materialized.get(artifact.artifactId);
+        const status = fact?.status === "materialized" ||
+            fact?.status === "missing" ||
+            fact?.status === "mismatch"
+            ? fact.status
+            : "not-recorded";
+        const runtimeEligible = status === "materialized" && fact?.revisionEligible === true;
+        const factOrigin = fact?.origin && typeof fact.origin === "object" && !Array.isArray(fact.origin)
+            ? fact.origin
+            : undefined;
+        return {
+            artifactId: artifact.artifactId,
+            kind: artifact.kind,
+            path: artifact.path,
+            mediaType: artifact.mediaType,
+            ...(artifact.schemaId ? { schemaId: artifact.schemaId } : {}),
+            revisionPolicy: artifact.revisionPolicy,
+            directConsumerNodeIds: artifact.directConsumerNodeIds,
+            materialization: {
+                status,
+                ...(typeof fact?.sha256 === "string" ? { sha256: fact.sha256 } : {}),
+                ...(typeof fact?.bytes === "number" ? { bytes: fact.bytes } : {}),
+                ...(typeof fact?.reasonCode === "string"
+                    ? { reasonCode: fact.reasonCode }
+                    : {}),
+            },
+            revision: {
+                eligible: runtimeEligible,
+                ...(!runtimeEligible
+                    ? {
+                        reasonCode: artifact.revisionPolicy !== "replace-file"
+                            ? "ARTIFACT_NOT_REVISION_ELIGIBLE"
+                            : typeof fact?.reasonCode === "string"
+                                ? fact.reasonCode
+                                : "ARTIFACT_NOT_MATERIALIZED",
+                    }
+                    : {}),
+            },
+            ...(factOrigin && ["executed", "imported", "overridden"].includes(String(factOrigin.kind))
+                ? {
+                    origin: {
+                        kind: factOrigin.kind,
+                        ...(typeof factOrigin.parentRunId === "string"
+                            ? { parentRunId: factOrigin.parentRunId }
+                            : {}),
+                        ...(typeof factOrigin.revisionId === "string"
+                            ? { revisionId: factOrigin.revisionId }
+                            : {}),
+                        ...(typeof factOrigin.supersedes === "string"
+                            ? { supersedes: factOrigin.supersedes }
+                            : {}),
+                    },
+                }
+                : {}),
+        };
+    });
+    const consumes = (task.consumesArtifacts ?? []).flatMap((binding) => {
+        const artifact = byId.get(binding.artifactId);
+        return artifact
+            ? [
+                {
+                    artifactId: binding.artifactId,
+                    required: binding.required,
+                    producerNodeId: artifact.producerNodeId,
+                    path: artifact.path,
+                    mediaType: artifact.mediaType,
+                    ...(artifact.schemaId ? { schemaId: artifact.schemaId } : {}),
+                },
+            ]
+            : [];
+    });
+    return {
+        status: 200,
+        body: {
+            schemaVersion: NODE_TRANSPARENCY_SCHEMA_VERSION,
+            dagRunId,
+            nodeId,
+            binding: {
+                available: graph.available,
+                ...(graph.reasonCode ? { reasonCode: graph.reasonCode } : {}),
+                artifactGraphSha256: graph.artifactGraphSha256,
+            },
+            origin: projectOrigin(record, stateNode(loaded.facts.state, nodeId)),
+            produces,
+            consumes,
+        },
+    };
+}
+function isTextPreviewMediaType(mediaType) {
+    const normalized = mediaType.toLowerCase().split(";", 1)[0]?.trim() ?? "";
+    return normalized.startsWith("text/") || [
+        "application/json",
+        "application/ld+json",
+        "application/x-ndjson",
+        "application/xml",
+        "application/yaml",
+        "application/x-yaml",
+        "application/toml",
+        "application/javascript",
+        "application/sql",
+    ].includes(normalized) || normalized.endsWith("+json") || normalized.endsWith("+xml");
+}
+function isInsideDirectory(root, candidate) {
+    const normalizedRoot = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+    return candidate.startsWith(normalizedRoot);
+}
+export async function loadDagNodeArtifactPreview(repoRoot, dagRunId, nodeId, artifactId) {
+    if (!isSafeObservabilityIdentifier(nodeId) || !isSafeObservabilityIdentifier(artifactId)) {
+        return {
+            status: 400,
+            body: { error: "Invalid node or artifact identifier", reason: "invalid-id" },
+        };
+    }
+    const loaded = await loadRunFacts(repoRoot, dagRunId);
+    if (!loaded.ok)
+        return loaded.failure;
+    const task = loaded.facts.spec.tasks.find((candidate) => candidate.id === nodeId);
+    if (!task) {
+        return {
+            status: 404,
+            body: { error: "DAG node not found", reason: "not-found" },
+        };
+    }
+    const graph = buildArtifactBindingGraph(loaded.facts.spec);
+    if (!graph.available) {
+        return {
+            status: 422,
+            body: {
+                error: "Artifact preview requires frozen artifact bindings",
+                reason: graph.reasonCode ?? "ARTIFACT_BINDING_UNAVAILABLE",
+            },
+        };
+    }
+    const artifact = graph.artifacts.find((candidate) => candidate.artifactId === artifactId);
+    const isVisibleToNode = artifact && (artifact.producerNodeId === nodeId ||
+        (task.consumesArtifacts ?? []).some((binding) => binding.artifactId === artifactId));
+    if (!artifact || !isVisibleToNode) {
+        return {
+            status: 404,
+            body: { error: "Artifact is not bound to this node", reason: "not-found" },
+        };
+    }
+    const producerRecord = await loadNodeRecord(repoRoot, dagRunId, artifact.producerNodeId);
+    const fact = declaredArtifactFacts(producerRecord).get(artifactId);
+    if (fact?.status !== "materialized" || typeof fact.sha256 !== "string") {
+        return {
+            status: 404,
+            body: {
+                error: "Artifact file has not been materialized",
+                reason: typeof fact?.reasonCode === "string"
+                    ? fact.reasonCode
+                    : "ARTIFACT_NOT_MATERIALIZED",
+            },
+        };
+    }
+    const resolved = resolveDagRunArtifact(repoRoot, dagRunId, artifact.path.split("/").filter(Boolean));
+    if (!resolved.ok)
+        return failureForResolution(resolved.reason);
+    try {
+        const [runRoot, artifactRealPath, fileStat] = await Promise.all([
+            realpath(resolved.result.runDir),
+            realpath(resolved.result.absolutePath),
+            lstat(resolved.result.absolutePath),
+        ]);
+        if (!isInsideDirectory(runRoot, artifactRealPath) ||
+            !fileStat.isFile() ||
+            fileStat.isSymbolicLink() ||
+            fileStat.nlink !== 1) {
+            return {
+                status: 422,
+                body: { error: "Artifact is not a safe regular file", reason: "unsafe-path" },
+            };
+        }
+        const bytes = await readFile(artifactRealPath);
+        const actualSha256 = createHash("sha256").update(bytes).digest("hex");
+        if (actualSha256 !== fact.sha256 ||
+            (typeof fact.bytes === "number" && fact.bytes !== bytes.byteLength)) {
+            return {
+                status: 422,
+                body: {
+                    error: "Artifact bytes no longer match the recorded materialization",
+                    reason: "ARTIFACT_HASH_MISMATCH",
+                },
+            };
+        }
+        if (!isTextPreviewMediaType(artifact.mediaType)) {
+            return {
+                status: 200,
+                body: {
+                    schemaVersion: NODE_TRANSPARENCY_SCHEMA_VERSION,
+                    dagRunId,
+                    nodeId,
+                    producerNodeId: artifact.producerNodeId,
+                    artifactId,
+                    path: artifact.path,
+                    mediaType: artifact.mediaType,
+                    kind: artifact.kind,
+                    sha256: actualSha256,
+                    sourceBytes: bytes.byteLength,
+                    maxBytes: DAG_ARTIFACT_PREVIEW_MAX_BYTES,
+                    previewKind: "unsupported",
+                    content: null,
+                    truncated: false,
+                    redacted: false,
+                },
+            };
+        }
+        const raw = bytes.toString("utf8");
+        const redacted = redactSecrets(raw);
+        const content = truncateUtf8Preview(redacted, DAG_ARTIFACT_PREVIEW_MAX_BYTES);
+        return {
+            status: 200,
+            body: {
+                schemaVersion: NODE_TRANSPARENCY_SCHEMA_VERSION,
+                dagRunId,
+                nodeId,
+                producerNodeId: artifact.producerNodeId,
+                artifactId,
+                path: artifact.path,
+                mediaType: artifact.mediaType,
+                kind: artifact.kind,
+                sha256: actualSha256,
+                sourceBytes: bytes.byteLength,
+                maxBytes: DAG_ARTIFACT_PREVIEW_MAX_BYTES,
+                previewKind: "text",
+                content,
+                truncated: content !== redacted,
+                redacted: redacted !== raw,
+            },
+        };
+    }
+    catch {
+        return {
+            status: 404,
+            body: { error: "Artifact file is unavailable", reason: "not-found" },
+        };
+    }
+}
+function stringField(value, key) {
+    return typeof value?.[key] === "string" ? value[key] : undefined;
+}
+export async function loadDagRunLineage(repoRoot, dagRunId) {
+    const loaded = await loadRunFacts(repoRoot, dagRunId);
+    if (!loaded.ok)
+        return loaded.failure;
+    const continuationRaw = loaded.facts.state?.continuation;
+    const continuation = continuationRaw &&
+        typeof continuationRaw === "object" &&
+        !Array.isArray(continuationRaw)
+        ? continuationRaw
+        : null;
+    const importResolved = resolveDagRunArtifact(repoRoot, dagRunId, [
+        ".runtime",
+        "import-manifest.json",
+    ]);
+    const importManifest = importResolved.ok
+        ? await readJsonObject(importResolved.result.absolutePath)
+        : null;
+    const importedNodeIds = (Array.isArray(importManifest?.nodes) ? importManifest.nodes : [])
+        .flatMap((entry) => entry &&
+        typeof entry === "object" &&
+        !Array.isArray(entry) &&
+        typeof entry.nodeId === "string"
+        ? [entry.nodeId]
+        : [])
+        .sort();
+    const rerunResolved = resolveDagRunArtifact(repoRoot, dagRunId, [
+        ".runtime",
+        "rerun-plan.json",
+    ]);
+    const rerunPlan = rerunResolved.ok
+        ? await readJsonObject(rerunResolved.result.absolutePath)
+        : null;
+    const promptOverriddenNodeIds = (Array.isArray(rerunPlan?.promptOverrides) ? rerunPlan.promptOverrides : [])
+        .flatMap((entry) => entry &&
+        typeof entry === "object" &&
+        !Array.isArray(entry) &&
+        typeof entry.nodeId === "string"
+        ? [entry.nodeId]
+        : [])
+        .sort();
+    const artifactOverriddenNodeIds = (Array.isArray(importManifest?.overrides) ? importManifest.overrides : []).flatMap((entry) => entry &&
+        typeof entry === "object" &&
+        !Array.isArray(entry) &&
+        typeof entry.producerNodeId === "string"
+        ? [entry.producerNodeId]
+        : []);
+    const overriddenNodeIds = [
+        ...new Set([...promptOverriddenNodeIds, ...artifactOverriddenNodeIds]),
+    ].sort();
+    const parentRunId = stringField(continuation, "parentRunId");
+    return {
+        status: 200,
+        body: {
+            schemaVersion: NODE_TRANSPARENCY_SCHEMA_VERSION,
+            dagRunId,
+            kind: parentRunId ? "continuation" : "root",
+            ...(parentRunId ? { parentRunId } : {}),
+            ...(stringField(rerunPlan, "trigger")
+                ? { trigger: stringField(rerunPlan, "trigger") }
+                : {}),
+            ...(stringField(continuation, "operatorSelectedNodeId")
+                ? {
+                    operatorSelectedNodeId: stringField(continuation, "operatorSelectedNodeId"),
+                }
+                : {}),
+            ...(stringField(continuation, "effectiveFromNodeId")
+                ? {
+                    effectiveFromNodeId: stringField(continuation, "effectiveFromNodeId"),
+                }
+                : {}),
+            ...(stringField(rerunPlan, "planHash")
+                ? { planHash: stringField(rerunPlan, "planHash") }
+                : {}),
+            importedNodeIds,
+            overriddenNodeIds,
+        },
+    };
+}

package/dist/worker/observe/routes.js

@@ -14,13 +14,14 @@ import { dagSourceBindingSchema } from "../../workflows/dag/types.js";
 import { getTaskPaths } from "../../task/runtime.js";
 import { classifyLedgerGate, computeLedgerInputDigest, LedgerParseError, parseLedgerJson, recoverLedgerInputContract, summarizeLedger, } from "../../task/source-prepare/ledger.js";
 import { getTaskPoolRoot } from "../pool/run-store.js";
-import { resolveDagRunArtifact, } from "./dag-run-artifacts.js";
+import { resolveDagRunArtifact } from "./dag-run-artifacts.js";
 import { frontendPrewriteResultV1Schema } from "../../workflows/dag/frontend-prewrite-gate.js";
 import { isAllowedArtifactTextPath, resolveArtifactPath, resolveRepoFilePreview, toRepoRelativeArtifactPath, } from "./paths.js";
 import { extractSpecEvidence, extractSpecReadContent, } from "./spec-evidence.js";
 import { buildDagNodeInput } from "./node-input.js";
 import { loadDagNodeExecutionOutput } from "./dag-node-execution-output.js";
 import { loadDagNodeProcess } from "./node-process.js";
+import { loadDagNodeArtifactInventory, loadDagNodeArtifactPreview, loadDagNodeContextSummary, loadDagRunLineage, } from "./node-transparency.js";
 import { buildObserveHealthV1 } from "./health.js";
 import { buildNightJobDetail, buildNightJobsDoctor, buildNightJobsList, buildNightJobsMorning, } from "./night-jobs.js";
 const ARTIFACT_PREVIEW_MAX_BYTES = 64 * 1024;
@@ -109,6 +110,21 @@ export const ROUTES = [
         pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/input$/,
         handler: handleDagNodeInput,
     },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/context$/,
+        handler: handleDagNodeContext,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/artifacts\/preview$/,
+        handler: handleDagNodeArtifactPreview,
+    },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/artifacts$/,
+        handler: handleDagNodeArtifacts,
+    },
     {
         method: "GET",
         pattern: /^\/api\/dag-runs\/([^/]+)\/nodes\/([^/]+)\/execution-output$/,
@@ -139,6 +155,11 @@ export const ROUTES = [
         pattern: /^\/api\/dag-runs\/([^/]+)\/prewrite-result$/,
         handler: handleDagRunPrewriteResult,
     },
+    {
+        method: "GET",
+        pattern: /^\/api\/dag-runs\/([^/]+)\/lineage$/,
+        handler: handleDagRunLineage,
+    },
     {
         method: "GET",
         pattern: /^\/api\/dag-runs\/([^/]+)$/,
@@ -754,6 +775,35 @@ async function handleDagNodeInput(_req, res, match, ctx) {
     const result = await buildDagNodeInput(ctx.repoRoot, dagRunId, nodeId);
     sendJson(res, result.status, result.body);
 }
+async function handleDagNodeContext(_req, res, match, ctx) {
+    const attemptRaw = match.query.get("attempt");
+    let attempt;
+    if (attemptRaw != null) {
+        attempt = Number(attemptRaw);
+        if (!Number.isSafeInteger(attempt) || attempt < 1) {
+            sendJson(res, 400, {
+                error: "attempt must be a positive integer",
+                reason: "invalid-attempt",
+            });
+            return;
+        }
+    }
+    const result = await loadDagNodeContextSummary(ctx.repoRoot, match.params.id, match.params.sub, attempt);
+    sendJson(res, result.status, result.body);
+}
+async function handleDagNodeArtifacts(_req, res, match, ctx) {
+    const result = await loadDagNodeArtifactInventory(ctx.repoRoot, match.params.id, match.params.sub);
+    sendJson(res, result.status, result.body);
+}
+async function handleDagNodeArtifactPreview(_req, res, match, ctx) {
+    const artifactId = match.query.get("artifactId") ?? "";
+    const result = await loadDagNodeArtifactPreview(ctx.repoRoot, match.params.id, match.params.sub, artifactId);
+    sendJson(res, result.status, result.body);
+}
+async function handleDagRunLineage(_req, res, match, ctx) {
+    const result = await loadDagRunLineage(ctx.repoRoot, match.params.id);
+    sendJson(res, result.status, result.body);
+}
 /**
  * Read-only execution body by attempt-N / pass-N key only.
  * Clients must never submit artifact paths; server maps key → run-dir segments.