@chenpengfei/daily-brief 0.1.0

package/dist/src/agent/source-grounding-repair.js

@@ -0,0 +1,159 @@
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createStageModelRuntime } from "./model-stage-runtime.js";
+import { runAgentStage } from "./stage-runner.js";
+export async function runSourceGroundingRepairStage(input) {
+    const request = buildRepairRequest(input.brief, input.sourceItems, input.auditFindings);
+    const runtime = createStageModelRuntime({
+        config: input.modelRuntimeConfig,
+        env: input.modelRuntimeEnv ?? process.env,
+        fauxResponse: JSON.stringify(buildFauxRepairOutput(input.brief))
+    });
+    try {
+        const response = await runRepairAgent(request, runtime);
+        const sourceItemIds = input.sourceItems.map((item) => item.id);
+        const signalIds = input.brief.signals.map((signal) => signal.id);
+        const result = await runAgentStage({
+            stage: "repair",
+            artifact: input.artifact,
+            inputRefs: {
+                ...(input.inputRefs ?? {}),
+                sourceItemIds,
+                signalIds,
+                repair: { stage: "audit", findings: input.auditFindings }
+            },
+            validationContext: { sourceItemIds, signalIds },
+            execute: async () => response.text
+        });
+        return {
+            brief: applyRepair(input.brief, result.output),
+            repair: result.output,
+            events: response.events
+        };
+    }
+    finally {
+        runtime.unregister?.();
+    }
+}
+function buildRepairRequest(brief, sourceItems, auditFindings) {
+    return {
+        brief,
+        auditFindings,
+        citedSourceItems: sourceItems.map((item) => ({
+            id: item.id,
+            sourceId: item.sourceId,
+            platform: item.platform,
+            url: item.url,
+            title: item.title,
+            analyzableText: item.analyzableText,
+            ...(item.metadata ? { metadata: item.metadata } : {})
+        }))
+    };
+}
+async function runRepairAgent(request, runtime) {
+    const events = [];
+    const agent = new Agent({
+        initialState: {
+            systemPrompt: [
+                "你是 Daily Brief Agent 的 Source-grounding Repair Stage。",
+                "你只根据 Audit findings 对 brief 做最小必要修改。",
+                "不得引入新事实，不得删除 citation 来逃避问题，不得扩大叙述范围。",
+                "如果某个断言无法被 cited Source Items 支撑，必须改弱、改成集合性表述，或明确写成 Source Item 只表明的范围。",
+                "输出必须是 JSON object，不要 Markdown，不要解释。"
+            ].join("\n"),
+            model: runtime.model,
+            thinkingLevel: runtime.thinkingLevel
+        },
+        sessionId: "daily-brief-source-grounding-repair",
+        ...(runtime.getApiKey ? { getApiKey: runtime.getApiKey } : {})
+    });
+    agent.subscribe((event) => {
+        events.push(`repair:${event.type}`);
+    });
+    await agent.prompt([
+        "请根据 Audit findings 修复 Daily Brief narrative。",
+        "",
+        "JSON schema:",
+        "{",
+        "  \"stage\": \"repair\",",
+        "  \"executiveSummary\": \"可选：修复后的 Executive Summary\",",
+        "  \"signalNarratives\": [",
+        "    {",
+        "      \"signalId\": \"signal id from input\",",
+        "      \"focusAreas\": [\"Agent 架构|AI Coding\"],",
+        "      \"directions\": [\"先进工具|长程任务|持续学习|自我改进|人与 Agent 的边界\"],",
+        "      \"whatItIs\": \"修复后的是什么\",",
+        "      \"whatItIsNot\": \"修复后的不是什么\",",
+        "      \"minimalExample\": \"修复后的最小例子\",",
+        "      \"whyItMatters\": \"修复后的为什么重要\"",
+        "    }",
+        "  ]",
+        "}",
+        "",
+        "修复要求:",
+        "- 只修改 Audit findings 指出的相关 Signal。",
+        "- 保留读者可读性和具体性。",
+        "- 一一映射是允许的，但每个映射都必须被对应 Source Item 直接支撑；不确定时改成集合性或更弱的表述。",
+        "- 修复后仍必须能通过 Source-grounding Audit。",
+        "",
+        "Input:",
+        JSON.stringify(request, null, 2)
+    ].join("\n"));
+    const text = latestAssistantText(agent);
+    if (!text) {
+        throw new Error("Repair Stage did not return text");
+    }
+    return { text, events };
+}
+function buildFauxRepairOutput(brief) {
+    return {
+        stage: "repair",
+        executiveSummary: brief.executiveSummary,
+        signalNarratives: brief.signals.map((signal) => ({
+            signalId: signal.id,
+            focusAreas: signal.focusAreas ?? [],
+            directions: signal.directions ?? [],
+            whatItIs: weakenRiskyMapping(signal.summary.whatItIs),
+            whatItIsNot: signal.summary.whatItIsNot,
+            minimalExample: signal.summary.minimalExample,
+            whyItMatters: signal.whyItMatters
+        }))
+    };
+}
+function weakenRiskyMapping(value) {
+    return value
+        .replace(/分别(?:指向|对应|代表|说明|表明|描述)/g, "共同表明")
+        .replace(/一一对应/g, "共同对应")
+        .replace(/respectively/gi, "collectively");
+}
+function applyRepair(brief, repair) {
+    const bySignalId = new Map(repair.signalNarratives.map((narrative) => [narrative.signalId, narrative]));
+    return {
+        ...brief,
+        ...(repair.executiveSummary ? { executiveSummary: repair.executiveSummary } : {}),
+        signals: brief.signals.map((signal) => {
+            const narrative = bySignalId.get(signal.id);
+            if (!narrative) {
+                return signal;
+            }
+            return {
+                ...signal,
+                focusAreas: narrative.focusAreas,
+                directions: narrative.directions,
+                summary: {
+                    whatItIs: narrative.whatItIs,
+                    whatItIsNot: narrative.whatItIsNot,
+                    minimalExample: narrative.minimalExample
+                },
+                whyItMatters: narrative.whyItMatters
+            };
+        })
+    };
+}
+function latestAssistantText(agent) {
+    const assistantMessage = [...agent.state.messages].reverse().find((message) => message.role === "assistant");
+    const text = assistantMessage?.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("");
+    return text && text.trim().length > 0 ? text.trim() : undefined;
+}

package/dist/src/agent/source-item-understanding.js

@@ -0,0 +1,206 @@
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createStageModelRuntime } from "./model-stage-runtime.js";
+import { runAgentStage } from "./stage-runner.js";
+import { AgentStageValidationError } from "./stage-contracts.js";
+export async function runSourceItemUnderstandingStage(input) {
+    if (input.sourceItems.length === 0) {
+        return { annotations: [], batchCount: 0, events: [] };
+    }
+    const batches = batchSourceItems(input.sourceItems, input.maxBatchCharacters ?? 60_000);
+    const annotations = [];
+    const events = [];
+    for (const [index, batch] of batches.entries()) {
+        const request = buildUnderstandingRequest(batch);
+        const runtime = createStageModelRuntime({
+            config: input.modelRuntimeConfig,
+            env: input.modelRuntimeEnv ?? process.env,
+            fauxResponse: JSON.stringify(buildFauxUnderstandingOutput(request))
+        });
+        try {
+            const response = await runUnderstandingAgent(request, runtime);
+            events.push(...response.events.map((event) => `understanding:${index + 1}/${batches.length}:${event}`));
+            const stage = await runAgentStage({
+                stage: "understanding",
+                artifact: input.artifact ?? createInMemoryArtifact(input.modelRuntimeConfig),
+                inputRefs: {
+                    ...(input.inputRefs ?? {}),
+                    sourceItemIds: batch.map((item) => item.id),
+                    batch: { index: index + 1, total: batches.length }
+                },
+                validationContext: {
+                    sourceItemIds: batch.map((item) => item.id)
+                },
+                execute: async () => response.text
+            });
+            annotations.push(...stage.output.sourceItemAnnotations);
+        }
+        finally {
+            runtime.unregister?.();
+        }
+    }
+    validateMergedAnnotations(input.sourceItems, annotations);
+    return {
+        annotations,
+        batchCount: batches.length,
+        events
+    };
+}
+export function batchSourceItems(sourceItems, maxBatchCharacters) {
+    if (!Number.isFinite(maxBatchCharacters) || maxBatchCharacters <= 0) {
+        throw new Error("maxBatchCharacters must be a positive number");
+    }
+    const batches = [];
+    let current = [];
+    let currentSize = 0;
+    for (const item of sourceItems) {
+        const size = estimateSourceItemSize(item);
+        if (current.length > 0 && currentSize + size > maxBatchCharacters) {
+            batches.push(current);
+            current = [];
+            currentSize = 0;
+        }
+        current.push(item);
+        currentSize += size;
+    }
+    if (current.length > 0) {
+        batches.push(current);
+    }
+    return batches;
+}
+function buildUnderstandingRequest(sourceItems) {
+    return {
+        sourceItems: sourceItems.map((item) => ({
+            id: item.id,
+            sourceId: item.sourceId,
+            platform: item.platform,
+            url: item.url,
+            title: item.title,
+            analyzableText: item.analyzableText,
+            ...(item.metadata ? { metadata: item.metadata } : {})
+        }))
+    };
+}
+async function runUnderstandingAgent(request, runtime) {
+    const events = [];
+    const agent = new Agent({
+        initialState: {
+            systemPrompt: [
+                "你是 Daily Brief Agent 的 Source Item Understanding Stage。",
+                "你只能基于输入 Source Items 生成结构化理解标注。",
+                "不要联网，不要使用工具，不要补充未引用事实。输出必须是 JSON object。"
+            ].join("\n"),
+            model: runtime.model,
+            thinkingLevel: runtime.thinkingLevel
+        },
+        sessionId: "daily-brief-understanding",
+        ...(runtime.getApiKey ? { getApiKey: runtime.getApiKey } : {})
+    });
+    agent.subscribe((event) => {
+        events.push(event.type);
+    });
+    await agent.prompt([
+        "请为每个 Source Item 生成一条 annotation。",
+        "",
+        "JSON schema:",
+        "{",
+        "  \"stage\": \"understanding\",",
+        "  \"sourceItemAnnotations\": [",
+        "    {",
+        "      \"sourceItemId\": \"input id\",",
+        "      \"claims\": [\"只基于 Source Item 的简短 claims\"],",
+        "      \"summary\": \"一句简短中文理解\",",
+        "      \"focusAreaRelevance\": \"strong|partial|weak|none\",",
+        "      \"evidenceBoundary\": \"说明证据边界和不能推出什么\",",
+        "      \"relevance\": \"relevant|not_relevant|uncertain\",",
+        "      \"evidence\": [\"支撑判断的短证据片段\"],",
+        "      \"weakItemHints\": [\"如果较弱，为什么弱；否则空数组\"]",
+        "    }",
+        "  ]",
+        "}",
+        "",
+        "关注领域：Agent 架构、AI Coding。关注方向：先进工具、长程任务、持续学习、自我改进、人与 Agent 的边界。",
+        "Input:",
+        JSON.stringify(request, null, 2)
+    ].join("\n"));
+    const text = latestAssistantText(agent);
+    if (!text) {
+        throw new Error("Understanding Stage did not return text");
+    }
+    return { text, events };
+}
+function buildFauxUnderstandingOutput(request) {
+    return {
+        stage: "understanding",
+        sourceItemAnnotations: request.sourceItems.map((item) => {
+            const relevance = classifyRelevance(item);
+            const evidence = firstEvidence(item.analyzableText);
+            return {
+                sourceItemId: item.id,
+                claims: [evidence],
+                summary: `当前 Source Item 表明：${evidence}`,
+                focusAreaRelevance: relevance === "relevant" ? "strong" : "none",
+                evidenceBoundary: "仅能说明该 Source Item 自身提供的内容，不能外推项目成熟度或外部采用情况。",
+                relevance,
+                evidence: [evidence],
+                weakItemHints: relevance === "relevant" ? [] : ["未明显命中 Agent 架构或 AI Coding 关注领域。"]
+            };
+        })
+    };
+}
+function validateMergedAnnotations(sourceItems, annotations) {
+    const expected = new Set(sourceItems.map((item) => item.id));
+    const seen = new Set();
+    const issues = [];
+    for (const annotation of annotations) {
+        if (!expected.has(annotation.sourceItemId)) {
+            issues.push(`sourceItemId references unknown id: ${annotation.sourceItemId}`);
+        }
+        if (seen.has(annotation.sourceItemId)) {
+            issues.push(`duplicate annotation for sourceItemId: ${annotation.sourceItemId}`);
+        }
+        seen.add(annotation.sourceItemId);
+    }
+    for (const sourceItem of sourceItems) {
+        if (!seen.has(sourceItem.id)) {
+            issues.push(`missing annotation for sourceItemId: ${sourceItem.id}`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new AgentStageValidationError("understanding", issues);
+    }
+}
+function createInMemoryArtifact(modelRuntimeConfig) {
+    return {
+        schemaVersion: 1,
+        runId: "in-memory-understanding",
+        date: new Date().toISOString().slice(0, 10),
+        startedAt: new Date().toISOString(),
+        model: {
+            provider: modelRuntimeConfig.provider,
+            model: modelRuntimeConfig.model,
+            ...(modelRuntimeConfig.credentialRef ? { credentialRef: modelRuntimeConfig.credentialRef } : {})
+        },
+        inputRefs: {},
+        stages: []
+    };
+}
+function latestAssistantText(agent) {
+    const assistantMessage = [...agent.state.messages].reverse().find((message) => message.role === "assistant");
+    const text = assistantMessage?.content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("");
+    return text && text.trim().length > 0 ? text.trim() : undefined;
+}
+function estimateSourceItemSize(item) {
+    return item.id.length + item.title.length + item.url.length + item.analyzableText.length;
+}
+function classifyRelevance(item) {
+    const text = `${item.title} ${item.analyzableText}`.toLowerCase();
+    const terms = ["agent architecture", "agent runtime", "coding agent", "ai coding", "tool execution", "memory", "workflow"];
+    return terms.some((term) => text.includes(term)) ? "relevant" : "not_relevant";
+}
+function firstEvidence(text) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    return normalized.length > 140 ? `${normalized.slice(0, 137)}...` : normalized || "Source Item 没有可分析文本。";
+}

package/dist/src/agent/stage-contracts.js

@@ -0,0 +1,205 @@
+export const AGENT_STAGE_NAMES = ["understanding", "selection", "ranking", "narrative", "audit", "repair"];
+export class AgentStageValidationError extends Error {
+    stage;
+    issues;
+    constructor(stage, issues) {
+        super(`Invalid ${stage} stage output:\n${issues.map((issue) => `- ${issue}`).join("\n")}`);
+        this.name = "AgentStageValidationError";
+        this.stage = stage;
+        this.issues = issues;
+    }
+}
+export function parseAgentStageOutput(stage, value, context = {}) {
+    let parsed;
+    if (typeof value === "string") {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new AgentStageValidationError(stage, [`output must be valid JSON: ${message}`]);
+        }
+    }
+    else {
+        parsed = value;
+    }
+    return validateAgentStageOutput(stage, parsed, context);
+}
+export function validateAgentStageOutput(stage, value, context = {}) {
+    const issues = [];
+    if (!isRecord(value)) {
+        throw new AgentStageValidationError(stage, ["output must be an object"]);
+    }
+    if (value.stage !== stage) {
+        issues.push(`stage must be ${stage}`);
+    }
+    if (stage === "understanding") {
+        validateUnderstanding(value, context, issues);
+    }
+    else if (stage === "selection") {
+        validateSelection(value, context, issues);
+    }
+    else if (stage === "ranking") {
+        validateRanking(value, context, issues);
+    }
+    else if (stage === "narrative" || stage === "repair") {
+        validateNarrative(value, context, issues);
+    }
+    else if (stage === "audit") {
+        validateAudit(value, context, issues);
+    }
+    if (issues.length > 0) {
+        throw new AgentStageValidationError(stage, issues);
+    }
+    return value;
+}
+function validateUnderstanding(value, context, issues) {
+    const annotations = readArray(value.sourceItemAnnotations, "sourceItemAnnotations", issues);
+    for (const [index, annotation] of annotations.entries()) {
+        if (!isRecord(annotation)) {
+            issues.push(`sourceItemAnnotations[${index}] must be an object`);
+            continue;
+        }
+        const sourceItemId = readString(annotation.sourceItemId, `sourceItemAnnotations[${index}].sourceItemId`, issues);
+        validateStringArray(annotation.claims, `sourceItemAnnotations[${index}].claims`, issues);
+        readString(annotation.summary, `sourceItemAnnotations[${index}].summary`, issues);
+        readString(annotation.evidenceBoundary, `sourceItemAnnotations[${index}].evidenceBoundary`, issues);
+        if (!["relevant", "not_relevant", "uncertain"].includes(String(annotation.relevance))) {
+            issues.push(`sourceItemAnnotations[${index}].relevance must be relevant, not_relevant, or uncertain`);
+        }
+        if (!["strong", "partial", "weak", "none"].includes(String(annotation.focusAreaRelevance))) {
+            issues.push(`sourceItemAnnotations[${index}].focusAreaRelevance must be strong, partial, weak, or none`);
+        }
+        validateStringArray(annotation.evidence, `sourceItemAnnotations[${index}].evidence`, issues);
+        validateStringArray(annotation.weakItemHints, `sourceItemAnnotations[${index}].weakItemHints`, issues);
+        validateKnownRef("sourceItemId", sourceItemId, context.sourceItemIds, issues);
+    }
+}
+function validateSelection(value, context, issues) {
+    const signals = readArray(value.candidateSignals, "candidateSignals", issues);
+    for (const [index, signal] of signals.entries()) {
+        if (!isRecord(signal)) {
+            issues.push(`candidateSignals[${index}] must be an object`);
+            continue;
+        }
+        readString(signal.signalId, `candidateSignals[${index}].signalId`, issues);
+        readString(signal.title, `candidateSignals[${index}].title`, issues);
+        readString(signal.reason, `candidateSignals[${index}].reason`, issues);
+        if (signal.strength !== "strong" && signal.strength !== "weak") {
+            issues.push(`candidateSignals[${index}].strength must be strong or weak`);
+        }
+        if (signal.signalType !== undefined &&
+            !["architecture", "ai-coding", "tool-repo", "risk"].includes(String(signal.signalType))) {
+            issues.push(`candidateSignals[${index}].signalType must be architecture, ai-coding, tool-repo, or risk`);
+        }
+        for (const sourceItemId of validateStringArray(signal.sourceItemIds, `candidateSignals[${index}].sourceItemIds`, issues)) {
+            validateKnownRef("sourceItemId", sourceItemId, context.sourceItemIds, issues);
+        }
+    }
+    if (value.excludedSourceItems !== undefined) {
+        const excluded = readArray(value.excludedSourceItems, "excludedSourceItems", issues);
+        for (const [index, exclusion] of excluded.entries()) {
+            if (!isRecord(exclusion)) {
+                issues.push(`excludedSourceItems[${index}] must be an object`);
+                continue;
+            }
+            const sourceItemId = readString(exclusion.sourceItemId, `excludedSourceItems[${index}].sourceItemId`, issues);
+            readString(exclusion.reason, `excludedSourceItems[${index}].reason`, issues);
+            validateKnownRef("sourceItemId", sourceItemId, context.sourceItemIds, issues);
+        }
+    }
+}
+function validateRanking(value, context, issues) {
+    const signals = readArray(value.rankedSignals, "rankedSignals", issues);
+    for (const [index, signal] of signals.entries()) {
+        if (!isRecord(signal)) {
+            issues.push(`rankedSignals[${index}] must be an object`);
+            continue;
+        }
+        const signalId = readString(signal.signalId, `rankedSignals[${index}].signalId`, issues);
+        readString(signal.reason, `rankedSignals[${index}].reason`, issues);
+        if (!Number.isInteger(signal.rank) || Number(signal.rank) < 1) {
+            issues.push(`rankedSignals[${index}].rank must be a positive integer`);
+        }
+        validateKnownRef("signalId", signalId, context.signalIds, issues);
+    }
+}
+function validateNarrative(value, context, issues) {
+    if (value.executiveSummary !== undefined) {
+        readString(value.executiveSummary, "executiveSummary", issues);
+    }
+    const narratives = readArray(value.signalNarratives, "signalNarratives", issues);
+    for (const [index, narrative] of narratives.entries()) {
+        if (!isRecord(narrative)) {
+            issues.push(`signalNarratives[${index}] must be an object`);
+            continue;
+        }
+        const signalId = readString(narrative.signalId, `signalNarratives[${index}].signalId`, issues);
+        validateStringArray(narrative.focusAreas, `signalNarratives[${index}].focusAreas`, issues);
+        validateStringArray(narrative.directions, `signalNarratives[${index}].directions`, issues);
+        readString(narrative.whatItIs, `signalNarratives[${index}].whatItIs`, issues);
+        readString(narrative.whatItIsNot, `signalNarratives[${index}].whatItIsNot`, issues);
+        readString(narrative.minimalExample, `signalNarratives[${index}].minimalExample`, issues);
+        readString(narrative.whyItMatters, `signalNarratives[${index}].whyItMatters`, issues);
+        validateKnownRef("signalId", signalId, context.signalIds, issues);
+    }
+}
+function validateAudit(value, context, issues) {
+    if (value.status !== "passed" && value.status !== "failed") {
+        issues.push("status must be passed or failed");
+    }
+    const findings = readArray(value.findings, "findings", issues);
+    for (const [index, finding] of findings.entries()) {
+        if (!isRecord(finding)) {
+            issues.push(`findings[${index}] must be an object`);
+            continue;
+        }
+        if (finding.signalId !== undefined) {
+            const signalId = readString(finding.signalId, `findings[${index}].signalId`, issues);
+            validateKnownRef("signalId", signalId, context.signalIds, issues);
+        }
+        if (finding.sourceItemId !== undefined) {
+            const sourceItemId = readString(finding.sourceItemId, `findings[${index}].sourceItemId`, issues);
+            validateKnownRef("sourceItemId", sourceItemId, context.sourceItemIds, issues);
+        }
+        readString(finding.issue, `findings[${index}].issue`, issues);
+    }
+}
+function readArray(value, field, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${field} must be an array`);
+        return [];
+    }
+    return value;
+}
+function validateStringArray(value, field, issues) {
+    const entries = readArray(value, field, issues);
+    const strings = [];
+    for (const [index, entry] of entries.entries()) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            issues.push(`${field}[${index}] must be a non-empty string`);
+        }
+        else {
+            strings.push(entry.trim());
+        }
+    }
+    return strings;
+}
+function readString(value, field, issues) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        issues.push(`${field} must be a non-empty string`);
+        return "";
+    }
+    return value.trim();
+}
+function validateKnownRef(kind, value, known, issues) {
+    if (!value || !known) {
+        return;
+    }
+    if (!known.includes(value)) {
+        issues.push(`${kind} references unknown id: ${value}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/agent/stage-runner.js

@@ -0,0 +1,66 @@
+import { AgentStageValidationError, parseAgentStageOutput } from "./stage-contracts.js";
+import { writeAgentRunArtifact } from "../storage/agent-run-artifact.js";
+export async function runAgentStage(input) {
+    const startedAt = new Date();
+    try {
+        const rawOutput = await input.execute();
+        const output = parseAgentStageOutput(input.stage, rawOutput, input.validationContext);
+        const record = {
+            stage: input.stage,
+            status: "succeeded",
+            startedAt: startedAt.toISOString(),
+            completedAt: new Date().toISOString(),
+            inputRefs: input.inputRefs ?? {},
+            output,
+            validation: {
+                status: "passed",
+                issues: []
+            }
+        };
+        input.artifact.stages.push(record);
+        return {
+            output,
+            record,
+            ...(await maybeWriteArtifact(input))
+        };
+    }
+    catch (error) {
+        const failure = toAgentRunFailure(error);
+        const record = {
+            stage: input.stage,
+            status: "failed",
+            startedAt: startedAt.toISOString(),
+            completedAt: new Date().toISOString(),
+            inputRefs: input.inputRefs ?? {},
+            validation: {
+                status: failure.kind === "validation" ? "failed" : "passed",
+                issues: failure.issues ?? []
+            },
+            failure
+        };
+        input.artifact.stages.push(record);
+        input.artifact.failure = failure;
+        await maybeWriteArtifact(input);
+        throw error;
+    }
+}
+async function maybeWriteArtifact(input) {
+    if (!input.date || !input.artifactRoot) {
+        return {};
+    }
+    const written = await writeAgentRunArtifact(input.artifact, input.date, input.artifactRoot);
+    return { artifactPath: written.path };
+}
+function toAgentRunFailure(error) {
+    if (error instanceof AgentStageValidationError) {
+        return {
+            kind: "validation",
+            message: error.message,
+            issues: error.issues
+        };
+    }
+    return {
+        kind: "execution",
+        message: error instanceof Error ? error.message : String(error)
+    };
+}