@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/runtime/runtime-action-proposals.js

@@ -0,0 +1,542 @@
+import { mkdirSync } from "node:fs";
+import { actionProposalPath, actionProposalsRoot, byCreatedAtDesc, listJsonFiles, readActionProposalAt, writeJsonFile, } from "./runtime-persistence.js";
+import { ACTION_PLANNER_CLARIFICATION_MESSAGE, actionAssistantMessage, actionCommandPreview, actionTypeFromValues, actionValueBuildPlanIntent, buildPlanAuthoringHintFromPrompt, buildPlanAuthoringPromptFallback, buildPlanIdForProposal, buildPlanLabelFromId, createActionProposalId, directServiceEndpointForAction, hasContextGraphBenchmarkTarget, numberValue, sanitizeActionProposalPlan, stringValue, benchmarkModeFromValues, } from "./runtime-proposal-helpers.js";
+import { ActionProposalApprovalRequestSchema, ActionProposalCreateRequestSchema, ActionProposalPlanSchema, ActionProposalResourceSchema, ActionProposalTypeSchema, } from "./schemas/index.js";
+import { BuildPlanAuthoringActionValuesSchema, ProjectSetupActionValuesSchema, } from "./action-values.js";
+import { buildPlanIdForProjectConfig, buildTestSpecFromSourceFolderConfig, listProjectConfigs, loadSourceFolderConfig, resolveConfiguredSourceFolderPath, resolveProjectSourceBindingPath, } from "../projects/source-config.js";
+import { listSourceFolderChoices } from "../projects/source-folders.js";
+import { artifactRequirementsForPlanAuthoring, requestedArtifactsForPlanAuthoring, } from "./plan-artifact-contract.js";
+import { BuildPlanAuthoringArtifactRequirementSchema, BuildPlanContextCheckDraftSchema, RequestedArtifactSchema, } from "../build-plans/authoring/brief.js";
+import { getExecutorStatus } from "./runtime-executor.js";
+export function listActionProposals(projectDataDir) {
+    return byCreatedAtDesc(listJsonFiles(actionProposalsRoot(projectDataDir))
+        .map(readActionProposalAt)
+        .filter((proposal) => proposal !== null));
+}
+export function getActionProposal(projectDataDir, proposalId) {
+    return listActionProposals(projectDataDir).find((proposal) => proposal.proposal_id === proposalId) ?? null;
+}
+export async function createActionProposal(runtime, projectDataDir, requestValue) {
+    const request = ActionProposalCreateRequestSchema.parse(requestValue);
+    const proposal = ActionProposalResourceSchema.parse({
+        ...(await buildActionProposal(runtime, projectDataDir, request)),
+        client_origin: request.client_origin,
+    });
+    writeActionProposal(projectDataDir, proposal);
+    return proposal;
+}
+export async function decideActionProposal(runtime, projectDataDir, proposalId, requestValue) {
+    const decision = ActionProposalApprovalRequestSchema.parse(requestValue);
+    const current = getActionProposal(projectDataDir, proposalId);
+    if (!current)
+        return null;
+    if (current.status !== "awaiting_approval") {
+        throw new Error(`Action proposal "${proposalId}" is already ${current.status}.`);
+    }
+    const now = new Date().toISOString();
+    const decided = ActionProposalResourceSchema.parse({
+        ...current,
+        status: decision.approved ? "approved" : "denied",
+        updated_at: now,
+        approval: {
+            approved: decision.approved,
+            decided_at: now,
+            ...(decision.note ? { note: decision.note } : {}),
+        },
+    });
+    writeActionProposal(projectDataDir, decided);
+    if (!decision.approved)
+        return decided;
+    try {
+        const submission = await submitActionProposal(runtime, projectDataDir, decided);
+        const submitted = ActionProposalResourceSchema.parse({
+            ...decided,
+            status: "submitted",
+            updated_at: new Date().toISOString(),
+            submitted_run_id: submission.runId,
+            submitted_run_type: submission.runType,
+        });
+        writeActionProposal(projectDataDir, submitted);
+        return submitted;
+    }
+    catch (error) {
+        const failed = ActionProposalResourceSchema.parse({
+            ...decided,
+            status: "failed",
+            updated_at: new Date().toISOString(),
+            error: error instanceof Error ? error.message : String(error),
+        });
+        writeActionProposal(projectDataDir, failed);
+        return failed;
+    }
+}
+export function writeActionProposal(projectDataDir, proposal) {
+    mkdirSync(actionProposalsRoot(projectDataDir), { recursive: true });
+    writeJsonFile(actionProposalPath(projectDataDir, proposal.proposal_id), ActionProposalResourceSchema.parse(proposal));
+}
+function hasOwnValue(values, key) {
+    return Object.prototype.hasOwnProperty.call(values, key);
+}
+function requestedArtifactsFromProposalValues(values) {
+    if (!hasOwnValue(values, "requested_artifacts"))
+        return undefined;
+    return RequestedArtifactSchema.array().parse(values.requested_artifacts);
+}
+function artifactRequirementsFromProposalValues(values) {
+    if (!hasOwnValue(values, "artifact_requirements"))
+        return undefined;
+    return BuildPlanAuthoringArtifactRequirementSchema.array().parse(values.artifact_requirements);
+}
+function contextChecksFromProposalValues(values) {
+    if (!hasOwnValue(values, "checks"))
+        return undefined;
+    return BuildPlanContextCheckDraftSchema.array().parse(values.checks);
+}
+async function planActionProposal(runtime, projectDataDir, request) {
+    if (!runtime.handlers.planActionProposal) {
+        return ActionProposalPlanSchema.parse({
+            action_type: "clarification",
+            ...(request.project ? { project: request.project } : {}),
+            assistant_message: "No local action planner is configured for this Interf instance.",
+        });
+    }
+    const projects = listProjectConfigs(loadSourceFolderConfig(projectDataDir));
+    let rawPlan;
+    try {
+        rawPlan = await runtime.handlers.planActionProposal(request, {
+            sourcePath: projectDataDir,
+            projects,
+            projectHealth: projects.map((project) => {
+                const benchmarkSpec = buildTestSpecFromSourceFolderConfig({
+                    projectDataDir,
+                    targetName: project.name,
+                    targetType: "context-graph",
+                });
+                const benchmarkQuestions = benchmarkSpec?.cases.length ?? 0;
+                const contextGraphReady = hasContextGraphBenchmarkTarget(projectDataDir, project);
+                return {
+                    name: project.name,
+                    benchmark_questions: benchmarkQuestions,
+                    context_graph_ready: contextGraphReady,
+                    can_run_benchmark: benchmarkQuestions > 0 && contextGraphReady,
+                    recommended_next_actions: contextGraphReady
+                        ? benchmarkQuestions > 0
+                            ? ["run benchmark", "improve Build Plan", "build again"]
+                            : ["draft benchmark questions", "build again"]
+                        : ["build"],
+                };
+            }),
+            sourceFolders: listSourceFolderChoices(projectDataDir),
+            recentProposals: listActionProposals(projectDataDir).slice(0, 5),
+        });
+    }
+    catch {
+        return ActionProposalPlanSchema.parse({
+            action_type: "clarification",
+            ...(request.project ? { project: request.project } : {}),
+            assistant_message: ACTION_PLANNER_CLARIFICATION_MESSAGE,
+        });
+    }
+    const parsed = ActionProposalPlanSchema.safeParse(sanitizeActionProposalPlan(rawPlan));
+    if (parsed.success)
+        return parsed.data;
+    return ActionProposalPlanSchema.parse({
+        action_type: "clarification",
+        ...(request.project ? { project: request.project } : {}),
+        assistant_message: ACTION_PLANNER_CLARIFICATION_MESSAGE,
+    });
+}
+function directServiceActionClarification(options) {
+    const endpoint = directServiceEndpointForAction(options.actionType, {
+        project: options.project,
+    });
+    if (!endpoint) {
+        throw new Error(`Action "${options.actionType}" is not a direct deterministic service action.`);
+    }
+    const label = options.actionType === "project-setup"
+        ? "Project setup"
+        : options.actionType === "build-plan-change"
+            ? "Build Plan change"
+            : "Project change";
+    const now = new Date().toISOString();
+    return ActionProposalResourceSchema.parse({
+        kind: "interf-action-proposal",
+        version: 1,
+        proposal_id: createActionProposalId(),
+        status: "needs_clarification",
+        action_type: "clarification",
+        title: `${label} uses a direct service endpoint`,
+        summary: `${label} is deterministic and is not accepted through action proposals.`,
+        assistant_message: `${label} must be submitted directly to ${endpoint}. Action proposals are only for freeform planning or async local-agent-backed work.`,
+        message: options.message,
+        project: options.project ?? null,
+        build_plan: options.buildPlan ?? null,
+        request: {
+            message: options.message,
+            endpoint,
+            action_type: options.actionType,
+            ...(options.values ? { values: options.values } : {}),
+        },
+        created_at: now,
+        updated_at: now,
+        proposed_by_executor: getExecutorStatus().executor,
+        approval: null,
+        submitted_run_id: null,
+        submitted_run_type: null,
+        error: null,
+    });
+}
+async function buildActionProposal(runtime, projectDataDir, request) {
+    const structuredProjectSetup = ProjectSetupActionValuesSchema.safeParse(request.values);
+    const structuredBuildPlanAuthoring = BuildPlanAuthoringActionValuesSchema.safeParse(request.values);
+    const structuredActionType = actionTypeFromValues(request.values);
+    const structuredDirectActionType = structuredProjectSetup.success
+        ? "project-setup"
+        : structuredActionType && directServiceEndpointForAction(structuredActionType)
+            ? structuredActionType
+            : null;
+    if (structuredDirectActionType) {
+        return directServiceActionClarification({
+            actionType: structuredDirectActionType,
+            message: request.message,
+            buildPlan: stringValue(request.values, "build_plan") ??
+                stringValue(request.values, "build_plan_id") ??
+                stringValue(request.values, "new_build_plan_id"),
+            project: request.project ?? stringValue(request.values, "project") ?? stringValue(request.values, "name"),
+            values: request.values,
+        });
+    }
+    const structuredPlanActionType = structuredBuildPlanAuthoring.success ? "build-plan-draft" : structuredActionType;
+    // Typed UI/CLI actions already carry the service contract; only freeform chat needs planner inference.
+    const plan = structuredPlanActionType
+        ? ActionProposalPlanSchema.parse({
+            action_type: structuredPlanActionType,
+            ...(request.project ? { project: request.project } : {}),
+        })
+        : await planActionProposal(runtime, projectDataDir, request);
+    const actionType = structuredPlanActionType ?? plan.action_type;
+    if (directServiceEndpointForAction(actionType)) {
+        return directServiceActionClarification({
+            actionType,
+            message: request.message,
+            buildPlan: plan.build_plan ??
+                stringValue(plan.values, "build_plan") ??
+                stringValue(plan.values, "build_plan_id") ??
+                stringValue(request.values, "build_plan") ??
+                stringValue(request.values, "build_plan_id"),
+            project: plan.project ?? request.project ?? stringValue(plan.values, "project") ?? stringValue(request.values, "project"),
+            values: {
+                ...(plan.values ?? {}),
+                ...(request.values ?? {}),
+            },
+        });
+    }
+    const usePlannerText = !structuredPlanActionType && plan.action_type === actionType;
+    const now = new Date().toISOString();
+    if (actionType === "clarification") {
+        return ActionProposalResourceSchema.parse({
+            kind: "interf-action-proposal",
+            version: 1,
+            proposal_id: createActionProposalId(),
+            status: "needs_clarification",
+            action_type: actionType,
+            title: plan.title ?? "Clarify Interf action",
+            summary: plan.summary ?? "No local run was proposed because the request did not resolve to a confirmed Interf action.",
+            assistant_message: plan.assistant_message ?? ACTION_PLANNER_CLARIFICATION_MESSAGE,
+            ...(plan.command_preview ? { command_preview: plan.command_preview } : {}),
+            message: request.message,
+            project: plan.project ?? request.project ?? null,
+            build_plan: plan.build_plan ?? null,
+            request: {
+                message: request.message,
+                ...(plan.values ? { values: plan.values } : {}),
+            },
+            created_at: now,
+            updated_at: now,
+            proposed_by_executor: getExecutorStatus().executor,
+            approval: null,
+            submitted_run_id: null,
+            submitted_run_type: null,
+            error: null,
+        });
+    }
+    const proposalValues = {
+        ...(plan.values ?? {}),
+        ...(request.values ?? {}),
+    };
+    if (actionType === "build-plan-draft" || actionType === "build-plan-improvement") {
+        const requestedProjectName = plan.project ?? request.project ?? null;
+        const fallbackProject = requestedProjectName
+            ? null
+            : listProjectConfigs(loadSourceFolderConfig(projectDataDir))[0] ?? null;
+        const projectConfig = requestedProjectName
+            ? runtime.resolveProjectConfig(projectDataDir, requestedProjectName)
+            : fallbackProject;
+        const projectPath = projectConfig
+            ? resolveProjectSourceBindingPath(projectDataDir, projectConfig)
+            : resolveConfiguredSourceFolderPath(projectDataDir) ?? projectDataDir;
+        const requestedBuildPlanId = stringValue(request.values, "build_plan_id") ??
+            stringValue(request.values, "build_plan");
+        const plannedBuildPlanId = plan.build_plan ??
+            stringValue(plan.values, "build_plan_id") ??
+            stringValue(plan.values, "build_plan");
+        const buildPlanId = requestedBuildPlanId ?? plannedBuildPlanId ?? buildPlanIdForProposal(request.message, proposalValues);
+        const intent = actionValueBuildPlanIntent(proposalValues) ??
+            stringValue(proposalValues, "intent") ??
+            buildPlanAuthoringPromptFallback(request.message, buildPlanId);
+        const hint = stringValue(proposalValues, "hint") ?? buildPlanAuthoringHintFromPrompt(intent);
+        const explicitRequestedArtifacts = requestedArtifactsFromProposalValues(proposalValues);
+        const requestedArtifacts = requestedArtifactsForPlanAuthoring({
+            projectDataDir,
+            projectConfig: projectConfig ?? null,
+            explicitRequestedArtifacts,
+        });
+        const explicitArtifactRequirements = artifactRequirementsFromProposalValues(proposalValues);
+        const baseBuildPlanId = stringValue(proposalValues, "base_build_plan_id");
+        const referenceBuildPlanId = stringValue(proposalValues, "reference_build_plan_id");
+        const userPrepInstructions = stringValue(proposalValues, "user_prep_instructions");
+        const actionRequest = {
+            project: projectConfig?.name ?? null,
+            source_folder_path: projectPath,
+            build_plan_id: buildPlanId,
+            ...(baseBuildPlanId ? { base_build_plan_id: baseBuildPlanId } : {}),
+            ...(referenceBuildPlanId ? { reference_build_plan_id: referenceBuildPlanId } : {}),
+            label: stringValue(proposalValues, "label") ?? buildPlanLabelFromId(buildPlanId),
+            hint,
+            intent,
+            checks: contextChecksFromProposalValues(proposalValues) ?? [],
+            ...(userPrepInstructions ? { user_prep_instructions: userPrepInstructions } : {}),
+            requested_artifacts: requestedArtifacts,
+            source_context: proposalValues.source_context ?? null,
+            artifact_requirements: artifactRequirementsForPlanAuthoring({
+                projectDataDir,
+                projectConfig: projectConfig ?? null,
+                requestedArtifacts,
+                explicitArtifactRequirements,
+            }),
+        };
+        const commandPreview = (usePlannerText ? plan.command_preview : undefined) ??
+            actionCommandPreview(actionType, projectConfig?.name ?? null, buildPlanId, proposalValues);
+        return ActionProposalResourceSchema.parse({
+            kind: "interf-action-proposal",
+            version: 1,
+            proposal_id: createActionProposalId(),
+            status: "awaiting_approval",
+            action_type: actionType,
+            title: (usePlannerText ? plan.title : undefined) ?? `Draft Build Plan ${buildPlanId}`,
+            summary: (usePlannerText ? plan.summary : undefined) ?? "Ask the configured local executor to draft a Build Plan for requested Artifacts and Context Checks.",
+            assistant_message: (usePlannerText ? plan.assistant_message : undefined) ??
+                actionAssistantMessage(actionType, projectConfig?.name ?? null, commandPreview),
+            command_preview: commandPreview,
+            message: request.message,
+            project: projectConfig?.name ?? null,
+            build_plan: buildPlanId,
+            request: actionRequest,
+            created_at: now,
+            updated_at: now,
+            proposed_by_executor: getExecutorStatus().executor,
+            approval: null,
+            submitted_run_id: null,
+            submitted_run_type: null,
+            error: null,
+        });
+    }
+    const projectConfig = runtime.resolveProjectConfig(projectDataDir, plan.project ?? request.project ?? runtime.defaultProjectId(projectDataDir));
+    const proposalActionType = ActionProposalTypeSchema.parse(actionType);
+    const projectPath = resolveProjectSourceBindingPath(projectDataDir, projectConfig);
+    const requestedBuildPlanId = stringValue(request.values, "build_plan_id") ??
+        stringValue(request.values, "build_plan");
+    const plannedBuildPlanId = plan.build_plan ??
+        stringValue(plan.values, "build_plan_id") ??
+        stringValue(plan.values, "build_plan");
+    const buildPlanId = requestedBuildPlanId ?? plannedBuildPlanId ?? buildPlanIdForProjectConfig(projectConfig);
+    const clarifyResolvedAction = (options) => ActionProposalResourceSchema.parse({
+        kind: "interf-action-proposal",
+        version: 1,
+        proposal_id: createActionProposalId(),
+        status: "needs_clarification",
+        action_type: "clarification",
+        title: options.title,
+        summary: options.summary,
+        assistant_message: options.assistantMessage,
+        message: request.message,
+        project: projectConfig.name,
+        build_plan: buildPlanId ?? null,
+        request: {
+            message: request.message,
+            ...(proposalValues ? { values: proposalValues } : {}),
+        },
+        created_at: now,
+        updated_at: now,
+        proposed_by_executor: getExecutorStatus().executor,
+        approval: null,
+        submitted_run_id: null,
+        submitted_run_type: null,
+        error: null,
+    });
+    const requestedBenchmarkMode = actionType === "benchmark"
+        ? benchmarkModeFromValues(proposalValues)
+        : null;
+    if (actionType === "benchmark") {
+        const benchmarkSpec = buildTestSpecFromSourceFolderConfig({
+            projectDataDir,
+            targetName: projectConfig.name,
+            targetType: requestedBenchmarkMode === "source-files" ? "source-files" : "context-graph",
+        });
+        const hasBenchmarkChecks = (benchmarkSpec?.cases.length ?? 0) > 0;
+        const contextGraphReady = hasContextGraphBenchmarkTarget(projectDataDir, projectConfig);
+        if (!hasBenchmarkChecks) {
+            return clarifyResolvedAction({
+                title: `Add benchmark questions for ${projectConfig.name}`,
+                summary: "Benchmark evaluation needs saved Q&A / fact-check questions.",
+                assistantMessage: `Project "${projectConfig.name}" does not have saved benchmark questions yet. Ask me to draft benchmark questions after the Source is ready, or add evaluation guidance first.`,
+            });
+        }
+        if (!contextGraphReady) {
+            return clarifyResolvedAction({
+                title: `Build ${projectConfig.name} first`,
+                summary: "Benchmark evaluation needs a built Context Graph with a recorded Source Manifest.",
+                assistantMessage: `Project "${projectConfig.name}" has no built Context Graph yet. Build it first; after that Interf can run source-files and Context Graph benchmark targets from the same recorded Source Manifest.`,
+            });
+        }
+    }
+    const actionRequest = (() => {
+        if (actionType === "build") {
+            return {
+                project: projectConfig.name,
+            };
+        }
+        if (actionType === "benchmark") {
+            return {
+                project: projectConfig.name,
+                target: requestedBenchmarkMode ?? "both",
+            };
+        }
+        if (actionType === "benchmark-question-draft") {
+            return {
+                project: projectConfig.name,
+                source_folder_path: projectPath,
+                intent: stringValue(proposalValues, "intent") ?? request.message,
+                target_count: Math.max(1, Math.min(8, Math.round(numberValue(proposalValues, "target_count") ?? 4))),
+            };
+        }
+        const fallbackBuildPlanId = buildPlanId ?? buildPlanIdForProposal(request.message, proposalValues);
+        const intent = actionValueBuildPlanIntent(proposalValues) ??
+            stringValue(proposalValues, "intent") ??
+            buildPlanAuthoringPromptFallback(request.message, fallbackBuildPlanId);
+        const hint = stringValue(proposalValues, "hint") ?? buildPlanAuthoringHintFromPrompt(intent);
+        const explicitRequestedArtifacts = requestedArtifactsFromProposalValues(proposalValues);
+        const requestedArtifacts = requestedArtifactsForPlanAuthoring({
+            projectDataDir,
+            projectConfig: projectConfig,
+            explicitRequestedArtifacts,
+        });
+        const explicitArtifactRequirements = artifactRequirementsFromProposalValues(proposalValues);
+        const baseBuildPlanId = stringValue(proposalValues, "base_build_plan_id");
+        const referenceBuildPlanId = stringValue(proposalValues, "reference_build_plan_id");
+        const userPrepInstructions = stringValue(proposalValues, "user_prep_instructions");
+        return {
+            project: projectConfig.name,
+            source_folder_path: projectPath,
+            build_plan_id: fallbackBuildPlanId,
+            ...(baseBuildPlanId ? { base_build_plan_id: baseBuildPlanId } : {}),
+            ...(referenceBuildPlanId ? { reference_build_plan_id: referenceBuildPlanId } : {}),
+            label: stringValue(proposalValues, "label") ?? buildPlanLabelFromId(fallbackBuildPlanId),
+            hint,
+            intent,
+            checks: contextChecksFromProposalValues(proposalValues) ?? [],
+            ...(userPrepInstructions ? { user_prep_instructions: userPrepInstructions } : {}),
+            requested_artifacts: requestedArtifacts,
+            source_context: proposalValues.source_context ?? null,
+            artifact_requirements: artifactRequirementsForPlanAuthoring({
+                projectDataDir,
+                projectConfig: projectConfig,
+                requestedArtifacts,
+                explicitArtifactRequirements,
+            }),
+        };
+    })();
+    const title = (() => {
+        if (plan.title)
+            return plan.title;
+        if (proposalActionType === "build")
+            return `Build ${projectConfig.name}`;
+        if (proposalActionType === "benchmark")
+            return `Benchmark ${projectConfig.name}`;
+        if (proposalActionType === "benchmark-question-draft")
+            return `Draft benchmark questions for ${projectConfig.name}`;
+        return `Draft Build Plan ${buildPlanId}`;
+    })();
+    const summary = (() => {
+        if (plan.summary)
+            return plan.summary;
+        if (proposalActionType === "build")
+            return "Build a Context Graph with summaries, claims, links back to sources, Build evidence, and traces.";
+        if (proposalActionType === "benchmark")
+            return "Run Q&A / fact-check benchmarks against source files and Context Graph.";
+        if (proposalActionType === "benchmark-question-draft")
+            return "Ask the configured local executor to draft saved Q&A / fact-check evaluation questions.";
+        return "Ask the configured local executor to draft a Build Plan for requested Artifacts and Context Checks.";
+    })();
+    const previewValues = proposalValues;
+    const commandPreview = plan.command_preview ?? actionCommandPreview(proposalActionType, projectConfig.name, buildPlanId, previewValues);
+    return ActionProposalResourceSchema.parse({
+        kind: "interf-action-proposal",
+        version: 1,
+        proposal_id: createActionProposalId(),
+        status: "awaiting_approval",
+        action_type: proposalActionType,
+        title,
+        summary,
+        assistant_message: plan.assistant_message ?? actionAssistantMessage(proposalActionType, projectConfig.name, commandPreview),
+        command_preview: commandPreview,
+        message: request.message,
+        project: projectConfig.name,
+        build_plan: buildPlanId,
+        request: actionRequest,
+        created_at: now,
+        updated_at: now,
+        proposed_by_executor: getExecutorStatus().executor,
+        approval: null,
+        submitted_run_id: null,
+        submitted_run_type: null,
+        error: null,
+    });
+}
+async function submitActionProposal(runtime, projectDataDir, proposal) {
+    if (proposal.action_type === "clarification") {
+        throw new Error("Clarification proposals cannot be submitted.");
+    }
+    if (proposal.action_type === "build") {
+        const resource = await runtime.createBuildRun(projectDataDir, proposal.request);
+        return {
+            runId: resource.run.run_id,
+            runType: "build-run",
+        };
+    }
+    if (proposal.action_type === "benchmark") {
+        const resource = await runtime.createVerifyRun(projectDataDir, proposal.request);
+        return {
+            runId: resource.run_id,
+            runType: "verify-run",
+        };
+    }
+    if (proposal.action_type === "benchmark-question-draft") {
+        const job = await runtime.createBenchmarkQuestionDraftRun(projectDataDir, proposal.request);
+        return {
+            runId: job.run_id,
+            runType: "job-run",
+        };
+    }
+    const directEndpoint = directServiceEndpointForAction(proposal.action_type, {
+        project: proposal.project,
+    });
+    if (directEndpoint) {
+        throw new Error(`Action "${proposal.action_type}" must be submitted directly to ${directEndpoint}.`);
+    }
+    const job = await runtime.createBuildPlanAuthoringRun(projectDataDir, proposal.request, proposal.action_type === "build-plan-improvement" ? "build-plan-improvement" : "build-plan-draft");
+    return {
+        runId: job.run_id,
+        runType: "job-run",
+    };
+}

package/dist/packages/runtime/runtime-build-plans.d.ts

@@ -0,0 +1,5 @@
+import { type BuildPlanChangeResult, type BuildPlanResource } from "./schemas/index.js";
+import type { LocalServiceRuntime } from "./runtime.js";
+export declare function listBuildPlans(runtime: LocalServiceRuntime, projectDataDir: string): BuildPlanResource[];
+export declare function getBuildPlanResource(runtime: LocalServiceRuntime, projectDataDir: string, buildPlanId: string): BuildPlanResource | null;
+export declare function applyBuildPlanChange(runtime: LocalServiceRuntime, projectDataDir: string, requestValue: unknown): BuildPlanChangeResult;

package/dist/packages/runtime/runtime-build-plans.js

@@ -0,0 +1,131 @@
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { asProjectDataDir, projectBuildPlansRoot, userBuildPlansRoot, } from "../contracts/lib/project-paths.js";
+import { buildPlanIdForProjectConfig, DEFAULT_BUILD_PLAN_ID, listProjectConfigs, loadSourceFolderConfig, saveSourceFolderConfig, } from "../projects/source-config.js";
+import { listBuildPlanChoices, } from "../build-plans/package/build-plan-definitions.js";
+import { buildPlanDefinitionPath, resolveBuildPlanPackageSourcePath, } from "../build-plans/package/local-build-plans.js";
+import { seedLocalBuildPlanPackageFromBase, } from "../build-plans/package/interf-build-plan-package.js";
+import { PACKAGE_ROOT } from "../build-plans/package/lib/package-root.js";
+import { buildBuildPlanResource, } from "./runtime-resource-builders.js";
+import { buildPlanLabelFromId, } from "./runtime-proposal-helpers.js";
+function detachBuildPlanFromProject(project, buildPlanId) {
+    if (buildPlanIdForProjectConfig(project) !== buildPlanId)
+        return project;
+    const { build_plan: _removedBuildPlan, ...detachedProject } = project;
+    return detachedProject;
+}
+import { BuildPlanChangeCreateRequestSchema, BuildPlanChangeResultSchema, } from "./schemas/index.js";
+export function listBuildPlans(runtime, projectDataDir) {
+    // The Build Plan choices list is dominated by repeated reads of
+    // build-plan.json + build-plan.schema.json across bundled, user-library, and
+    // Project-local Build Plan package roots. Key the cache off mtimes; if
+    // any of them changes (a new local Build Plan, an edit to the user
+    // library, etc.) the cache misses and we re-resolve.
+    const builtinRoot = join(PACKAGE_ROOT, "public-repo", "build-plans");
+    const localRoot = projectBuildPlansRoot(asProjectDataDir(projectDataDir));
+    const userRoot = userBuildPlansRoot();
+    return runtime.buildPlanListingCache.get(projectDataDir, [builtinRoot, localRoot, userRoot], () => {
+        const projects = listProjectConfigs(loadSourceFolderConfig(projectDataDir));
+        const choices = listBuildPlanChoices(projectDataDir);
+        return choices.map((buildPlan) => {
+            const activeForProjects = projects
+                .filter((project) => buildPlanIdForProjectConfig(project) === buildPlan.id)
+                .map((project) => project.name);
+            return buildBuildPlanResource({
+                id: buildPlan.id,
+                path: resolveBuildPlanPackageSourcePath(projectDataDir, buildPlan.id) ?? buildPlan.id,
+                label: buildPlan.label,
+                hint: buildPlan.hint,
+                purpose: buildPlan.purpose,
+                brief: buildPlan.brief,
+                inputs: buildPlan.inputs,
+                source_kind: buildPlan.scope === "builtin" ? "builtin" : "local",
+                built_in: buildPlan.scope === "builtin",
+                active_for_projects: activeForProjects,
+                artifacts: buildPlan.contextInterface?.artifacts ?? [],
+                stages: buildPlan.stages.map((stage) => ({
+                    id: stage.id,
+                    label: stage.label,
+                    description: stage.description,
+                    contract_type: stage.contractType,
+                    skill_dir: stage.skillDir,
+                    role: stage.role && stage.role.trim().length > 0 ? stage.role : "general",
+                    reads: stage.reads,
+                    writes: stage.writes,
+                })),
+            });
+        });
+    });
+}
+export function getBuildPlanResource(runtime, projectDataDir, buildPlanId) {
+    return listBuildPlans(runtime, projectDataDir).find((buildPlan) => buildPlan.id === buildPlanId) ?? null;
+}
+export function applyBuildPlanChange(runtime, projectDataDir, requestValue) {
+    const request = BuildPlanChangeCreateRequestSchema.parse(requestValue);
+    const buildPlanId = request.build_plan;
+    const outputPath = request.operation === "duplicate"
+        ? buildPlanDefinitionPath(projectDataDir, request.new_build_plan_id)
+        : buildPlanDefinitionPath(projectDataDir, buildPlanId);
+    if (request.operation === "duplicate") {
+        if (resolveBuildPlanPackageSourcePath(projectDataDir, request.new_build_plan_id)) {
+            throw new Error(`Build Plan "${request.new_build_plan_id}" already exists.`);
+        }
+        if (!resolveBuildPlanPackageSourcePath(projectDataDir, buildPlanId)) {
+            throw new Error(`Build Plan "${buildPlanId}" does not exist.`);
+        }
+        const label = request.label ?? buildPlanLabelFromId(request.new_build_plan_id);
+        const hint = request.hint ?? `Duplicate of ${buildPlanId}`;
+        const buildPlanPath = seedLocalBuildPlanPackageFromBase({
+            projectDataDir,
+            baseBuildPlanId: buildPlanId,
+            buildPlanId: request.new_build_plan_id,
+            label,
+            hint,
+        });
+        runtime.buildPlanListingCache.invalidate(projectDataDir);
+        return BuildPlanChangeResultSchema.parse({
+            kind: "interf-build-plan-change-result",
+            version: 1,
+            operation: "duplicate",
+            build_plan: buildPlanId,
+            new_build_plan_id: request.new_build_plan_id,
+            updated_projects: [],
+            build_plan_path: buildPlanPath,
+            changed: true,
+            message: `Duplicated Build Plan ${buildPlanId} as ${request.new_build_plan_id}.`,
+        });
+    }
+    if (request.confirmation !== buildPlanId) {
+        throw new Error(`Type ${buildPlanId} to confirm Build Plan removal.`);
+    }
+    const localBuildPlanPath = buildPlanDefinitionPath(projectDataDir, buildPlanId);
+    if (buildPlanId === DEFAULT_BUILD_PLAN_ID || !existsSync(localBuildPlanPath)) {
+        throw new Error(`Build Plan "${buildPlanId}" is not a removable local Build Plan.`);
+    }
+    const projects = listProjectConfigs(loadSourceFolderConfig(projectDataDir));
+    const updatedProjects = projects
+        .filter((project) => buildPlanIdForProjectConfig(project) === buildPlanId);
+    if (updatedProjects.length > 0) {
+        saveSourceFolderConfig(projectDataDir, {
+            projects: projects.map((project) => detachBuildPlanFromProject(project, buildPlanId)),
+        });
+        // Detaching a Build Plan changes readiness shape for those Projects.
+        for (const project of updatedProjects) {
+            runtime.readinessCache.invalidateProject(projectDataDir, project.name);
+        }
+    }
+    rmSync(outputPath, { recursive: true, force: true });
+    runtime.buildPlanListingCache.invalidate(projectDataDir);
+    return BuildPlanChangeResultSchema.parse({
+        kind: "interf-build-plan-change-result",
+        version: 1,
+        operation: "remove",
+        build_plan: buildPlanId,
+        updated_projects: updatedProjects.map((project) => project.name),
+        build_plan_path: outputPath,
+        changed: true,
+        message: updatedProjects.length > 0
+            ? `Removed Build Plan ${buildPlanId} and cleared it from ${updatedProjects.length} Project(s).`
+            : `Removed Build Plan ${buildPlanId}.`,
+    });
+}