@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/service/operations.js

@@ -1,15 +1,24 @@
 import { z } from "zod";
-import { TracesSchema } from "../../contracts/lib/project-schema.js";
-import { BuildEvidenceResourceSchema, ProjectIdSchema, } from "../../contracts/lib/schema.js";
-import { BuildPlanAuthoringCreateRequestSchema, BuildRunCreateRequestSchema, BuildRunResourceSchema, ContextGraphResourceSchema, InstanceResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ProjectCreateRequestSchema, ProjectWireShapeSchema, RunArtifactsResponseSchema, RunStatusResourceSchema, SourceFileListResponseSchema, SourceManifestResourceSchema, } from "../schemas/index.js";
+import { ContextGraphHandoffSchema, TracesSchema, } from "../../contracts/lib/project-schema.js";
+import { BuildEvidenceResourceSchema, GraphOutputCountsSchema, GraphManifestStageSummarySchema, GraphReadinessRollupSchema, MetricCountSchema, ProjectIdSchema, ResourceRefSchema, } from "../../contracts/lib/schema.js";
+import { BuildRunResourceSchema, ContextGraphResourceSchema, ContextGraphSessionResponseSchema, ContextGraphSessionsResponseSchema, InstanceResourceSchema, LocalJobRunResourceSchema, LocalServiceHealthSchema, ProjectCreateRequestSchema, ProjectBuildPlanAuthoringCreateRequestSchema, ProjectBuildRunCreateRequestSchema, ProjectListResponseSchema, ProjectResourceSchema, ProjectWireShapeSchema, ReadinessResourceSchema, RunArtifactsResponseSchema, RunEventsResponseSchema, RunStatusResourceSchema, SourceFileListResponseSchema, SourceManifestResourceSchema, } from "../schemas/index.js";
 const EmptyObjectSchema = z.object({}).strict();
 const OpenApiDocumentSchema = z.record(z.string(), z.unknown());
-const ProjectBuildRunCreateRequestSchema = BuildRunCreateRequestSchema
-    .omit({ project: true })
-    .strict();
-const PrepareBuildPlanRequestSchema = BuildPlanAuthoringCreateRequestSchema
-    .omit({ project: true, source_folder_path: true })
-    .strict();
+const ContextGraphStagesResponseSchema = z.object({
+    stages: z.array(GraphManifestStageSummarySchema),
+    readiness: GraphReadinessRollupSchema.nullable(),
+    primary_metrics: z.array(MetricCountSchema),
+}).strict();
+const ContextGraphResourcesResponseSchema = z.object({
+    resources: z.array(ResourceRefSchema),
+    entrypoints: z.array(ResourceRefSchema),
+    graph_outputs: GraphOutputCountsSchema.nullable(),
+}).strict();
+const ContextGraphResourceRefResponseSchema = z.object({
+    resource: ResourceRefSchema,
+    stage: GraphManifestStageSummarySchema.nullable(),
+    linked_resources: z.array(ResourceRefSchema),
+}).strict();
 const ProjectIdParameter = {
     name: "project_id",
     in: "path",
@@ -31,6 +40,20 @@ const ContextGraphFilePathParameter = {
     description: "Relative file path inside the latest Context Graph.",
     schema: z.string().min(1),
 };
+const ContextGraphResourceIdParameter = {
+    name: "resource_id",
+    in: "path",
+    required: true,
+    description: "ResourceRef id from the latest Context Graph manifest.",
+    schema: z.string().min(1),
+};
+const StageRunIdParameter = {
+    name: "stage_run_id",
+    in: "path",
+    required: true,
+    description: "Stage execution session id from the latest Build run.",
+    schema: z.string().min(1),
+};
 const RunFilePathParameter = {
     name: "path",
     in: "query",
@@ -72,13 +95,24 @@ export const SERVICE_OPERATIONS = [
         response_schema: OpenApiDocumentSchema,
         success_status: 200,
     },
+    {
+        id: "listProjects",
+        method: "GET",
+        path: "/v1/projects",
+        tags: ["Projects"],
+        summary: "List Projects",
+        description: "Return Projects registered on this instance with Source bindings, intent, Build Plan selection, and Context Graph locators.",
+        visibility: "app",
+        response_schema: ProjectListResponseSchema,
+        success_status: 200,
+    },
     {
         id: "createProject",
         method: "POST",
         path: "/v1/projects",
         tags: ["Projects"],
         summary: "Create Project",
-        description: "Create a Project bound to one Source. Project ids may be generated by clients.",
+        description: "Create a Project bound to one Source and one agent task intent. Project ids may be generated by clients.",
         visibility: "app",
         workflow_step: 1,
         request_schema: ProjectCreateRequestSchema,
@@ -94,7 +128,7 @@ export const SERVICE_OPERATIONS = [
         description: "Read one Project to confirm its Source binding, selected Build Plan, readiness, and latest Context Graph.",
         visibility: "app",
         parameters: [ProjectIdParameter],
-        response_schema: ProjectWireShapeSchema,
+        response_schema: ProjectResourceSchema,
         success_status: 200,
     },
     {
@@ -103,11 +137,11 @@ export const SERVICE_OPERATIONS = [
         path: "/v1/projects/{project_id}/build-plan-drafts",
         tags: ["Build Plans"],
         summary: "Prepare Build Plan",
-        description: "Draft a Build Plan from the approved intent, Context Checks, and requested Artifacts. This does not run a Build.",
+        description: "Draft a Build Plan from the Project intent, requested outputs, and coverage expectations. This does not run a Build.",
         visibility: "app",
         workflow_step: 2,
         parameters: [ProjectIdParameter],
-        request_schema: PrepareBuildPlanRequestSchema,
+        request_schema: ProjectBuildPlanAuthoringCreateRequestSchema,
         response_schema: LocalJobRunResourceSchema,
         success_status: 202,
     },
@@ -149,6 +183,18 @@ export const SERVICE_OPERATIONS = [
         response_schema: RunArtifactsResponseSchema,
         success_status: 200,
     },
+    {
+        id: "getRunEvents",
+        method: "GET",
+        path: "/v1/runs/{run_id}/events",
+        tags: ["Runs"],
+        summary: "Get Run events",
+        description: "Read the durable event log for a Build run: stage start/pass/fail, files processed, artifacts written, evidence, checks, and readiness. Use compact status for polling; read events to inspect or replay what happened.",
+        visibility: "app",
+        parameters: [RunIdParameter],
+        response_schema: RunEventsResponseSchema,
+        success_status: 200,
+    },
     {
         id: "readRunFile",
         method: "GET",
@@ -168,12 +214,84 @@ export const SERVICE_OPERATIONS = [
         path: "/v1/projects/{project_id}/context-graph",
         tags: ["Context Graphs"],
         summary: "Get latest Context Graph",
-        description: "Return the latest successful Context Graph locator and readiness state for a Project. This is a compact locator/status read; read artifacts/ handoff files before answering.",
+        description: "Return the latest successful Context Graph locator, GraphManifest, primary metrics, StageManifest summaries, entrypoints, and ready/not ready rollup for a Project.",
         visibility: "app",
         parameters: [ProjectIdParameter],
         response_schema: ContextGraphResourceSchema,
         success_status: 200,
     },
+    {
+        id: "listContextGraphStages",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/stages",
+        tags: ["Context Graphs"],
+        summary: "List Context Graph StageManifests",
+        description: "Return StageManifest summaries for the latest Context Graph.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: ContextGraphStagesResponseSchema,
+        success_status: 200,
+    },
+    {
+        id: "listContextGraphResources",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/resources",
+        tags: ["Context Graphs"],
+        summary: "List Context Graph resources",
+        description: "Return the ResourceRef index from the latest GraphManifest.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: ContextGraphResourcesResponseSchema,
+        success_status: 200,
+    },
+    {
+        id: "listContextGraphSessions",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/sessions",
+        tags: ["Context Graphs"],
+        summary: "List Context Graph execution sessions",
+        description: "Return replayable per-stage execution shell sessions for the latest Build run, including workspace, prompt, logs, validation attempts, and stage contract paths.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: ContextGraphSessionsResponseSchema,
+        success_status: 200,
+    },
+    {
+        id: "getContextGraphResource",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/resources/{resource_id}",
+        tags: ["Context Graphs"],
+        summary: "Get Context Graph resource",
+        description: "Return one ResourceRef from the latest GraphManifest for inspector drilldown.",
+        visibility: "app",
+        parameters: [ProjectIdParameter, ContextGraphResourceIdParameter],
+        response_schema: ContextGraphResourceRefResponseSchema,
+        success_status: 200,
+    },
+    {
+        id: "getContextGraphSession",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/sessions/{stage_run_id}",
+        tags: ["Context Graphs"],
+        summary: "Get Context Graph execution session",
+        description: "Return one replayable stage execution shell session for inspector drilldown.",
+        visibility: "app",
+        parameters: [ProjectIdParameter, StageRunIdParameter],
+        response_schema: ContextGraphSessionResponseSchema,
+        success_status: 200,
+    },
+    {
+        id: "getProjectReadiness",
+        method: "GET",
+        path: "/v1/projects/{project_id}/readiness",
+        tags: ["Context Graphs"],
+        summary: "Get Project readiness",
+        description: "Read the ready/not ready verdict for the latest Context Graph against the Project intent.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: ReadinessResourceSchema,
+        success_status: 200,
+    },
     {
         id: "listSourceFiles",
         method: "GET",
@@ -198,13 +316,25 @@ export const SERVICE_OPERATIONS = [
         response_schema: SourceManifestResourceSchema,
         success_status: 200,
     },
+    {
+        id: "getContextGraphEntrypoint",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/entrypoint",
+        tags: ["Context Graphs"],
+        summary: "Get Context Graph entrypoint",
+        description: "Return the primary downstream entrypoint for the latest Context Graph. Agents should start from home.md.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: ContextGraphHandoffSchema,
+        success_status: 200,
+    },
     {
         id: "readContextGraphFile",
         method: "GET",
         path: "/v1/projects/{project_id}/context-graph/file",
         tags: ["Context Graphs"],
         summary: "Read Context Graph file",
-        description: "Read one file from the latest Context Graph by relative path. Start with artifacts/ task handoffs; use summaries/ for coverage proof and knowledge/ for drilldown.",
+        description: "Read one file from the latest Context Graph by relative path. Start with home.md; use knowledge/ for task-specific notes and summaries/ for source-backed coverage.",
         visibility: "app",
         parameters: [ProjectIdParameter, ContextGraphFilePathParameter],
         response_schema: z.string(),
@@ -228,8 +358,8 @@ export const SERVICE_OPERATIONS = [
         method: "GET",
         path: "/v1/projects/{project_id}/context-graph/evidence",
         tags: ["Context Graphs"],
-        summary: "Get Build evidence",
-        description: "Read checks, Artifact diagnostics, and readiness evidence for the latest Context Graph.",
+        summary: "Get graph diagnostics",
+        description: "Read supplemental diagnostic rows for the latest Context Graph. GraphManifest primary metrics are the authoritative coverage summary.",
         visibility: "app",
         parameters: [ProjectIdParameter],
         response_schema: BuildEvidenceResourceSchema,

package/dist/packages/runtime/service/routes.d.ts

@@ -57,15 +57,23 @@ export declare const PROJECT_SUBRESOURCES: {
     readonly contextGraph: "context-graph";
     /** First-class traces surface — per-claim provenance back to source. */
     readonly traces: "context-graph/traces";
-    /** First-class Checks / Build evidence review resource. */
+    /** Stage Manifest summaries for the latest Context Graph. */
+    readonly contextGraphStages: "context-graph/stages";
+    /** Replayable stage execution shell sessions for the latest Build run. */
+    readonly contextGraphSessions: "context-graph/sessions";
+    /** ResourceRef index for the latest Context Graph. */
+    readonly contextGraphResources: "context-graph/resources";
+    /** Supplemental graph diagnostics. Graph Manifest metrics are authoritative. */
     readonly buildEvidence: "context-graph/evidence";
+    /** Primary downstream graph entrypoint. */
+    readonly contextGraphEntrypoint: "context-graph/entrypoint";
     /** Read a single Context Graph file using a query param: `?path=<relpath>`. */
     readonly contextGraphFile: "context-graph/file";
     /** Drift state for the Project's Source binding. */
     readonly sourceState: "source-state";
     /**
-     * per-Artifact detail. Returns the latest status, contributing stages,
-     * and check evidence for a Build Plan-declared Artifact:
+     * Per-output detail. Returns the latest status, contributing stages,
+     * and diagnostics for a Build Plan-declared requested output:
      *   GET /v1/projects/<id>/artifacts/<artifact-id>
      */
     readonly artifacts: "artifacts";

package/dist/packages/runtime/service/routes.js

@@ -58,15 +58,23 @@ export const PROJECT_SUBRESOURCES = {
     contextGraph: "context-graph",
     /** First-class traces surface — per-claim provenance back to source. */
     traces: "context-graph/traces",
-    /** First-class Checks / Build evidence review resource. */
+    /** Stage Manifest summaries for the latest Context Graph. */
+    contextGraphStages: "context-graph/stages",
+    /** Replayable stage execution shell sessions for the latest Build run. */
+    contextGraphSessions: "context-graph/sessions",
+    /** ResourceRef index for the latest Context Graph. */
+    contextGraphResources: "context-graph/resources",
+    /** Supplemental graph diagnostics. Graph Manifest metrics are authoritative. */
     buildEvidence: "context-graph/evidence",
+    /** Primary downstream graph entrypoint. */
+    contextGraphEntrypoint: "context-graph/entrypoint",
     /** Read a single Context Graph file using a query param: `?path=<relpath>`. */
     contextGraphFile: "context-graph/file",
     /** Drift state for the Project's Source binding. */
     sourceState: "source-state",
     /**
-     * per-Artifact detail. Returns the latest status, contributing stages,
-     * and check evidence for a Build Plan-declared Artifact:
+     * Per-output detail. Returns the latest status, contributing stages,
+     * and diagnostics for a Build Plan-declared requested output:
      *   GET /v1/projects/<id>/artifacts/<artifact-id>
      */
     artifacts: "artifacts",

package/dist/packages/runtime/service/server-app-boot.js

@@ -35,12 +35,12 @@ export function sendDesktopAppBoot(req, res, runtime) {
   <script id="interf-app-boot" type="application/json">${json}</script>
 </head>
 <body>
-  <p>Interf local service is running. Open Interf.app to use the desktop interface.</p>
+  <p>Interf local service is running.</p>
 </body>
 </html>
 `);
     return true;
 }
 export function sendServiceNotFound(res) {
-    sendText(res, 404, "Not found. Open Interf.app for the desktop interface.\n");
+    sendText(res, 404, "Not found. Interf local service is running.\n");
 }

package/dist/packages/runtime/service/server-helpers.d.ts

@@ -25,3 +25,14 @@ export declare function sendError(res: ServerResponse, statusCode: number, conte
 export declare function sendErrorResponse(res: ServerResponse, error: unknown, fallbackStatus?: number): void;
 export declare function readJsonBody(req: IncomingMessage): Promise<unknown>;
 export declare function parseRequestUrl(req: IncomingMessage): URL;
+/**
+ * Decode a single percent-encoded path segment, or send a structured 400 and
+ * return `null`. `decodeURIComponent` throws a `URIError` on malformed input
+ * (e.g. a truncated escape like `%E0%A4%A`); left unguarded that crashes the
+ * handler into an uncaught 500. Routing every guarded call site through this
+ * helper keeps the decode semantics and the 400 message single-sourced.
+ *
+ * `label` names the id in the error message, e.g. `"Run id"` ->
+ * `"Run id is not valid URI-encoded UTF-8."`.
+ */
+export declare function decodeOr400(res: ServerResponse, raw: string, label: string): string | null;

package/dist/packages/runtime/service/server-helpers.js

@@ -87,3 +87,22 @@ export async function readJsonBody(req) {
 export function parseRequestUrl(req) {
     return new URL(req.url ?? "/", "http://127.0.0.1");
 }
+/**
+ * Decode a single percent-encoded path segment, or send a structured 400 and
+ * return `null`. `decodeURIComponent` throws a `URIError` on malformed input
+ * (e.g. a truncated escape like `%E0%A4%A`); left unguarded that crashes the
+ * handler into an uncaught 500. Routing every guarded call site through this
+ * helper keeps the decode semantics and the 400 message single-sourced.
+ *
+ * `label` names the id in the error message, e.g. `"Run id"` ->
+ * `"Run id is not valid URI-encoded UTF-8."`.
+ */
+export function decodeOr400(res, raw, label) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        sendError(res, 400, `${label} is not valid URI-encoded UTF-8.`);
+        return null;
+    }
+}

package/dist/packages/runtime/service/server-routes-action-proposals.js

@@ -1,5 +1,5 @@
 import { LOCAL_SERVICE_ROUTES } from "./routes.js";
-import { readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { decodeOr400, readJsonBody, sendError, sendJson, } from "./server-helpers.js";
 import { listStoredProjects } from "../project-store.js";
 export async function tryHandleActionProposals(req, res, runtime, path, method) {
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.actionProposals) {
@@ -17,7 +17,9 @@ export async function tryHandleActionProposals(req, res, runtime, path, method)
     }
     const actionProposalMatch = path.match(/^\/v1\/action-proposals\/([^/]+)(?:\/([^/]+))?$/);
     if (actionProposalMatch?.[1]) {
-        const proposalId = decodeURIComponent(actionProposalMatch[1]);
+        const proposalId = decodeOr400(res, actionProposalMatch[1], "Action proposal id");
+        if (proposalId === null)
+            return true;
         const child = actionProposalMatch[2];
         const firstProject = listStoredProjects()[0];
         const projectDataDir = firstProject?.projectDataDir ?? runtime.rootPath;

package/dist/packages/runtime/service/server-routes-agents.js

@@ -1,8 +1,8 @@
 import { join } from "node:path";
-import { InterfMcpHandoffSchema } from "../schemas/index.js";
+import { AgentPrefsPatchSchema, AgentRoleMapPatchSchema, CustomAgentRegisterRequestSchema, InterfMcpHandoffSchema, } from "../schemas/index.js";
 import { buildInterfMcpHandoff } from "../agent-handoff.js";
 import { buildLocalServiceUrl, LOCAL_SERVICE_ROUTES } from "./routes.js";
-import { readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { decodeOr400, readJsonBody, sendError, sendJson, } from "./server-helpers.js";
 import { packageRoot } from "./server-api-files.js";
 export async function tryHandleExecutor(req, res, runtime, path, method) {
     if (method === "GET" && path === LOCAL_SERVICE_ROUTES.executor) {
@@ -24,28 +24,8 @@ export async function tryHandleAgents(req, res, runtime, path, method) {
         }
         if (method === "POST") {
             try {
-                const body = (await readJsonBody(req));
-                if (!body || typeof body !== "object") {
-                    sendError(res, 400, "Request body must be a JSON object.");
-                    return true;
-                }
-                if (!body.name || typeof body.name !== "string") {
-                    sendError(res, 400, "Missing required field: name");
-                    return true;
-                }
-                if (!body.display_name || typeof body.display_name !== "string") {
-                    sendError(res, 400, "Missing required field: display_name");
-                    return true;
-                }
-                if (!body.command || typeof body.command !== "string") {
-                    sendError(res, 400, "Missing required field: command");
-                    return true;
-                }
-                const updated = runtime.registerCustomAgent({
-                    name: body.name,
-                    display_name: body.display_name,
-                    command: body.command,
-                });
+                const body = CustomAgentRegisterRequestSchema.parse(await readJsonBody(req));
+                const updated = runtime.registerCustomAgent(body);
                 sendJson(res, 201, updated);
             }
             catch (error) {
@@ -90,19 +70,7 @@ export async function tryHandleAgents(req, res, runtime, path, method) {
         }
         if (method === "PATCH") {
             try {
-                const body = (await readJsonBody(req));
-                if (!body || typeof body !== "object") {
-                    sendError(res, 400, "Request body must be a JSON object.");
-                    return true;
-                }
-                const patch = {};
-                for (const [role, value] of Object.entries(body)) {
-                    if (typeof value !== "string") {
-                        sendError(res, 400, `Role-map values must be strings (or "" to clear). Got ${typeof value} for role "${role}".`);
-                        return true;
-                    }
-                    patch[role] = value;
-                }
+                const patch = AgentRoleMapPatchSchema.parse(await readJsonBody(req));
                 const updated = runtime.patchAgentsRoleMap(patch);
                 sendJson(res, 200, updated);
             }
@@ -117,7 +85,9 @@ export async function tryHandleAgents(req, res, runtime, path, method) {
     // effort) for built-ins or custom agents alike.
     const agentMatch = path.match(/^\/v1\/agents\/([^/]+)$/);
     if (agentMatch?.[1] && method === "DELETE") {
-        const name = decodeURIComponent(agentMatch[1]);
+        const name = decodeOr400(res, agentMatch[1], "Agent name");
+        if (name === null)
+            return true;
         try {
             const updated = runtime.unregisterCustomAgent(name);
             sendJson(res, 200, updated);
@@ -130,61 +100,25 @@ export async function tryHandleAgents(req, res, runtime, path, method) {
         return true;
     }
     if (agentMatch?.[1] && method === "PATCH") {
-        const name = decodeURIComponent(agentMatch[1]);
+        const name = decodeOr400(res, agentMatch[1], "Agent name");
+        if (name === null)
+            return true;
         try {
-            const body = (await readJsonBody(req));
-            if (!body || typeof body !== "object") {
-                sendError(res, 400, "Request body must be a JSON object.");
-                return true;
-            }
+            const body = AgentPrefsPatchSchema.parse(await readJsonBody(req));
+            // Normalize the validated patch into the stored prefs shape, preserving
+            // the prior wire tolerance: an empty env_vars map is omitted, and a `""`
+            // or `null` model/effort clears that pref.
             const prefs = {};
             if ("env_vars" in body) {
                 const value = body.env_vars;
-                if (value === null || value === undefined) {
-                    // explicit clear — no env_vars in prefs
-                }
-                else if (typeof value === "object" && !Array.isArray(value)) {
-                    const entries = {};
-                    for (const [k, v] of Object.entries(value)) {
-                        if (typeof v !== "string") {
-                            sendError(res, 400, `env_vars values must be strings. Got ${typeof v} for "${k}".`);
-                            return true;
-                        }
-                        entries[k] = v;
-                    }
-                    if (Object.keys(entries).length > 0)
-                        prefs.env_vars = entries;
-                }
-                else {
-                    sendError(res, 400, "env_vars must be an object of string→string entries.");
-                    return true;
-                }
+                if (value && Object.keys(value).length > 0)
+                    prefs.env_vars = value;
             }
             if ("model" in body) {
-                const value = body.model;
-                if (value === null || value === "" || value === undefined) {
-                    prefs.model = null;
-                }
-                else if (typeof value === "string") {
-                    prefs.model = value;
-                }
-                else {
-                    sendError(res, 400, "model must be a string or null.");
-                    return true;
-                }
+                prefs.model = body.model === "" ? null : body.model ?? null;
             }
             if ("effort" in body) {
-                const value = body.effort;
-                if (value === null || value === "" || value === undefined) {
-                    prefs.effort = null;
-                }
-                else if (typeof value === "string") {
-                    prefs.effort = value;
-                }
-                else {
-                    sendError(res, 400, "effort must be a string or null.");
-                    return true;
-                }
+                prefs.effort = body.effort === "" ? null : body.effort ?? null;
             }
             const updated = runtime.setAgentPrefs(name, prefs);
             sendJson(res, 200, updated);

package/dist/packages/runtime/service/server-routes-build-plans.js

@@ -1,6 +1,6 @@
 import { BuildPlanSaveRequestSchema } from "../schemas/index.js";
 import { LOCAL_SERVICE_ROUTES } from "./routes.js";
-import { readJsonBody, sendError, sendJson, } from "./server-helpers.js";
+import { decodeOr400, readJsonBody, sendError, sendJson, } from "./server-helpers.js";
 import { isTraversalRelativePath, safeApiFilePath, sendApiFile, } from "./server-api-files.js";
 import { findInstanceBuildPlan, listInstanceBuildPlanRuns, listInstanceBuildPlans, resolveInstanceBuildPlanPackageRoot, } from "./server-instance-helpers.js";
 import { installUserBuildPlan } from "../../build-plans/package/user-build-plans.js";
@@ -30,7 +30,10 @@ export async function tryHandleBuildPlans(req, res, runtime, path, method) {
     }
     const buildPlanMatch = path.match(/^\/v1\/build-plans\/([^/]+)$/);
     if (method === "GET" && buildPlanMatch?.[1]) {
-        const buildPlanResource = findInstanceBuildPlan(runtime, decodeURIComponent(buildPlanMatch[1]));
+        const buildPlanId = decodeOr400(res, buildPlanMatch[1], "Build Plan id");
+        if (buildPlanId === null)
+            return true;
+        const buildPlanResource = findInstanceBuildPlan(runtime, buildPlanId);
         if (!buildPlanResource)
             sendError(res, 404, "Build Plan not found.");
         else
@@ -39,7 +42,10 @@ export async function tryHandleBuildPlans(req, res, runtime, path, method) {
     }
     const buildPlanRunsMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/runs$/);
     if (method === "GET" && buildPlanRunsMatch?.[1]) {
-        const runs = listInstanceBuildPlanRuns(runtime, decodeURIComponent(buildPlanRunsMatch[1]));
+        const buildPlanId = decodeOr400(res, buildPlanRunsMatch[1], "Build Plan id");
+        if (buildPlanId === null)
+            return true;
+        const runs = listInstanceBuildPlanRuns(runtime, buildPlanId);
         sendJson(res, 200, { runs });
         return true;
     }
@@ -51,15 +57,12 @@ export async function tryHandleBuildPlans(req, res, runtime, path, method) {
     // the resolved root.
     const buildPlanFilesMatch = path.match(/^\/v1\/build-plans\/([^/]+)\/files\/(.+)$/);
     if (method === "GET" && buildPlanFilesMatch?.[1] && buildPlanFilesMatch[2]) {
-        const buildPlanId = decodeURIComponent(buildPlanFilesMatch[1]);
-        let relPath;
-        try {
-            relPath = decodeURIComponent(buildPlanFilesMatch[2]);
-        }
-        catch {
-            sendError(res, 400, "File path is not valid URI-encoded UTF-8.");
+        const buildPlanId = decodeOr400(res, buildPlanFilesMatch[1], "Build Plan id");
+        if (buildPlanId === null)
+            return true;
+        const relPath = decodeOr400(res, buildPlanFilesMatch[2], "File path");
+        if (relPath === null)
             return true;
-        }
         if (isTraversalRelativePath(relPath)) {
             sendError(res, 400, "File path escapes Build Plan root.");
             return true;