@interf/compiler 0.33.0 → 0.50.0

package/dist/cli/commands/mcp.js

@@ -25,12 +25,15 @@
  *   runtime_status      shell out to `interf runtime status`
  * Desktop app profile tools:
  *   create_project, prepare_build_plan, run_build
- *   get_instance_status, get_project, get_run_status, get_run_artifacts
- *   get_latest_context_graph, read_context_graph_file
- *   get_context_graph_traces, get_build_evidence
+ *   get_instance_status, get_project, get_run_status, get_run_events, get_run_artifacts
+ *   get_latest_context_graph, get_context_graph_entrypoint, read_context_graph_file
+ *   get_context_graph_traces, get_context_graph_sessions, get_context_graph_session,
+ *   get_build_evidence
  *
  * Headless developer profile additionally exposes runtime lifecycle,
- * inventory, Build Plan library, benchmark, cancel, and admin tools.
+ * inventory, Build Plan library, benchmark, cancel, admin, full run event
+ * log (runs_events), and execution-session reads (context_graph_sessions,
+ * context_graph_session).
  */
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
@@ -39,26 +42,51 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/runtime/connection-config.js";
 import { readServiceRegistry, } from "../../packages/runtime/service/service-registry.js";
+import { callJson, } from "../lib/http-client.js";
+import { slugify } from "../../packages/contracts/utils/naming.js";
 import { LOCAL_SERVICE_ROUTES, buildPlanResourcePath, buildPlanSubresourcePath, projectResourcePath, projectSubresourcePath, runResourcePath, runSubresourcePath, } from "../../packages/runtime/service/routes.js";
 import { BuildPlanAuthoringArtifactRequirementSchema, BuildPlanContextCheckDraftSchema, RequestedArtifactSchema, } from "../../packages/runtime/schemas/index.js";
+import { ArtifactIdSchema, BuildPlanIdSchema, ProjectIdSchema, } from "../../packages/contracts/lib/schema.js";
 import { SourceContextSchema, } from "../../packages/projects/lib/schema.js";
+// ───────────────────────────────────────────────────────────────────────────
+// MCP id input schemas. These reuse the contract ID schemas so the MCP surface
+// accepts exactly the ids the runtime accepts — instead of a looser inline
+// `z.string().min(1)` that would let MCP pass ids the runtime then rejects.
+// `project_id`/`build_plan_id`/`artifact_id` carry the contract regex +
+// reserved-id rules; `run_id`s are opaque underscore-bearing tokens the runtime
+// mints (e.g. `build_<base36>_<base36>`), so there is no stricter contract
+// schema for them — they stay `z.string().min(1)`, defined once here.
+// ───────────────────────────────────────────────────────────────────────────
+const McpProjectIdSchema = ProjectIdSchema.describe("Project id (kebab-case).");
+const McpBuildPlanIdSchema = BuildPlanIdSchema.describe("Build Plan id (kebab-case).");
+const McpArtifactIdSchema = ArtifactIdSchema.describe("Requested output id (kebab-case).");
+const McpRunIdSchema = z.string().min(1).describe("Run id.");
 const INTERF_MCP_INSTRUCTIONS = [
-    "Interf prepares data for agents. It is not a search engine and not a general RAG index.",
-    "Interf MCP is how this host talks to Interf. Agents listed inside Interf are executors that run Build Plan stages. Do not treat MCP setup as executor setup.",
-    "App MCP exposes three core workflow tools: create_project, prepare_build_plan, and run_build. Other tools are read-only inspection helpers.",
-    "Default workflow for a user question over files: create a fresh Project for the current Source, propose Context Checks and requested Artifacts, prepare the Build Plan after the user approves those checks and Artifacts, stop for Build Plan approval, run_build only after that approval, then answer from the prepared Context Graph and its source-backed traces.",
-    "Source scope default: if Interf Desktop, the MCP host, or the user context already provides a Source locator or file set, use that whole Source. Do not ask the user to choose individual files or a subset unless they explicitly ask to narrow scope.",
-    "Do not answer by browsing existing Projects as if they were a corpus. In the Desktop app profile, always create a fresh Project for the current Source unless the user explicitly names an existing Project id.",
-    "Use existing Projects or Context Graphs only when the user explicitly selected or named them and they bind the same Source and task.",
-    "If no usable Source locator is available, ask for one Source locator. In the local Desktop path this may be a folder path. Do not present a file-selection menu or ask which files inside the Source to use.",
-    "Project creation is allowed when the user asks Interf to use a Source. Project ids are generated internally. Do not ask for existing Project ids. Approval gates are for Build Plan preparation and Build execution.",
-    "Before building, show the user the Context Checks, requested Artifacts, and drafted Build Plan in chat. Wait for approval unless the user has explicitly granted end-to-end autonomy.",
-    "No automatic retries: if prepare_build_plan, run_build, or a polled Run reaches failed/cancelled, report the failure and ask the user before starting another draft or Build run.",
-    "After a Build succeeds, read the task handoff under artifacts/ first. Treat home.md as a graph index, summaries/ as source coverage proof, and knowledge/ as navigation/drilldown.",
-    "A Context Graph is a knowledge map over the Source, not the answer source. Use it to understand what exists and where evidence lives; follow source references and traces when exact values, chart reads, tables, or provenance matter.",
-    "If a Context Graph artifact is too coarse or missing the needed evidence, improve the Build Plan and rebuild instead of giving a weak answer.",
+    "WHAT INTERF IS",
+    "Interf prepares data for agents. It builds a task-specific Context Graph from a Source (the user's files) — claim nodes, entities, comparison nodes, timelines, coverage indexes — that any agent can read to answer. Source-of-truth stays in the user's files. Interf does NOT answer the user's question; it prepares the structured graph the agent reasons over.",
+    "",
+    "WHAT YOU PASS, WHAT YOU GET",
+    "You pass: the user's intent (the task the graph is for) and optional graph areas you want prepared. You get: a Context Graph the agent reads — home.md as entrypoint, knowledge/ for drilldown, summaries/ as source coverage, source-backed traces for exact values.",
+    "",
+    "THE WORKFLOW",
+    "1. create_project — bind the Source + intent.",
+    "2. prepare_build_plan — name the graph areas to prepare (e.g. 'NY rent forecast claim nodes', 'cost comparison nodes', 'decision timeline'). Show the draft to the user. Stop for approval unless they granted end-to-end autonomy.",
+    "3. run_build — only after approval. Wait for terminal state; do not auto-retry.",
+    "4. get_latest_context_graph — read primary_metrics + home.md, follow traces for exact values, then answer.",
+    "",
+    "REQUESTED OUTPUTS ARE GRAPH AREAS, NOT ANSWERS",
+    "Each requested output is a region of the Context Graph the next agent will traverse (claim nodes, comparison nodes, a timeline, a coverage index). Never name an output 'the answer markdown', 'final report', 'forecast summary', or 'recommended decision' — those replace agent thinking. The agent still reasons; Interf only prepares.",
+    "",
+    "SOURCING",
+    "If the host/user already provides a Source locator, use the whole Source. Don't ask the user to pick files. Don't browse existing Projects like a corpus — create a fresh Project per task unless the user explicitly names one. Project ids are auto-generated.",
+    "",
+    "EXECUTORS VS MCP",
+    "Interf MCP is how this host talks to Interf. The agents listed inside Interf are EXECUTORS that run Build Plan stages; that is a separate setup from this MCP connection.",
+    "",
+    "FAILURE HANDLING",
+    "If any Run fails with 'executor preflight' in the error, the active execution agent CLI is broken on this machine. Tell the user to switch with `interf agents use claude-code` (or another available executor). Do not retry, do not create a new Project. For any other failure, report it and ask before starting another draft or Build.",
 ].join("\n");
-const McpRequestedArtifactSchema = RequestedArtifactSchema.describe("Requested Artifact the user approved. Use a short title, optional id, description/purpose, and plain-English checks.");
+const McpRequestedArtifactSchema = RequestedArtifactSchema.describe("A graph area Interf should prepare in the Context Graph — claim nodes, comparison nodes, a timeline, a coverage index. NOT the user's final answer and NOT a finished report. Each requested output is structured prepared data the NEXT agent will read and reason over. Good titles: 'NY rent forecast claims', 'Bristol vs London cost comparison nodes', 'Q3 decision-timeline signals'. Bad titles: 'NY rent growth answer', 'Final report', 'Forecast summary' — those replace agent thinking instead of preparing data for it. Source-of-truth stays in the user's files; Interf builds the task-specific Context Graph the agent reads.");
 function normalizeRequestedArtifacts(artifacts) {
     if (!artifacts)
         return undefined;
@@ -96,16 +124,12 @@ function encodeRelativePath(value) {
 function contextGraphFilePath(projectId, filePath) {
     return `${projectSubresourcePath(projectId, "contextGraphFile")}?path=${encodeURIComponent(filePath)}`;
 }
-function slugifyMcpId(input) {
-    return input
-        .toLowerCase()
-        .trim()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 48);
-}
-function generatedMcpId(prefix) {
-    const base = slugifyMcpId(prefix).slice(0, 18) || "item";
+// Exported for the slugify-equivalence regression test. The 18-char clamp keeps
+// the generated base well inside `slugify`'s own 80-char cap, so swapping the
+// former local `slugifyMcpId` (48-char cap) for the shared `slugify` is
+// behavior-preserving for every input.
+export function generatedMcpId(prefix) {
+    const base = slugify(prefix).slice(0, 18) || "item";
     const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
     return `${base}-${suffix}`;
 }
@@ -120,6 +144,15 @@ function packageVersionFromManifest() {
         return "0.0.0";
     }
 }
+// MCP intentionally does NOT use http-client's `resolveConnection`. That helper
+// is the CLI contract: it `process.exit(1)`s when no connection is found, which
+// is correct for a one-shot CLI command but fatal for a long-lived MCP server
+// that must instead return a structured `CONNECT_OR_ERROR_HINT` tool error and
+// stay up. MCP also adds a `--url`-override token discovery step (services.json
+// registry, then the active connection) that the plain CLI override path does
+// not perform. Until http-client exports a shared null-returning variant, this
+// resolution stays here; the underlying `readActiveConnection` precedence is
+// still single-sourced in connection-config.
 function resolveConnectionOrNull(args) {
     const urlOverride = args.url?.trim();
     const currentLocalToken = urlOverride
@@ -174,25 +207,12 @@ function runInterfCli(args) {
         });
     });
 }
-async function callApi(conn, path, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (conn.token)
-        headers.set("authorization", `Bearer ${conn.token}`);
-    if (init.body && !headers.has("content-type")) {
-        headers.set("content-type", "application/json");
-    }
-    const response = await fetch(`${conn.url}${path}`, { ...init, headers });
-    const raw = await response.text();
-    let body = null;
-    if (raw.length > 0) {
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            body = raw;
-        }
-    }
-    return { status: response.status, body, raw };
+// MCP issues every API call through the shared CLI `callJson` (header-setting +
+// JSON parsing live solely in http-client). `callJson` yields `body: null` on a
+// non-JSON body (vs the former local `callApi`'s `body = raw`); every read site
+// goes through `body ?? raw` or an `isRecord(body)` guard, so behavior holds.
+function mcpApi(conn, path, init = {}) {
+    return callJson(`${conn.url}${path}`, conn.token, init);
 }
 function toolResultJson(payload) {
     const text = typeof payload === "string"
@@ -224,7 +244,7 @@ async function callAndReturn(args, path, init = {}) {
     const conn = resolveConnectionOrNull(args);
     if (!conn)
         return toolErrorJson(CONNECT_OR_ERROR_HINT);
-    const response = await callApi(conn, path, init);
+    const response = await mcpApi(conn, path, init);
     if (response.status >= 200 && response.status < 300) {
         return toolResultJson(response.body ?? response.raw);
     }
@@ -234,7 +254,7 @@ async function callAndProject(args, path, project, init = {}) {
     const conn = resolveConnectionOrNull(args);
     if (!conn)
         return toolErrorJson(CONNECT_OR_ERROR_HINT);
-    const response = await callApi(conn, path, init);
+    const response = await mcpApi(conn, path, init);
     if (response.status >= 200 && response.status < 300) {
         return toolResultJson(project(response.body, response.raw));
     }
@@ -387,7 +407,7 @@ function compactRunEvents(payload, options) {
     };
 }
 async function currentSourcePathForApp(conn) {
-    const response = await callApi(conn, LOCAL_SERVICE_ROUTES.health);
+    const response = await mcpApi(conn, LOCAL_SERVICE_ROUTES.health);
     if (response.status >= 200 && response.status < 300 && isRecord(response.body)) {
         const sourcePath = readString(response.body, "source_folder_path");
         if (sourcePath)
@@ -397,7 +417,7 @@ async function currentSourcePathForApp(conn) {
     return sourceCandidates.length === 1 ? sourceCandidates[0]?.source_path ?? null : null;
 }
 async function sourceCandidatesForApp(conn) {
-    const response = await callApi(conn, LOCAL_SERVICE_ROUTES.projects);
+    const response = await mcpApi(conn, LOCAL_SERVICE_ROUTES.projects);
     if (response.status < 200 || response.status >= 300 || !isRecord(response.body))
         return [];
     const bySource = new Map();
@@ -431,10 +451,12 @@ async function callAppCreateProject(args, request) {
         return toolErrorJson("No unambiguous current Source locator is exposed by Interf. If source_candidates contains a Source that clearly matches the user's task, call create_project again with that source_path. Otherwise ask for one Source locator. Do not ask for an existing Project id or ask the user to choose individual files.", { source_candidates: sourceCandidates });
     }
     const id = generatedMcpId("project");
-    const response = await callApi(conn, LOCAL_SERVICE_ROUTES.projects, {
+    const intent = request.intent.trim();
+    const response = await mcpApi(conn, LOCAL_SERVICE_ROUTES.projects, {
         method: "POST",
         body: JSON.stringify({
             id,
+            intent,
             source: { kind: "local-folder", locator: sourcePath },
         }),
     });
@@ -446,34 +468,35 @@ async function callAppCreateProject(args, request) {
 function registerAppProfileTools(server, connectionArgs) {
     server.registerTool("create_project", {
         title: "Create Project",
-        description: "Core step 1. Create a fresh Project for this task and the whole current Source. The Project id is generated internally; do not ask for or provide one.",
+        description: "Workflow step 1. Bind the current Source + the user's intent (the task the Context Graph is for). Project id is auto-generated.",
         inputSchema: {
-            source_path: z.string().min(1).optional().describe("Fallback Source locator. In the local Desktop path this is an absolute folder path. Use only when Interf does not expose a current Source; do not pass individual files or a subset selection."),
+            intent: z.string().min(1).describe("The task the Context Graph must support — e.g. 'compare NY effective vs blended rent growth for 2026'."),
+            source_path: z.string().min(1).optional().describe("Fallback Source locator (absolute folder path on local Desktop). Pass only when Interf does not expose a current Source."),
         },
     }, async (args) => callAppCreateProject(connectionArgs, args));
     server.registerTool("prepare_build_plan", {
         title: "Prepare Build Plan",
-        description: "Core step 2. Draft the approved Build Plan for the Project. Use after the user approves checks and requested Artifacts. Stop after this tool and ask for Build Plan approval before building. If it fails, report the failure; do not retry without explicit user approval.",
+        description: "Workflow step 2. Draft the Build Plan from the Project intent + requested graph areas. Stop after this tool and show the draft for user approval (see top-level instructions for failure handling).",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id from create_project."),
-            build_plan_id: z.string().min(1).optional().describe("Optional Build Plan id. Omit to auto-generate."),
+            project_id: McpProjectIdSchema.describe("Project id from create_project."),
+            build_plan_id: McpBuildPlanIdSchema.optional().describe("Optional Build Plan id. Omit to auto-generate."),
             label: z.string().min(1).optional().describe("Optional short human label."),
             hint: z.string().min(1).optional().describe("Optional one-line plan hint."),
-            intent: z.string().min(1).describe("Question/task the Context Graph must support."),
-            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Plain-English checks the user approved."),
-            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested Artifacts the user approved."),
+            intent: z.string().min(1).optional().describe("Question/task the Context Graph must support. Omit to use the Project intent."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Optional legacy plain-English checks. Prefer Project intent plus requested outputs and coverage expectations."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested outputs the user approved."),
             source_context: SourceContextSchema.nullable().optional(),
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildPlanDraftRuns"), {
         method: "POST",
         body: JSON.stringify((() => {
-            const intent = args.intent.trim();
+            const intent = args.intent?.trim();
             const buildPlanId = args.build_plan_id?.trim() || generatedMcpId("plan");
             return {
                 build_plan_id: buildPlanId,
                 label: args.label?.trim() || buildPlanId,
-                hint: args.hint?.trim() || intent,
-                intent,
+                hint: args.hint?.trim() || intent || `Build Plan for Project ${args.project_id}`,
+                ...(intent ? { intent } : {}),
                 ...(args.context_checks ? { checks: args.context_checks } : {}),
                 ...(args.requested_artifacts ? { requested_artifacts: normalizeRequestedArtifacts(args.requested_artifacts) } : {}),
                 ...(args.source_context !== undefined ? { source_context: args.source_context } : {}),
@@ -482,9 +505,9 @@ function registerAppProfileTools(server, connectionArgs) {
     }));
     server.registerTool("run_build", {
         title: "Run Build",
-        description: "Core step 3. Run the selected Build Plan and create the Context Graph. Never call immediately after prepare_build_plan; use only after explicit Build Plan approval or explicit end-to-end autonomy. If it fails, report the failure; do not retry without explicit user approval.",
+        description: "Workflow step 3. Run the approved Build Plan and build the Context Graph. Only call after explicit Build Plan approval or explicit end-to-end autonomy. See top-level instructions for failure handling.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id from create_project."),
+            project_id: McpProjectIdSchema.describe("Project id from create_project."),
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildRuns"), { method: "POST", body: "{}" }));
     server.registerTool("get_instance_status", {
@@ -496,8 +519,8 @@ function registerAppProfileTools(server, connectionArgs) {
         if (!conn)
             return toolErrorJson(CONNECT_OR_ERROR_HINT);
         const [health, instance, sourceCandidates] = await Promise.all([
-            callApi(conn, LOCAL_SERVICE_ROUTES.health),
-            callApi(conn, LOCAL_SERVICE_ROUTES.instance),
+            mcpApi(conn, LOCAL_SERVICE_ROUTES.health),
+            mcpApi(conn, LOCAL_SERVICE_ROUTES.instance),
             sourceCandidatesForApp(conn),
         ]);
         if (health.status < 200 || health.status >= 300) {
@@ -520,42 +543,56 @@ function registerAppProfileTools(server, connectionArgs) {
             agent_count: readNumber(instanceBody, "agent_count"),
             default_agent: readString(instanceBody, "default_agent"),
             source_candidates: sourceCandidates,
-            instruction: "For a new file question: use the whole current Source, create_project -> ask user to approve checks/Artifacts -> prepare_build_plan -> ask user to approve the Build Plan -> run_build. If source_path is null but source_candidates has a Source that clearly matches the user's task, pass that source_path to create_project. Do not ask which files inside the Source to use unless the user explicitly narrows scope.",
+            instruction: "For a new file question: use the whole current Source, create_project -> prepare_build_plan -> ask user to review/approve the Build Plan -> run_build -> get_latest_context_graph. If source_path is null but source_candidates has a Source that clearly matches the user's task, pass that source_path to create_project. Do not ask which files inside the Source to use unless the user explicitly narrows scope.",
         });
     });
     server.registerTool("get_project", {
         title: "Get Project",
         description: "Read-only helper. Confirm one Project's Source binding, selected Build Plan, readiness, and latest Context Graph.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.project_id)));
+    server.registerTool("get_project_readiness", {
+        title: "Get Project Readiness",
+        description: "Read-only helper. Return ready/not ready for the latest Context Graph against the Project intent.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "readiness")));
     server.registerTool("get_run_status", {
         title: "Get Run Status",
         description: "Read-only helper. Compact polling receipt for one Run. Use this for repeated status checks.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
     }, async (args) => callAndProject(connectionArgs, runSubresourcePath(args.run_id, "status"), compactRunStatus));
     server.registerTool("get_run_artifacts", {
-        title: "Get Run Artifacts",
+        title: "Get Run Outputs",
         description: "Read-only helper. Fetch a finished Run's artifact manifest only when status is terminal or when reviewing a completed Build Plan draft.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/artifacts`));
     server.registerTool("get_latest_context_graph", {
         title: "Get Latest Context Graph",
-        description: "Read-only helper. Show the latest Context Graph locator for a Project. This is a locator/status read, not the answer surface; read artifacts/ handoff files next.",
+        description: "Read-only helper. Show the latest Context Graph locator, GraphManifest, primary metrics, entrypoints, and readiness for a Project. Start from home.md next.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraph")));
+    server.registerTool("get_context_graph_entrypoint", {
+        title: "Get Graph Entrypoint",
+        description: "Read-only helper. Return the downstream agent entrypoint for the latest Context Graph. Start from home.md, then follow entrypoint links when useful.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphEntrypoint")));
     server.registerTool("read_context_graph_file", {
         title: "Read Context Graph File",
-        description: "Read one prepared Context Graph file by relative path. Start with artifacts/ task handoffs; use summaries/ for coverage and knowledge/ for drilldown.",
+        description: "Read one prepared Context Graph file by relative path. Start with home.md; use summaries/ for coverage and knowledge/ for drilldown.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
             path: z.string().min(1).describe("Relative path inside the Context Graph."),
         },
     }, async (args) => callAndReturn(connectionArgs, contextGraphFilePath(args.project_id, args.path)));
@@ -563,14 +600,36 @@ function registerAppProfileTools(server, connectionArgs) {
         title: "Get Context Graph Traces",
         description: "Read-only helper. Read source-backed traces for exact values and provenance.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "traces")));
+    server.registerTool("get_context_graph_sessions", {
+        title: "Get Context Graph Execution Sessions",
+        description: "Read-only helper. List the per-stage execution shell sessions for the latest Build run — executor + model, status, attempt, validation attempts, and replay readiness. Pull these to drive the next self-improvement iteration when a stage was weak or failed.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphSessions")));
+    server.registerTool("get_context_graph_session", {
+        title: "Get One Context Graph Execution Session",
+        description: "Read-only helper. Return one preserved execution shell session by stage_run_id — prompt, event/status log paths, runtime files, artifact mounts, validation attempts, and the terminal verdict. Use it to inspect or replay exactly what a stage attempt did.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            stage_run_id: z.string().min(1).describe("Stage execution session id (stage_run_id) from get_context_graph_sessions."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, `${projectSubresourcePath(args.project_id, "contextGraphSessions")}/${encodeURIComponent(args.stage_run_id)}`));
+    server.registerTool("get_run_events", {
+        title: "Get Run Events",
+        description: "Read-only helper. Read the durable event log for a Build run: stage start/pass/fail, files processed, artifacts written, evidence, checks, and readiness. Poll get_run_status for progress; read events to inspect or replay what happened.",
+        inputSchema: {
+            run_id: McpRunIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(args.run_id, "events")));
     server.registerTool("get_build_evidence", {
-        title: "Get Build Evidence",
-        description: "Read-only helper. Read checks, Artifact diagnostics, and readiness evidence.",
+        title: "Get Supplemental Build Diagnostics",
+        description: "Read-only helper. Read supplemental diagnostics. Prefer get_latest_context_graph for primary coverage metrics and readiness.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildEvidence")));
 }
@@ -651,11 +710,12 @@ function registerTools(server, connectionArgs) {
         description: "Create a Project for the user's current Source. In the Desktop app profile, this is normally "
             + "the first Interf action for a new user question over files.",
         inputSchema: {
-            id: z.string().min(1).describe("Project id (kebab-case)."),
+            id: McpProjectIdSchema,
+            intent: z.string().min(1).describe("Agent task this Project's Context Graph should support."),
             source_path: z.string().min(1).describe("Source path visible to the connected instance."),
             ...(!appProfile
                 ? {
-                    build_plan_id: z.string().min(1).optional().describe("Optional Build Plan id to select."),
+                    build_plan_id: McpBuildPlanIdSchema.optional().describe("Optional Build Plan id to select."),
                 }
                 : {}),
         },
@@ -663,6 +723,7 @@ function registerTools(server, connectionArgs) {
         method: "POST",
         body: JSON.stringify({
             id: args.id,
+            intent: args.intent,
             source: { kind: "local-folder", locator: args.source_path },
             ...(args.build_plan_id ? { build_plan_id: args.build_plan_id } : {}),
         }),
@@ -672,17 +733,24 @@ function registerTools(server, connectionArgs) {
         description: "Return one Project resource to confirm its Source binding, selected Build Plan, readiness, "
             + "and latest Context Graph before deciding whether it matches the current task.",
         inputSchema: {
-            id: z.string().min(1).describe("Project id."),
+            id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id)));
+    server.registerTool("project_readiness", {
+        title: "Read Project readiness",
+        description: "Return the ready/not ready status for this Project's latest Context Graph against the Project intent.",
+        inputSchema: {
+            id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "readiness")));
     if (!appProfile) {
         server.registerTool("project_select_build_plan", {
             title: "Select a Build Plan for a Project",
             description: "Developer/admin tool. Update the selected Build Plan on a Project. "
                 + "Build Plan draft/improve runs select their resulting Plan automatically.",
             inputSchema: {
-                id: z.string().min(1).describe("Project id."),
-                build_plan_id: z.string().min(1).describe("Build Plan id to use."),
+                id: McpProjectIdSchema,
+                build_plan_id: McpBuildPlanIdSchema.describe("Build Plan id to use."),
             },
         }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id), {
             method: "PATCH",
@@ -692,7 +760,7 @@ function registerTools(server, connectionArgs) {
             title: "Remove a Project",
             description: "Developer/admin tool. Delete a Project and its Context Graph.",
             inputSchema: {
-                id: z.string().min(1).describe("Project id."),
+                id: McpProjectIdSchema,
             },
         }, async (args) => callAndReturn(connectionArgs, projectResourcePath(args.id), {
             method: "DELETE",
@@ -702,10 +770,10 @@ function registerTools(server, connectionArgs) {
     server.registerTool("project_build", {
         title: "Build Context Graph",
         description: "Run the selected Build Plan for a Project and write a task-specific Context Graph. "
-            + "Use this only after the user has approved the checks/requested Artifacts and Build Plan, "
+            + "Use this only after the user has approved the coverage expectations, requested outputs, and Build Plan, "
             + "unless they explicitly granted autonomy. Returns immediately; poll with runs_status.",
         inputSchema: {
-            id: z.string().min(1).describe("Project id."),
+            id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "buildRuns"), { method: "POST", body: "{}" }));
     if (!appProfile) {
@@ -713,7 +781,7 @@ function registerTools(server, connectionArgs) {
             title: "Run benchmark/evaluation",
             description: "Developer/evaluation tool. Run the Project's Q&A / fact-check benchmark against the latest Context Graph.",
             inputSchema: {
-                id: z.string().min(1).describe("Project id."),
+                id: McpProjectIdSchema,
             },
         }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "verifyRuns"), {
             method: "POST",
@@ -725,23 +793,30 @@ function registerTools(server, connectionArgs) {
         description: "List the Source files bound to a Project to confirm coverage scope. "
             + "This is not an answer source by itself; prepare or inspect a Context Graph before answering.",
         inputSchema: {
-            id: z.string().min(1).describe("Project id."),
+            id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.id, "sourceFiles")));
     server.registerTool("context_graph_show", {
         title: "Show latest Context Graph",
         description: "Inspect the latest Context Graph locator/status for a Project. Reuse it only if it was built for the same Source "
-            + "and task-relevant checks/artifacts; otherwise improve or draft a Build Plan and rebuild. Read artifacts/ handoffs before answering.",
+            + "and task intent; otherwise improve or draft a Build Plan and rebuild. Read home.md before answering.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraph")));
+    server.registerTool("context_graph_entrypoint", {
+        title: "Read Context Graph entrypoint",
+        description: "Return the downstream entrypoint for the latest Context Graph. Start from home.md before summaries/ or knowledge/.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphEntrypoint")));
     server.registerTool("context_graph_file_read", {
         title: "Read a Context Graph file",
-        description: "Read one prepared Context Graph file by relative path. Start with artifacts/ task handoffs, "
+        description: "Read one prepared Context Graph file by relative path. Start with home.md, "
             + "then use summaries/ for coverage and knowledge/ for drilldown. Do not use this to search unrelated Projects for answers.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
             path: z.string().min(1).describe("Relative path inside the Context Graph root."),
         },
     }, async (args) => callAndReturn(connectionArgs, contextGraphFilePath(args.project_id, args.path)));
@@ -750,23 +825,37 @@ function registerTools(server, connectionArgs) {
         description: "Read source-backed traces for the latest Context Graph. Use traces to follow prepared context "
             + "back to the Source for exact values, chart reads, tables, and provenance-sensitive claims.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "traces")));
+    server.registerTool("context_graph_sessions", {
+        title: "List Context Graph execution sessions",
+        description: "List the per-stage execution shell sessions for the latest Build run — executor + model, status, attempt, validation attempts, and replay readiness. Pull these to drive the next self-improvement iteration when a stage was weak or failed.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "contextGraphSessions")));
+    server.registerTool("context_graph_session", {
+        title: "Get one Context Graph execution session",
+        description: "Return one preserved execution shell session by stage_run_id — prompt, event/status log paths, runtime files, artifact mounts, validation attempts, and terminal verdict. Use it to inspect or replay exactly what a stage attempt did.",
+        inputSchema: {
+            project_id: McpProjectIdSchema,
+            stage_run_id: z.string().min(1).describe("Stage execution session id (stage_run_id) from context_graph_sessions."),
+        },
+    }, async (args) => callAndReturn(connectionArgs, `${projectSubresourcePath(args.project_id, "contextGraphSessions")}/${encodeURIComponent(args.stage_run_id)}`));
     server.registerTool("project_build_evidence", {
-        title: "Read Build evidence",
-        description: "Read the latest Build evidence resource for a Project: check rows, Artifact diagnostics, "
-            + "and readiness backing. If evidence is weak or missing, improve the Build Plan instead of answering.",
+        title: "Read Supplemental Build Diagnostics",
+        description: "Read the latest supplemental diagnostics resource for a Project. Prefer context_graph_show for primary metrics; if coverage is weak or missing, improve the Build Plan instead of answering.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
+            project_id: McpProjectIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, projectSubresourcePath(args.project_id, "buildEvidence")));
     server.registerTool("project_artifact_show", {
-        title: "Show Project Artifact",
-        description: "Return latest status and contributing evidence for one Build Plan-declared Artifact.",
+        title: "Show Requested Output",
+        description: "Return latest status and contributing evidence for one Build Plan-declared requested output.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
-            artifact_id: z.string().min(1).describe("Artifact id."),
+            project_id: McpProjectIdSchema,
+            artifact_id: McpArtifactIdSchema.describe("Requested output id."),
         },
     }, async (args) => callAndReturn(connectionArgs, `${projectSubresourcePath(args.project_id, "artifacts")}/${encodeURIComponent(args.artifact_id)}`));
     // ── Build Plans ────────────────────────────────────────────────────────
@@ -778,9 +867,9 @@ function registerTools(server, connectionArgs) {
         }, async () => callAndReturn(connectionArgs, LOCAL_SERVICE_ROUTES.buildPlans));
         server.registerTool("build_plan_show", {
             title: "Show one Build Plan",
-            description: "Developer/library tool. Return one Build Plan resource, including requested Artifacts, stages, and checks.",
+            description: "Developer/library tool. Return one Build Plan resource, including requested outputs, stages, and coverage checks.",
             inputSchema: {
-                build_plan_id: z.string().min(1).describe("Build Plan id."),
+                build_plan_id: McpBuildPlanIdSchema,
             },
         }, async (args) => callAndReturn(connectionArgs, buildPlanResourcePath(args.build_plan_id)));
         server.registerTool("build_plan_file_read", {
@@ -788,23 +877,22 @@ function registerTools(server, connectionArgs) {
             description: "Developer/library tool. Read one file inside a Build Plan package by relative path, such as "
                 + "build-plan.json, build-plan.schema.json, or a stage SKILL.md.",
             inputSchema: {
-                build_plan_id: z.string().min(1).describe("Build Plan id."),
+                build_plan_id: McpBuildPlanIdSchema,
                 path: z.string().min(1).describe("Relative path inside the Build Plan package."),
             },
         }, async (args) => callAndReturn(connectionArgs, `${buildPlanSubresourcePath(args.build_plan_id, "files")}/${encodeRelativePath(args.path)}`));
     }
     server.registerTool("build_plan_draft", {
         title: "Draft a Build Plan",
-        description: "Draft the task-specific Build Plan after the user approves the proposed Context Checks "
-            + "and requested Artifacts. This is the main Interf preparation action before building.",
+        description: "Draft the task-specific Build Plan from the Project intent, requested outputs, and optional coverage expectations. This is the main Interf preparation action before building.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
-            build_plan_id: z.string().min(1).describe("Build Plan id to create."),
+            project_id: McpProjectIdSchema,
+            build_plan_id: McpBuildPlanIdSchema.describe("Build Plan id to create."),
             label: z.string().min(1).describe("Human-readable Build Plan label."),
             hint: z.string().min(1).describe("Short Build Plan hint."),
-            intent: z.string().min(1).describe("Agent task this Build Plan should support."),
-            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Plain-English Context Checks the user approved before drafting."),
-            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested Artifacts the user approved before drafting. Use simple titles, descriptions, and plain-English checks."),
+            intent: z.string().min(1).optional().describe("Agent task this Build Plan should support. Omit to use the Project intent."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Optional legacy plain-English checks. Prefer Project intent plus requested outputs and coverage expectations."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested outputs the user approved before drafting. Use simple titles, descriptions, and coverage expectations."),
             source_context: SourceContextSchema.nullable().optional(),
             ...(!appProfile
                 ? {
@@ -819,7 +907,7 @@ function registerTools(server, connectionArgs) {
             build_plan_id: args.build_plan_id,
             label: args.label,
             hint: args.hint,
-            intent: args.intent,
+            ...(args.intent ? { intent: args.intent } : {}),
             ...(args.context_checks ? { checks: args.context_checks } : {}),
             ...(args.requested_artifacts ? { requested_artifacts: normalizeRequestedArtifacts(args.requested_artifacts) } : {}),
             ...(args.source_context !== undefined ? { source_context: args.source_context } : {}),
@@ -829,15 +917,15 @@ function registerTools(server, connectionArgs) {
     server.registerTool("build_plan_improve", {
         title: "Improve a Build Plan",
         description: "Improve the selected Build Plan when the current Context Graph is not ready for the user's task, "
-            + "for example when an Artifact is too coarse, a chart/table was under-extracted, or evidence is missing.",
+            + "for example when coverage is missing, an entrypoint is too coarse, a chart/table was under-extracted, or evidence is missing.",
         inputSchema: {
-            project_id: z.string().min(1).describe("Project id."),
-            build_plan_id: z.string().min(1).describe("Selected Build Plan id to improve."),
+            project_id: McpProjectIdSchema,
+            build_plan_id: McpBuildPlanIdSchema.describe("Selected Build Plan id to improve."),
             label: z.string().min(1).describe("Human-readable Build Plan label."),
             hint: z.string().min(1).describe("Short Build Plan hint."),
-            intent: z.string().min(1).describe("Change request or improvement goal."),
-            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Plain-English Context Checks the improved Plan must satisfy."),
-            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested Artifacts for the improved Plan. Use simple titles, descriptions, and plain-English checks."),
+            intent: z.string().min(1).optional().describe("Change request or improvement goal. Omit to use the Project intent."),
+            context_checks: z.array(BuildPlanContextCheckDraftSchema).optional().describe("Optional legacy plain-English checks. Prefer missing coverage and requested output changes."),
+            requested_artifacts: z.array(McpRequestedArtifactSchema).optional().describe("Requested outputs for the improved Plan. Use simple titles, descriptions, and coverage expectations."),
             source_context: SourceContextSchema.nullable().optional(),
             ...(!appProfile
                 ? {
@@ -853,7 +941,7 @@ function registerTools(server, connectionArgs) {
             reference_build_plan_id: args.build_plan_id,
             label: args.label,
             hint: args.hint,
-            intent: args.intent,
+            ...(args.intent ? { intent: args.intent } : {}),
             ...(args.context_checks ? { checks: args.context_checks } : {}),
             ...(args.requested_artifacts ? { requested_artifacts: normalizeRequestedArtifacts(args.requested_artifacts) } : {}),
             ...(args.source_context !== undefined ? { source_context: args.source_context } : {}),
@@ -866,7 +954,7 @@ function registerTools(server, connectionArgs) {
         description: "Return a compact run-status receipt for polling. This intentionally omits full trace events, "
             + "stream logs, and artifact manifests so repeated polls do not fill the agent context window.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
     }, async (args) => callAndProject(connectionArgs, runSubresourcePath(args.run_id, "status"), compactRunStatus));
     server.registerTool("runs_watch", {
@@ -874,7 +962,7 @@ function registerTools(server, connectionArgs) {
         description: "Read a bounded tail of run events for debugging or progress detail. Do not use this for polling; "
             + "poll runs_status until the run reaches a terminal state.",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
             limit: z.number().int().min(1).max(50).default(10).describe("Maximum recent events to return. Defaults to 10; max 50."),
             include_streams: z.boolean().default(false).describe("Include recent log stream chunks. Defaults to false because logs can be verbose."),
             stream_limit: z.number().int().min(1).max(20).default(5).describe("Maximum recent log stream chunks to return when include_streams is true. Defaults to 5; max 20."),
@@ -889,16 +977,25 @@ function registerTools(server, connectionArgs) {
             title: "Cancel a run",
             description: "Developer/admin tool. Request cancellation of an in-flight run.",
             inputSchema: {
-                run_id: z.string().min(1).describe("Run id."),
+                run_id: McpRunIdSchema,
             },
         }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/cancel`, { method: "POST", body: "{}" }));
     }
+    server.registerTool("runs_events", {
+        title: "Read full run event log",
+        description: "Return the full durable event log for a Build run: stage start/pass/fail, files processed, "
+            + "artifacts written, evidence, checks, and readiness. Use runs_status for polling and runs_watch "
+            + "for a bounded tail; use this to inspect or replay the complete sequence.",
+        inputSchema: {
+            run_id: McpRunIdSchema,
+        },
+    }, async (args) => callAndReturn(connectionArgs, runSubresourcePath(args.run_id, "events")));
     server.registerTool("runs_fetch", {
         title: "Fetch run artifacts",
         description: "Return the artifact manifest for a finished run (Context Graph, "
             + "evidence records, logs, run-scoped audit trail).",
         inputSchema: {
-            run_id: z.string().min(1).describe("Run id."),
+            run_id: McpRunIdSchema,
         },
     }, async (args) => callAndReturn(connectionArgs, `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(args.run_id)}/artifacts`));
     // ── Instance ────────────────────────────────────────────────────────────