@interf/compiler 0.22.2 → 0.50.0

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

@@ -0,0 +1,375 @@
+import { z } from "zod";
+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 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",
+    required: true,
+    description: "Project id.",
+    schema: ProjectIdSchema,
+};
+const RunIdParameter = {
+    name: "run_id",
+    in: "path",
+    required: true,
+    description: "Run id.",
+    schema: z.string().min(1),
+};
+const ContextGraphFilePathParameter = {
+    name: "path",
+    in: "query",
+    required: true,
+    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",
+    required: true,
+    description: "Relative file path inside the Build run's Context Graph output.",
+    schema: z.string().min(1),
+};
+export const SERVICE_OPERATIONS = [
+    {
+        id: "getHealth",
+        method: "GET",
+        path: "/health",
+        tags: ["Instance"],
+        summary: "Check local service health",
+        description: "Small tokenless liveness probe for local clients.",
+        visibility: "public",
+        response_schema: LocalServiceHealthSchema,
+        success_status: 200,
+    },
+    {
+        id: "getInstance",
+        method: "GET",
+        path: "/v1/instance",
+        tags: ["Instance"],
+        summary: "Get instance metadata",
+        description: "Return local service metadata without Project or Source contents.",
+        visibility: "public",
+        response_schema: InstanceResourceSchema,
+        success_status: 200,
+    },
+    {
+        id: "getOpenApi",
+        method: "GET",
+        path: "/v1/openapi.json",
+        tags: ["Instance"],
+        summary: "Get OpenAPI contract",
+        description: "Return the generated OpenAPI document for the local service API.",
+        visibility: "public",
+        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 and one agent task intent. Project ids may be generated by clients.",
+        visibility: "app",
+        workflow_step: 1,
+        request_schema: ProjectCreateRequestSchema,
+        response_schema: ProjectWireShapeSchema,
+        success_status: 201,
+    },
+    {
+        id: "getProject",
+        method: "GET",
+        path: "/v1/projects/{project_id}",
+        tags: ["Projects"],
+        summary: "Get Project",
+        description: "Read one Project to confirm its Source binding, selected Build Plan, readiness, and latest Context Graph.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: ProjectResourceSchema,
+        success_status: 200,
+    },
+    {
+        id: "prepareBuildPlan",
+        method: "POST",
+        path: "/v1/projects/{project_id}/build-plan-drafts",
+        tags: ["Build Plans"],
+        summary: "Prepare Build Plan",
+        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: ProjectBuildPlanAuthoringCreateRequestSchema,
+        response_schema: LocalJobRunResourceSchema,
+        success_status: 202,
+    },
+    {
+        id: "runBuild",
+        method: "POST",
+        path: "/v1/projects/{project_id}/build-runs",
+        tags: ["Build Runs"],
+        summary: "Run Build",
+        description: "Run the selected Build Plan and create an isolated Context Graph folder. Use only after Build Plan approval or explicit autonomy.",
+        visibility: "app",
+        workflow_step: 3,
+        parameters: [ProjectIdParameter],
+        request_schema: ProjectBuildRunCreateRequestSchema.default({}),
+        response_schema: BuildRunResourceSchema,
+        success_status: 201,
+    },
+    {
+        id: "getRunStatus",
+        method: "GET",
+        path: "/v1/runs/{run_id}/status",
+        tags: ["Runs"],
+        summary: "Get Run status",
+        description: "Read compact Run observability for polling. Detailed logs and artifacts are separate resources.",
+        visibility: "app",
+        parameters: [RunIdParameter],
+        response_schema: RunStatusResourceSchema,
+        success_status: 200,
+    },
+    {
+        id: "getRunArtifacts",
+        method: "GET",
+        path: "/v1/runs/{run_id}/artifacts",
+        tags: ["Runs"],
+        summary: "Get Run artifacts",
+        description: "Read the bounded artifact manifest for a finished Build run. Use only when the compact status says the Run is terminal.",
+        visibility: "app",
+        parameters: [RunIdParameter],
+        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",
+        path: "/v1/runs/{run_id}/files",
+        tags: ["Runs"],
+        summary: "Read Run file",
+        description: "Read a prompt log, status log, event stream, stage contract, or evidence file from the exact Build run output. Use this instead of latest Context Graph file reads when debugging historical runs.",
+        visibility: "app",
+        parameters: [RunIdParameter, RunFilePathParameter],
+        response_schema: z.string(),
+        response_content_type: "text/plain",
+        success_status: 200,
+    },
+    {
+        id: "getLatestContextGraph",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph",
+        tags: ["Context Graphs"],
+        summary: "Get latest Context Graph",
+        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",
+        path: "/v1/projects/{project_id}/source-files",
+        tags: ["Source"],
+        summary: "List Source Manifest projection",
+        description: "Return the latest Source Manifest projected as source file rows for compatibility clients. Use source-manifest as the canonical run authority.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: SourceFileListResponseSchema,
+        success_status: 200,
+    },
+    {
+        id: "getSourceManifest",
+        method: "GET",
+        path: "/v1/projects/{project_id}/source-manifest",
+        tags: ["Source"],
+        summary: "Get Source Manifest",
+        description: "Return the evidence-backed Source Manifest recorded for the latest Context Graph.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        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 home.md; use knowledge/ for task-specific notes and summaries/ for source-backed coverage.",
+        visibility: "app",
+        parameters: [ProjectIdParameter, ContextGraphFilePathParameter],
+        response_schema: z.string(),
+        response_content_type: "text/plain",
+        success_status: 200,
+    },
+    {
+        id: "getContextGraphTraces",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/traces",
+        tags: ["Context Graphs"],
+        summary: "Get Context Graph traces",
+        description: "Read source-backed trace rollups for exact values and provenance checks.",
+        visibility: "app",
+        parameters: [ProjectIdParameter],
+        response_schema: TracesSchema,
+        success_status: 200,
+    },
+    {
+        id: "getBuildEvidence",
+        method: "GET",
+        path: "/v1/projects/{project_id}/context-graph/evidence",
+        tags: ["Context Graphs"],
+        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,
+        success_status: 200,
+    },
+];
+export const APP_PROFILE_OPERATION_IDS = SERVICE_OPERATIONS
+    .filter((operation) => operation.visibility === "app")
+    .map((operation) => operation.id);
+export function serviceOperationById(id) {
+    return SERVICE_OPERATIONS.find((operation) => operation.id === id);
+}
+export { EmptyObjectSchema };

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

@@ -0,0 +1,114 @@
+export declare const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
+export declare const LOCAL_SERVICE_DEFAULT_PORT = 4873;
+export declare const LOCAL_SERVICE_ROUTES: {
+    readonly root: "/";
+    readonly api: "/v1";
+    readonly health: "/health";
+    readonly instance: "/v1/instance";
+    readonly openapi: "/v1/openapi.json";
+    readonly projects: "/v1/projects";
+    readonly buildPlans: "/v1/build-plans";
+    readonly runs: "/v1/runs";
+    /** Server-Sent Events change stream — pushes refresh signals to clients. */
+    readonly events: "/v1/events";
+    readonly actionProposals: "/v1/action-proposals";
+    /** App-backed MCP setup for MCP-capable agent hosts. */
+    readonly mcp: "/v1/mcp";
+    /** Single-active-agent route backed by the role-map's `general` row. */
+    readonly executor: "/v1/executor";
+    /**
+     * connected-agents primitive — registry, role-map, role list.
+     * `agents/{name}` and `agents/role-map` are sub-resources handled
+     * by string match in `server.ts`.
+     */
+    readonly agents: "/v1/agents";
+    /**
+     * Auth surface — current user identity, login/logout (cloud only),
+     * subscription state.
+     */
+    readonly auth: "/v1/auth";
+    /** Current account / session — used by the local service to check `runtime.currentAccount`. */
+    readonly me: "/v1/me";
+    readonly openPath: "/v1/open-path";
+};
+/** Project-scoped sub-resources (relative to /v1/projects/<id>/). */
+export declare const PROJECT_SUBRESOURCES: {
+    /** Build-run collection — POST creates a new Build run for this Project. */
+    readonly buildRuns: "build-runs";
+    readonly verifyRuns: "verify-runs";
+    readonly buildPlanDraftRuns: "build-plan-drafts";
+    readonly legacyBuildPlanDraftRuns: "build-plan-draft-runs";
+    readonly buildPlanImprovementRuns: "build-plan-improvement-runs";
+    readonly benchmarkQuestionDrafts: "benchmark-question-drafts";
+    readonly benchmarkChecks: "benchmark-checks";
+    readonly buildPlanChanges: "build-plan-changes";
+    readonly reset: "reset";
+    readonly runs: "runs";
+    readonly readiness: "readiness";
+    readonly graphs: "graphs";
+    readonly sourceFiles: "source-files";
+    /** Latest evidence-backed Source Manifest for this Project. */
+    readonly sourceManifest: "source-manifest";
+    /**
+     * Latest Context Graph for this Project — what the agent reads. Returns the
+     * current Context Graph wire shape plus a locator pointing at the generated
+     * folder or API-served resource.
+     */
+    readonly contextGraph: "context-graph";
+    /** First-class traces surface — per-claim provenance back to source. */
+    readonly traces: "context-graph/traces";
+    /** 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-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";
+};
+/** Build Plan activity sub-resources (relative to /v1/build-plans/<id>/). */
+export declare const BUILD_PLAN_SUBRESOURCES: {
+    readonly runs: "runs";
+    /**
+     * Read a Build Plan definition file (read-only, path-guarded inside
+     * the Build Plan root). Used by the locator pattern's `api-served` kind:
+     *   GET /v1/build-plans/<id>/files/<relpath>
+     */
+    readonly files: "files";
+};
+/** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
+export declare const RUN_SUBRESOURCES: {
+    readonly status: "status";
+    readonly events: "events";
+    readonly cancel: "cancel";
+    readonly artifacts: "artifacts";
+    readonly files: "files";
+};
+export declare function buildLocalServiceUrl(options?: {
+    host?: string;
+    port?: number;
+}): string;
+/** Path builder: /v1/projects/<id>. */
+export declare function projectResourcePath(projectId: string): string;
+/** Path builder: /v1/projects/<id>/<subresource>. */
+export declare function projectSubresourcePath(projectId: string, sub: keyof typeof PROJECT_SUBRESOURCES): string;
+/** Path builder: /v1/runs/<run-id>. */
+export declare function runResourcePath(runId: string): string;
+/** Path builder: /v1/runs/<run-id>/<subresource>. */
+export declare function runSubresourcePath(runId: string, sub: keyof typeof RUN_SUBRESOURCES): string;
+/** Path builder: /v1/build-plans/<id>. */
+export declare function buildPlanResourcePath(buildPlanId: string): string;
+/** Path builder: /v1/build-plans/<id>/<subresource>. */
+export declare function buildPlanSubresourcePath(buildPlanId: string, sub: keyof typeof BUILD_PLAN_SUBRESOURCES): string;

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

@@ -0,0 +1,128 @@
+export const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
+export const LOCAL_SERVICE_DEFAULT_PORT = 4873;
+export const LOCAL_SERVICE_ROUTES = {
+    root: "/",
+    api: "/v1",
+    health: "/health",
+    // surface — project-keyed.
+    instance: "/v1/instance",
+    openapi: "/v1/openapi.json",
+    projects: "/v1/projects",
+    buildPlans: "/v1/build-plans",
+    runs: "/v1/runs",
+    /** Server-Sent Events change stream — pushes refresh signals to clients. */
+    events: "/v1/events",
+    actionProposals: "/v1/action-proposals",
+    /** App-backed MCP setup for MCP-capable agent hosts. */
+    mcp: "/v1/mcp",
+    /** Single-active-agent route backed by the role-map's `general` row. */
+    executor: "/v1/executor",
+    /**
+     * connected-agents primitive — registry, role-map, role list.
+     * `agents/{name}` and `agents/role-map` are sub-resources handled
+     * by string match in `server.ts`.
+     */
+    agents: "/v1/agents",
+    /**
+     * Auth surface — current user identity, login/logout (cloud only),
+     * subscription state.
+     */
+    auth: "/v1/auth",
+    /** Current account / session — used by the local service to check `runtime.currentAccount`. */
+    me: "/v1/me",
+    openPath: "/v1/open-path",
+};
+/** Project-scoped sub-resources (relative to /v1/projects/<id>/). */
+export const PROJECT_SUBRESOURCES = {
+    /** Build-run collection — POST creates a new Build run for this Project. */
+    buildRuns: "build-runs",
+    verifyRuns: "verify-runs",
+    buildPlanDraftRuns: "build-plan-drafts",
+    legacyBuildPlanDraftRuns: "build-plan-draft-runs",
+    buildPlanImprovementRuns: "build-plan-improvement-runs",
+    benchmarkQuestionDrafts: "benchmark-question-drafts",
+    benchmarkChecks: "benchmark-checks",
+    buildPlanChanges: "build-plan-changes",
+    reset: "reset",
+    runs: "runs",
+    readiness: "readiness",
+    graphs: "graphs",
+    sourceFiles: "source-files",
+    /** Latest evidence-backed Source Manifest for this Project. */
+    sourceManifest: "source-manifest",
+    /**
+     * Latest Context Graph for this Project — what the agent reads. Returns the
+     * current Context Graph wire shape plus a locator pointing at the generated
+     * folder or API-served resource.
+     */
+    contextGraph: "context-graph",
+    /** First-class traces surface — per-claim provenance back to source. */
+    traces: "context-graph/traces",
+    /** 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-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",
+};
+/** Build Plan activity sub-resources (relative to /v1/build-plans/<id>/). */
+export const BUILD_PLAN_SUBRESOURCES = {
+    runs: "runs",
+    /**
+     * Read a Build Plan definition file (read-only, path-guarded inside
+     * the Build Plan root). Used by the locator pattern's `api-served` kind:
+     *   GET /v1/build-plans/<id>/files/<relpath>
+     */
+    files: "files",
+};
+/** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
+export const RUN_SUBRESOURCES = {
+    status: "status",
+    events: "events",
+    cancel: "cancel",
+    artifacts: "artifacts",
+    files: "files",
+};
+export function buildLocalServiceUrl(options = {}) {
+    const host = options.host ?? LOCAL_SERVICE_DEFAULT_HOST;
+    const port = options.port ?? LOCAL_SERVICE_DEFAULT_PORT;
+    return `http://${host}:${port}`;
+}
+/** Path builder: /v1/projects/<id>. */
+export function projectResourcePath(projectId) {
+    return `${LOCAL_SERVICE_ROUTES.projects}/${encodeURIComponent(projectId)}`;
+}
+/** Path builder: /v1/projects/<id>/<subresource>. */
+export function projectSubresourcePath(projectId, sub) {
+    return `${projectResourcePath(projectId)}/${PROJECT_SUBRESOURCES[sub]}`;
+}
+/** Path builder: /v1/runs/<run-id>. */
+export function runResourcePath(runId) {
+    return `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(runId)}`;
+}
+/** Path builder: /v1/runs/<run-id>/<subresource>. */
+export function runSubresourcePath(runId, sub) {
+    return `${runResourcePath(runId)}/${RUN_SUBRESOURCES[sub]}`;
+}
+/** Path builder: /v1/build-plans/<id>. */
+export function buildPlanResourcePath(buildPlanId) {
+    return `${LOCAL_SERVICE_ROUTES.buildPlans}/${encodeURIComponent(buildPlanId)}`;
+}
+/** Path builder: /v1/build-plans/<id>/<subresource>. */
+export function buildPlanSubresourcePath(buildPlanId, sub) {
+    return `${buildPlanResourcePath(buildPlanId)}/${BUILD_PLAN_SUBRESOURCES[sub]}`;
+}

package/dist/packages/runtime/service/server-api-files.d.ts

@@ -0,0 +1,10 @@
+import type { ServerResponse } from "node:http";
+export declare function packageRoot(): string;
+export declare function safeApiFilePath(root: string, relativePath: string): string | null;
+export declare function sendApiFile(res: ServerResponse, filePath: string): boolean;
+/**
+ * Reject any path that contains `..` or absolute segments. These helpers are
+ * only for authenticated `/v1/.../files/...` API resources, not for serving
+ * the Desktop renderer.
+ */
+export declare function isTraversalRelativePath(relPath: string): boolean;