@evref-bl/dev-nexus 0.1.0-alpha.0

package/dist/nexusAutomationAgentLaunch.js

@@ -0,0 +1,855 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { appendNexusAutomationRunRecord, buildNexusAutomationWorkItemQuery, eligibleNexusAutomationWorkItems, evaluateNexusAutomationLedgerBackoff, readNexusAutomationRunLedger, releaseNexusAutomationRunLock, acquireNexusAutomationRunLock, } from "./nexusAutomation.js";
+import { defaultNexusAutomationCommandRunner, } from "./nexusAutomationCommandExecutor.js";
+import { normalizeNexusAutomationAgentPolicy, } from "./nexusAutomationAgentProfile.js";
+import { projectPluginCapabilityProjections, } from "./nexusPluginCapabilities.js";
+import { loadProjectConfig, } from "./nexusProjectConfig.js";
+import { readNexusAutomationTargetContext, } from "./nexusAutomationTarget.js";
+import { resolvePrimaryProjectComponent, resolveProjectComponents, } from "./nexusProjectLifecycle.js";
+import { createWorkTrackerProvider, } from "./workTrackingProviderService.js";
+export class NexusAutomationAgentLaunchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusAutomationAgentLaunchError";
+    }
+}
+export async function runNexusAutomationAgentLaunchOnce(options) {
+    const projectRoot = path.resolve(requiredNonEmptyString(options.projectRoot, "projectRoot"));
+    const projectConfig = loadProjectConfig(projectRoot);
+    const automationConfig = projectConfig.automation ?? null;
+    const runId = options.runId ?? generateNexusAutomationAgentRunId(options.now);
+    let sourceRoot = null;
+    let components = [];
+    let lock = null;
+    let ledger = null;
+    let componentProviders = [];
+    let preflight = [];
+    let selectorQuery = null;
+    let eligibleWorkItems = [];
+    let componentEligibleWorkItems = [];
+    let contextFile = null;
+    let resultFile = null;
+    if (!automationConfig?.enabled) {
+        return launchResult({
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status: "skipped",
+            summary: "Automation is not enabled for this project",
+            ledger,
+            lock,
+            preflight: [],
+            selectorQuery,
+            eligibleWorkItems,
+            componentEligibleWorkItems,
+            components,
+            contextFile,
+            resultFile,
+            launch: null,
+        });
+    }
+    if (automationConfig.mode !== "agent_launch") {
+        return launchResult({
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status: "blocked",
+            summary: "Automation mode is not agent_launch",
+            ledger,
+            lock,
+            preflight: [],
+            selectorQuery,
+            eligibleWorkItems,
+            componentEligibleWorkItems,
+            components,
+            contextFile,
+            resultFile,
+            launch: null,
+        });
+    }
+    const startedAt = currentIso(options.now);
+    lock = acquireNexusAutomationRunLock({
+        projectRoot,
+        config: automationConfig,
+        runId,
+        owner: options.owner ?? null,
+        now: startedAt,
+    });
+    try {
+        ledger = readNexusAutomationRunLedger(projectRoot, automationConfig);
+        const backoff = evaluateNexusAutomationLedgerBackoff(automationConfig, ledger, startedAt);
+        if (!backoff.shouldRun) {
+            const summary = backoff.reason ?? "Automation retry backoff is active";
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: startedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    status: "skipped",
+                    startedAt,
+                    finishedAt: startedAt,
+                    summary,
+                    nextRunNotBefore: backoff.retryAfter,
+                },
+            });
+            return launchResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "skipped",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                selectorQuery,
+                eligibleWorkItems,
+                componentEligibleWorkItems,
+                components,
+                contextFile,
+                resultFile,
+                launch: null,
+            });
+        }
+        components = resolveProjectComponents(projectRoot, projectConfig);
+        sourceRoot = resolvePrimaryProjectComponent(projectRoot, projectConfig).sourceRoot;
+        componentProviders = createAgentLaunchComponentProviders({
+            options,
+            projectRoot,
+            projectConfig,
+            components,
+        });
+        if (componentProviders.length === 0) {
+            const summary = "No project component has work tracking configured";
+            preflight = [
+                check("workTracking", false, "At least one component has work tracking configured", summary),
+            ];
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: startedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    status: "blocked",
+                    startedAt,
+                    finishedAt: startedAt,
+                    sourceRoot,
+                    summary,
+                    error: summary,
+                },
+            });
+            return launchResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "blocked",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                selectorQuery,
+                eligibleWorkItems,
+                componentEligibleWorkItems,
+                components,
+                contextFile,
+                resultFile,
+                launch: null,
+            });
+        }
+        preflight = preflightNexusAutomationAgentLaunch({
+            components,
+            componentProviders,
+            automationConfig,
+        });
+        const failedChecks = preflight.filter((check) => check.status === "failed");
+        if (failedChecks.length > 0) {
+            const summary = failedChecks.map((check) => check.message).join("; ");
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: startedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    status: "blocked",
+                    startedAt,
+                    finishedAt: startedAt,
+                    sourceRoot,
+                    summary,
+                    error: summary,
+                },
+            });
+            return launchResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "blocked",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                selectorQuery,
+                eligibleWorkItems,
+                componentEligibleWorkItems,
+                components,
+                contextFile,
+                resultFile,
+                launch: null,
+            });
+        }
+        selectorQuery = buildNexusAutomationWorkItemQuery(automationConfig);
+        componentEligibleWorkItems = await listEligibleWorkItemsByComponent(componentProviders, selectorQuery, automationConfig, projectRoot);
+        eligibleWorkItems = componentEligibleWorkItems.flatMap((component) => component.workItems);
+        if (eligibleWorkItems.length === 0) {
+            const summary = "No eligible work item matched the automation selector";
+            const finishedAt = currentIso(options.now);
+            ledger = appendNexusAutomationRunRecord({
+                projectRoot,
+                config: automationConfig,
+                now: finishedAt,
+                record: {
+                    id: runId,
+                    projectId: projectConfig.id,
+                    status: "skipped",
+                    startedAt,
+                    finishedAt,
+                    sourceRoot,
+                    summary,
+                },
+            });
+            return launchResult({
+                runId,
+                projectRoot,
+                sourceRoot,
+                projectConfig,
+                automationConfig,
+                status: "skipped",
+                summary,
+                ledger,
+                lock,
+                preflight,
+                selectorQuery,
+                eligibleWorkItems,
+                componentEligibleWorkItems,
+                components,
+                contextFile,
+                resultFile,
+                launch: null,
+            });
+        }
+        const launchFiles = nexusAutomationAgentLaunchFiles({
+            projectRoot,
+            runId,
+        });
+        writeNexusAutomationAgentLaunchContext({
+            contextFile: launchFiles.contextFile,
+            context: buildAgentLaunchContext({
+                runId,
+                startedAt,
+                projectRoot,
+                sourceRoot,
+                components,
+                projectConfig,
+                automationConfig,
+                selectorQuery,
+                eligibleWorkItems,
+                componentEligibleWorkItems,
+                resultFile: launchFiles.resultFile,
+            }),
+        });
+        contextFile = launchFiles.contextFile;
+        resultFile = launchFiles.resultFile;
+        const agentResult = await options.launcher({
+            runId,
+            startedAt,
+            projectRoot,
+            sourceRoot,
+            components,
+            projectConfig,
+            automationConfig,
+            selectorQuery,
+            eligibleWorkItems,
+            componentEligibleWorkItems,
+            contextFile,
+            resultFile,
+        });
+        const status = normalizeAgentStatus(agentResult.status);
+        const finishedAt = currentIso(options.now);
+        const summary = agentResult.summary ?? defaultAgentSummary(status);
+        ledger = appendNexusAutomationRunRecord({
+            projectRoot,
+            config: automationConfig,
+            now: finishedAt,
+            record: {
+                id: runId,
+                projectId: projectConfig.id,
+                status,
+                startedAt,
+                finishedAt,
+                sourceRoot,
+                commitIds: agentResult.commitIds ?? [],
+                summary,
+                verification: verificationRecords(agentResult.verification, finishedAt),
+                publicationDecision: publicationDecisionRecord(agentResult.publicationDecision, finishedAt),
+                error: agentResult.error ?? null,
+            },
+        });
+        return launchResult({
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status,
+            summary,
+            ledger,
+            lock,
+            preflight,
+            selectorQuery,
+            eligibleWorkItems,
+            componentEligibleWorkItems,
+            components,
+            contextFile,
+            resultFile,
+            launch: agentResult,
+        });
+    }
+    catch (error) {
+        if (!automationConfig) {
+            throw error;
+        }
+        const finishedAt = currentIso(options.now);
+        const summary = errorMessage(error);
+        ledger = appendNexusAutomationRunRecord({
+            projectRoot,
+            config: automationConfig,
+            now: finishedAt,
+            record: {
+                id: runId,
+                projectId: projectConfig.id,
+                status: "failed",
+                startedAt,
+                finishedAt,
+                sourceRoot,
+                summary,
+                error: summary,
+            },
+        });
+        return launchResult({
+            runId,
+            projectRoot,
+            sourceRoot,
+            projectConfig,
+            automationConfig,
+            status: "failed",
+            summary,
+            ledger,
+            lock,
+            preflight,
+            selectorQuery,
+            eligibleWorkItems,
+            componentEligibleWorkItems,
+            components,
+            contextFile,
+            resultFile,
+            launch: null,
+        });
+    }
+    finally {
+        if (automationConfig) {
+            releaseNexusAutomationRunLock({
+                projectRoot,
+                config: automationConfig,
+                runId,
+            });
+        }
+    }
+}
+export function createNexusAutomationAgentCommandLauncher(options) {
+    const command = requiredNonEmptyString(options.command, "command");
+    const commandRunner = options.commandRunner ?? defaultNexusAutomationCommandRunner;
+    return (input) => {
+        const commandResult = commandRunner(command, {
+            cwd: input.projectRoot,
+            env: agentLaunchEnvironment(options.env ?? process.env, input),
+            timeoutMs: options.timeoutMs,
+        });
+        const commandVerification = verificationFromCommandResult(commandResult);
+        const reported = readAgentResultFile(input.resultFile);
+        if (reported.status === "failed") {
+            return {
+                status: "failed",
+                summary: reported.summary,
+                verification: [commandVerification],
+                error: reported.error,
+            };
+        }
+        const verification = [
+            commandVerification,
+            ...(reported.result?.verification ?? []),
+        ];
+        if (!commandSucceeded(commandResult)) {
+            return {
+                status: "failed",
+                summary: `Agent command failed: ${commandSummary(commandResult)}`,
+                verification,
+                commitIds: reported.result?.commitIds ?? [],
+                publicationDecision: reported.result?.publicationDecision,
+                error: commandSummary(commandResult),
+            };
+        }
+        if (reported.status === "missing") {
+            return {
+                status: "failed",
+                summary: reported.summary,
+                verification,
+                error: reported.error,
+            };
+        }
+        const status = normalizeAgentStatus(reported.result?.status);
+        return {
+            status,
+            summary: reported.result?.summary ?? defaultAgentSummary(status),
+            verification,
+            commitIds: reported.result?.commitIds ?? [],
+            publicationDecision: reported.result?.publicationDecision,
+            error: reported.result?.error ?? null,
+        };
+    };
+}
+export function preflightNexusAutomationAgentLaunch(options) {
+    return [
+        ...preflightNexusAutomationAgentPolicy(options.automationConfig),
+        check("workTracking", options.componentProviders.length > 0, "At least one component has work tracking configured", "No project component has work tracking configured"),
+        ...options.componentProviders.map(({ component, provider }) => check(`component:${component.id}:trackerListItems`, provider.capabilities.listItems, `Component ${component.id} tracker can list work items`, `Component ${component.id} tracker provider ${provider.provider} cannot list work items`)),
+        ...options.components.map((component) => check(`component:${component.id}:sourceRoot`, component.sourceRootExists, `Component ${component.id} source root exists`, `Component ${component.id} source root does not exist: ${component.sourceRoot}`)),
+    ];
+}
+function preflightNexusAutomationAgentPolicy(automationConfig) {
+    const policy = normalizeNexusAutomationAgentPolicy(automationConfig);
+    const checks = [
+        check("agent:maxConcurrentSubagents", policy.maxConcurrentSubagents > 0, `Agent subagent cap is ${policy.maxConcurrentSubagents}`, "automation.agent.maxConcurrentSubagents must be a positive integer"),
+    ];
+    if (!policy.coordinatorProfileId) {
+        checks.push(check("agent:coordinatorProfile", true, "No coordinator profile is configured; command policy must come from automation.agent.command or caller override", "Coordinator profile is not configured"));
+        return checks;
+    }
+    const coordinatorProfile = policy.coordinatorProfile;
+    checks.push(check("agent:coordinatorProfile", coordinatorProfile !== null, `Coordinator profile ${policy.coordinatorProfileId} is configured`, `automation.agent.coordinatorProfileId references missing profile: ${policy.coordinatorProfileId}`));
+    if (!coordinatorProfile) {
+        return checks;
+    }
+    checks.push(check(`agentProfile:${coordinatorProfile.id}:intendedUse`, coordinatorProfile.intendedUse !== "subagent", `Coordinator profile ${coordinatorProfile.id} intendedUse allows coordinator launch`, `automation.agent.profiles.${coordinatorProfile.id}.intendedUse must be coordinator or any for coordinator launch`), check(`agentProfile:${coordinatorProfile.id}:command`, coordinatorProfile.command !== null, `Coordinator profile ${coordinatorProfile.id} command is configured`, `automation.agent.profiles.${coordinatorProfile.id}.command must be configured for coordinator launch`));
+    return checks;
+}
+export function generateNexusAutomationAgentRunId(now) {
+    const timestamp = currentIso(now)
+        .replaceAll("-", "")
+        .replaceAll(":", "")
+        .replace(".", "-");
+    const suffix = Math.random().toString(36).slice(2, 8);
+    return `agent-${timestamp}-${suffix}`;
+}
+function createAgentLaunchComponentProviders(options) {
+    return options.components
+        .filter((component) => component.workTracking)
+        .map((component) => ({
+        component,
+        provider: createAgentLaunchProvider({
+            options: options.options,
+            projectRoot: options.projectRoot,
+            projectConfig: options.projectConfig,
+            component,
+        }),
+    }));
+}
+function createAgentLaunchProvider(options) {
+    const workTracking = options.component.workTracking;
+    if (!workTracking) {
+        throw new NexusAutomationAgentLaunchError(`Component ${options.component.id} work tracking is not configured`);
+    }
+    if (options.options.provider) {
+        return options.options.provider;
+    }
+    if (options.options.providerFactory) {
+        return options.options.providerFactory({
+            projectRoot: options.projectRoot,
+            sourceRoot: options.component.sourceRoot,
+            projectConfig: options.projectConfig,
+            component: options.component,
+            workTracking,
+        });
+    }
+    return createWorkTrackerProvider(workTracking, {
+        ...options.options.providerOptions,
+        projectRoot: options.projectRoot,
+        now: options.options.now,
+    });
+}
+async function listEligibleWorkItemsByComponent(componentProviders, selectorQuery, automationConfig, projectRoot) {
+    const grouped = [];
+    for (const { component, provider } of componentProviders) {
+        grouped.push({
+            componentId: component.id,
+            workItems: eligibleNexusAutomationWorkItems(await provider.listWorkItems({
+                ...selectorQuery,
+                projectRoot,
+            }), automationConfig),
+        });
+    }
+    return grouped;
+}
+function buildAgentLaunchContext(input) {
+    return {
+        version: 1,
+        runId: input.runId,
+        startedAt: input.startedAt,
+        projectRoot: input.projectRoot,
+        sourceRoot: input.sourceRoot,
+        project: {
+            id: input.projectConfig.id,
+            name: input.projectConfig.name,
+            componentCount: input.components.length,
+        },
+        components: input.components.map(componentContext),
+        automation: {
+            mode: "agent_launch",
+            selectorQuery: input.selectorQuery,
+            eligibleWorkItemCount: input.eligibleWorkItems.length,
+        },
+        target: readNexusAutomationTargetContext({
+            projectRoot: input.projectRoot,
+            config: input.automationConfig,
+        }),
+        agent: normalizeNexusAutomationAgentPolicy(input.automationConfig),
+        pluginCapabilities: projectPluginCapabilityProjections(input.projectConfig),
+        result: agentResultContract(input.resultFile),
+        eligibleWorkItems: input.eligibleWorkItems,
+        componentEligibleWorkItems: input.componentEligibleWorkItems,
+        safety: input.automationConfig.safety,
+        publication: input.automationConfig.publication,
+    };
+}
+function componentContext(component) {
+    return {
+        id: component.id,
+        name: component.name,
+        role: component.role,
+        kind: component.kind,
+        sourceRoot: component.sourceRoot,
+        sourceRootExists: component.sourceRootExists,
+        worktreesRoot: component.worktreesRoot,
+        worktreesRootExists: component.worktreesRootExists,
+        remoteUrl: component.remoteUrl,
+        defaultBranch: component.defaultBranch,
+        workTracker: {
+            provider: component.workTracking?.provider ?? null,
+            configured: Boolean(component.workTracking),
+        },
+        relationships: component.relationships,
+    };
+}
+function writeNexusAutomationAgentLaunchContext(options) {
+    fs.mkdirSync(path.dirname(options.contextFile), { recursive: true });
+    fs.writeFileSync(options.contextFile, `${JSON.stringify(options.context, null, 2)}\n`, "utf8");
+}
+function nexusAutomationAgentLaunchFiles(options) {
+    const launchDir = path.join(options.projectRoot, ".dev-nexus", "automation", "agent-launches", safePathSegment(options.runId));
+    const contextFile = path.join(launchDir, "context.json");
+    const resultFile = path.join(launchDir, "result.json");
+    return { contextFile, resultFile };
+}
+function agentResultContract(resultFile) {
+    return {
+        file: resultFile,
+        requiredFields: ["status", "summary"],
+        optionalFields: [
+            "commitIds",
+            "verification",
+            "publicationDecision",
+            "error",
+        ],
+        statuses: ["completed", "failed", "blocked"],
+        verificationStatuses: ["passed", "failed", "not_run"],
+        publicationDecisionTypes: [
+            "not_decided",
+            "local_only",
+            "direct_integration",
+            "review_handoff",
+            "blocked",
+        ],
+    };
+}
+function agentLaunchEnvironment(baseEnv, input) {
+    return {
+        ...baseEnv,
+        DEV_NEXUS_AUTOMATION_MODE: "agent_launch",
+        DEV_NEXUS_RUN_ID: input.runId,
+        DEV_NEXUS_STARTED_AT: input.startedAt,
+        DEV_NEXUS_PROJECT_ROOT: input.projectRoot,
+        DEV_NEXUS_SOURCE_ROOT: input.sourceRoot,
+        DEV_NEXUS_COMPONENT_COUNT: input.components.length.toString(),
+        DEV_NEXUS_COMPONENT_IDS: input.components
+            .map((component) => component.id)
+            .join(","),
+        DEV_NEXUS_PRIMARY_COMPONENT_ID: input.components.find((component) => component.role === "primary")?.id ??
+            input.components[0]?.id ??
+            "",
+        DEV_NEXUS_AGENT_CONTEXT_FILE: input.contextFile,
+        DEV_NEXUS_AGENT_RESULT_FILE: input.resultFile,
+        DEV_NEXUS_AGENT_RESULT_REQUIRED_FIELDS: "status,summary",
+        DEV_NEXUS_AGENT_RESULT_OPTIONAL_FIELDS: "commitIds,verification,publicationDecision,error",
+        DEV_NEXUS_TARGET_ID: input.automationConfig.target.id ?? "",
+        DEV_NEXUS_TARGET_STATE_FILE: readNexusAutomationTargetContext({
+            projectRoot: input.projectRoot,
+            config: input.automationConfig,
+        }).statePath,
+        DEV_NEXUS_TARGET_CYCLE_LEDGER_FILE: readNexusAutomationTargetContext({
+            projectRoot: input.projectRoot,
+            config: input.automationConfig,
+        }).cycleLedgerPath,
+        DEV_NEXUS_COORDINATOR_PROFILE_ID: input.automationConfig.agent.coordinatorProfileId ?? "",
+        DEV_NEXUS_MAX_CONCURRENT_SUBAGENTS: input.automationConfig.agent.maxConcurrentSubagents.toString(),
+        DEV_NEXUS_ELIGIBLE_WORK_ITEM_COUNT: input.eligibleWorkItems.length.toString(),
+        DEV_NEXUS_ELIGIBLE_WORK_ITEM_IDS: input.eligibleWorkItems
+            .map((item) => item.id)
+            .join(","),
+    };
+}
+function readAgentResultFile(resultFile) {
+    if (!fs.existsSync(resultFile)) {
+        const message = `Agent result file was not written: ${resultFile}`;
+        return {
+            status: "missing",
+            summary: message,
+            error: message,
+        };
+    }
+    try {
+        return {
+            status: "loaded",
+            summary: "Agent result file loaded",
+            error: null,
+            result: normalizeAgentResult(JSON.parse(fs.readFileSync(resultFile, "utf8").replace(/^\uFEFF/, ""))),
+        };
+    }
+    catch (error) {
+        const message = `Agent result file is invalid: ${errorMessage(error)}`;
+        return {
+            status: "failed",
+            summary: message,
+            error: message,
+        };
+    }
+}
+function normalizeAgentResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationAgentLaunchError("agent result must be an object");
+    }
+    const record = value;
+    return {
+        status: normalizeAgentStatus(requiredNonEmptyString(record.status, "agent result.status")),
+        summary: requiredNonEmptyString(record.summary, "agent result.summary"),
+        ...(record.commitIds === undefined
+            ? {}
+            : { commitIds: normalizeStringArray(record.commitIds, "agent result.commitIds") }),
+        ...(record.verification === undefined
+            ? {}
+            : { verification: normalizeVerificationInputList(record.verification) }),
+        ...(record.publicationDecision === undefined
+            ? {}
+            : {
+                publicationDecision: normalizePublicationDecisionInput(record.publicationDecision),
+            }),
+        ...(record.error === undefined
+            ? {}
+            : { error: optionalNullableString(record.error) ?? null }),
+    };
+}
+function normalizeVerificationInputList(value) {
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationAgentLaunchError("agent result.verification must be an array");
+    }
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new NexusAutomationAgentLaunchError(`agent result.verification[${index}] must be an object`);
+        }
+        const record = item;
+        return {
+            command: requiredNonEmptyString(record.command, `agent result.verification[${index}].command`),
+            ...(record.status === undefined
+                ? {}
+                : {
+                    status: normalizeVerificationStatus(record.status, `agent result.verification[${index}].status`),
+                }),
+            ...(record.summary === undefined
+                ? {}
+                : { summary: optionalNullableString(record.summary) ?? null }),
+        };
+    });
+}
+function normalizePublicationDecisionInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new NexusAutomationAgentLaunchError("agent result.publicationDecision must be an object");
+    }
+    const record = value;
+    return {
+        type: normalizePublicationDecisionType(record.type, "agent result.publicationDecision.type"),
+        targetBranch: optionalNullableString(record.targetBranch) ?? null,
+        remote: optionalNullableString(record.remote) ?? null,
+        prUrl: optionalNullableString(record.prUrl) ?? null,
+        reason: optionalNullableString(record.reason) ?? null,
+    };
+}
+function verificationRecords(values, recordedAt) {
+    return (values ?? []).map((value) => ({
+        command: requiredNonEmptyString(value.command, "verification.command"),
+        status: value.status ?? "passed",
+        summary: optionalNullableString(value.summary) ?? null,
+        recordedAt,
+    }));
+}
+function publicationDecisionRecord(value, decidedAt) {
+    if (!value) {
+        return null;
+    }
+    return {
+        type: value.type,
+        targetBranch: value.targetBranch ?? null,
+        remote: value.remote ?? null,
+        prUrl: value.prUrl ?? null,
+        reason: value.reason ?? null,
+        decidedAt,
+    };
+}
+function verificationFromCommandResult(result) {
+    return {
+        command: result.command,
+        status: commandSucceeded(result) ? "passed" : "failed",
+        summary: commandSummary(result),
+    };
+}
+function commandSucceeded(result) {
+    return result.exitCode === 0 && !result.error;
+}
+function commandSummary(result) {
+    if (result.error) {
+        return result.error;
+    }
+    const exit = result.exitCode === null ? "no exit code" : `exit ${result.exitCode}`;
+    const output = firstNonEmptyLine(result.stderr) ?? firstNonEmptyLine(result.stdout);
+    return output ? `${exit}: ${truncate(output, 180)}` : exit;
+}
+function defaultAgentSummary(status) {
+    if (status === "completed") {
+        return "Agent launch completed";
+    }
+    if (status === "blocked") {
+        return "Agent launch reported a blocker";
+    }
+    return "Agent launch failed";
+}
+function normalizeAgentStatus(status) {
+    if (status === undefined || status === null) {
+        return "completed";
+    }
+    if (status === "completed" || status === "failed" || status === "blocked") {
+        return status;
+    }
+    throw new NexusAutomationAgentLaunchError("agent launch status must be completed, failed, or blocked");
+}
+function normalizeVerificationStatus(status, name) {
+    if (status === "passed" || status === "failed" || status === "not_run") {
+        return status;
+    }
+    throw new NexusAutomationAgentLaunchError(`${name} must be passed, failed, or not_run`);
+}
+function normalizePublicationDecisionType(value, name) {
+    if (value === "not_decided" ||
+        value === "local_only" ||
+        value === "direct_integration" ||
+        value === "review_handoff" ||
+        value === "blocked") {
+        return value;
+    }
+    throw new NexusAutomationAgentLaunchError(`${name} must be not_decided, local_only, direct_integration, review_handoff, or blocked`);
+}
+function check(name, passed, passedMessage, failedMessage) {
+    return {
+        name,
+        status: (passed ? "passed" : "failed"),
+        message: passed ? passedMessage : failedMessage,
+    };
+}
+function launchResult(result) {
+    return {
+        ...result,
+        componentEligibleWorkItems: result.componentEligibleWorkItems ?? [],
+        components: result.components ?? [],
+    };
+}
+function safePathSegment(value) {
+    const normalized = value
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (!normalized) {
+        throw new NexusAutomationAgentLaunchError("runId must contain at least one safe character");
+    }
+    return normalized;
+}
+function currentIso(now) {
+    const value = now ? now() : new Date();
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new NexusAutomationAgentLaunchError("now must return a valid date");
+    }
+    return date.toISOString();
+}
+function firstNonEmptyLine(value) {
+    return value
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .find(Boolean);
+}
+function truncate(value, length) {
+    return value.length <= length ? value : `${value.slice(0, length - 3)}...`;
+}
+function normalizeStringArray(value, name) {
+    if (!Array.isArray(value)) {
+        throw new NexusAutomationAgentLaunchError(`${name} must be an array`);
+    }
+    return value.map((item, index) => requiredNonEmptyString(item, `${name}[${index}]`));
+}
+function optionalNullableString(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return requiredNonEmptyString(value, "value");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function requiredNonEmptyString(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new NexusAutomationAgentLaunchError(`${name} must be a non-empty string`);
+    }
+    return value.trim();
+}