proteum 2.2.8 → 2.3.0

package/common/dev/mcpPayloads.ts

@@ -0,0 +1,736 @@
+import type { TDevConsoleLogLevel, TDevConsoleLogsResponse } from './console';
+import type { TDoctorResponse } from './diagnostics';
+import { buildExplainSummaryItems } from './diagnostics';
+import type { TDiagnoseResponse, TExplainOwnerResponse, TOrientResponse } from './inspection';
+import type { TPerfRequestResponse, TPerfTopResponse } from './performance';
+import type { TProteumManifest } from './proteumManifest';
+import type { TRequestTrace } from './requestTrace';
+
+export type TProteumMcpNextAction = {
+    command?: string;
+    label: string;
+    reason?: string;
+    tool?: string;
+    toolArgs?: Record<string, unknown>;
+};
+
+export type TProteumMcpOmittedDetail = {
+    reason: string;
+    command?: string;
+    tool?: string;
+    toolArgs?: Record<string, unknown>;
+};
+
+export type TProteumMcpPayload<TData extends object = Record<string, unknown>> = {
+    ok: true;
+    format: 'proteum-mcp-v1';
+    summary: string;
+    data: TData;
+    nextActions?: TProteumMcpNextAction[];
+    omitted?: TProteumMcpOmittedDetail[];
+};
+
+type TNodeFs = {
+    existsSync: (filepath: string) => boolean;
+    readFileSync: (filepath: string, encoding: 'utf8') => string;
+    statSync: (filepath: string) => { isDirectory: () => boolean };
+};
+
+type TNodePath = {
+    dirname: (filepath: string) => string;
+    join: (...segments: string[]) => string;
+    relative: (from: string, to: string) => string;
+    resolve: (...segments: string[]) => string;
+};
+
+const maxInstructionPreviewLength = 360;
+const maxTextLength = 220;
+const nodeRequire = (() => {
+    try {
+        return eval('require') as NodeRequire;
+    } catch (_error) {
+        return undefined;
+    }
+})();
+const fs = nodeRequire ? (nodeRequire('fs') as TNodeFs) : undefined;
+const path = nodeRequire ? (nodeRequire('path') as TNodePath) : undefined;
+
+const hasNodeFs = () => fs !== undefined;
+const hasNodePath = () => path !== undefined;
+const fileExists = (filepath: string) => fs !== undefined && fs.existsSync(filepath);
+const directoryExists = (filepath: string) => {
+    if (fs === undefined || !fs.existsSync(filepath)) return false;
+    try {
+        return fs.statSync(filepath).isDirectory();
+    } catch (_error) {
+        return false;
+    }
+};
+
+export const truncateForMcp = (value: string, max = maxTextLength) =>
+    value.length <= max ? value : `${value.slice(0, max)}...`;
+
+export const compactList = <TValue>(values: TValue[], limit: number) => values.slice(0, Math.max(0, limit));
+
+export const createMcpPayload = <TData extends object>({
+    data,
+    nextActions,
+    omitted,
+    summary,
+}: Omit<TProteumMcpPayload<TData>, 'format' | 'ok'>): TProteumMcpPayload<TData> => ({
+    ok: true,
+    format: 'proteum-mcp-v1',
+    summary,
+    data,
+    ...(nextActions && nextActions.length > 0 ? { nextActions } : {}),
+    ...(omitted && omitted.length > 0 ? { omitted } : {}),
+});
+
+export const stringifyMcpPayload = (value: object) => JSON.stringify(value);
+
+export const summarizeManifest = (manifest: TProteumManifest | undefined) => {
+    if (!manifest) return undefined;
+
+    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+
+    return {
+        appRoot: manifest.app.root,
+        coreRoot: manifest.app.coreRoot,
+        identifier: manifest.app.identity.identifier,
+        name: manifest.app.identity.name,
+        routerPort: manifest.env.resolved.routerPort,
+        env: {
+            name: manifest.env.resolved.name,
+            profile: manifest.env.resolved.profile,
+            internalUrl: manifest.env.resolved.routerInternalUrl,
+        },
+        diagnostics: { errors, warnings },
+        counts: {
+            commands: manifest.commands.length,
+            connectedProjects: manifest.connectedProjects.length,
+            controllers: manifest.controllers.length,
+            layouts: manifest.layouts.length,
+            routes: manifest.routes.client.length + manifest.routes.server.length,
+            clientRoutes: manifest.routes.client.length,
+            serverRoutes: manifest.routes.server.length,
+            services: manifest.services.app.length + manifest.services.routerPlugins.length,
+        },
+    };
+};
+
+const compactOwnerMatch = (match: TExplainOwnerResponse['matches'][number]) => ({
+    kind: match.kind,
+    label: match.label,
+    score: match.score,
+    scope: match.scopeLabel,
+    origin: match.originHint,
+    source: match.source,
+});
+
+const compactDiagnostic = (diagnostic: TDoctorResponse['diagnostics'][number]) => ({
+    level: diagnostic.level,
+    code: diagnostic.code,
+    message: truncateForMcp(diagnostic.message),
+    filepath: diagnostic.filepath,
+    sourceLocation: diagnostic.sourceLocation,
+    fixHint: diagnostic.fixHint ? truncateForMcp(diagnostic.fixHint) : undefined,
+});
+
+export const compactDoctorResponse = ({
+    contracts,
+    doctor,
+}: {
+    contracts?: TDoctorResponse;
+    doctor: TDoctorResponse;
+}) =>
+    createMcpPayload({
+        summary: contracts
+            ? `Doctor: ${doctor.summary.errors} errors/${doctor.summary.warnings} warnings; contracts: ${contracts.summary.errors} errors/${contracts.summary.warnings} warnings`
+            : `Doctor: ${doctor.summary.errors} errors/${doctor.summary.warnings} warnings`,
+        data: {
+            doctor: {
+                summary: doctor.summary,
+                top: compactList(doctor.diagnostics, 8).map(compactDiagnostic),
+                total: doctor.diagnostics.length,
+            },
+            contracts: contracts
+                ? {
+                      summary: contracts.summary,
+                      top: compactList(contracts.diagnostics, 8).map(compactDiagnostic),
+                      total: contracts.diagnostics.length,
+                  }
+                : undefined,
+        },
+        omitted:
+            doctor.diagnostics.length > 8 || (contracts && contracts.diagnostics.length > 8)
+                ? [
+                      {
+                          reason: 'Diagnostics are capped in MCP output. Use the CLI full-detail command when every diagnostic is required.',
+                          command: 'proteum doctor --full',
+                      },
+                  ]
+                : undefined,
+    });
+
+export const compactOrientationResponse = (response: TOrientResponse) => {
+    const topOwner = response.owner.matches[0];
+    const summary = topOwner
+        ? `${response.query} -> ${topOwner.kind} ${topOwner.label} (${topOwner.scopeLabel})`
+        : `${response.query} -> no manifest owner matched`;
+
+    return createMcpPayload({
+        summary,
+        data: {
+            query: response.query,
+            app: response.app,
+            owner: {
+                top: topOwner ? compactOwnerMatch(topOwner) : undefined,
+                matches: compactList(response.owner.matches, 5).map(compactOwnerMatch),
+                totalReturned: response.owner.matches.length,
+            },
+            instructions: {
+                mustRead: [...new Set([response.guidance.agents, ...response.guidance.areaAgents])],
+                readWhen: [
+                    {
+                        file: response.guidance.diagnostics,
+                        when: 'Raw errors, failing requests, traces, perf regressions, or reproduction work.',
+                    },
+                    {
+                        file: response.guidance.codingStyle,
+                        when: 'Before editing implementation files.',
+                    },
+                    {
+                        file: response.guidance.optimizations,
+                        when: 'Client-side implementation, packages, build, runtime, or performance work.',
+                    },
+                ],
+            },
+            connected: {
+                imports: compactList(response.connected.imports, 5),
+                producers: compactList(response.connected.producers, 4),
+                totalImports: response.connected.imports.length,
+                totalProducers: response.connected.producers.length,
+            },
+            warnings: response.warnings,
+        },
+        nextActions: response.nextSteps.map((step) => ({
+            command: step.command,
+            label: step.label,
+            reason: step.reason,
+        })),
+    });
+};
+
+export const compactExplainSummary = ({
+    manifest,
+    owner,
+    query,
+}: {
+    manifest: TProteumManifest;
+    owner?: TExplainOwnerResponse;
+    query?: string;
+}) => {
+    if (owner) {
+        const topOwner = owner.matches[0];
+        return createMcpPayload({
+            summary: topOwner
+                ? `${query || owner.query} -> ${topOwner.kind} ${topOwner.label} (${topOwner.scopeLabel})`
+                : `${query || owner.query} -> no owner matched`,
+            data: {
+                query: query || owner.query,
+                normalizedQuery: owner.normalizedQuery,
+                owner: {
+                    top: topOwner ? compactOwnerMatch(topOwner) : undefined,
+                    matches: compactList(owner.matches, 8).map(compactOwnerMatch),
+                    totalReturned: owner.matches.length,
+                },
+                manifest: summarizeManifest(manifest),
+            },
+        });
+    }
+
+    const items = buildExplainSummaryItems(manifest).map((item) => truncateForMcp(item, 300));
+    return createMcpPayload({
+        summary: `Manifest ${manifest.app.identity.identifier}: ${manifest.controllers.length} controllers, ${manifest.routes.client.length + manifest.routes.server.length} routes`,
+        data: {
+            manifest: summarizeManifest(manifest),
+            summaryItems: items,
+        },
+    });
+};
+
+const compactRequest = (request: TDiagnoseResponse['request']) =>
+    request
+        ? {
+              id: request.id,
+              method: request.method,
+              path: request.path,
+              statusCode: request.statusCode,
+              durationMs: request.durationMs,
+              capture: request.capture,
+              user: request.user,
+              errorMessage: request.errorMessage ? truncateForMcp(request.errorMessage) : undefined,
+              counts: {
+                  calls: request.calls.length,
+                  events: request.events.length,
+                  sqlQueries: request.sqlQueries.length,
+                  droppedEvents: request.droppedEvents,
+              },
+          }
+        : undefined;
+
+export const compactDiagnoseResponse = (response: TDiagnoseResponse) => {
+    const request = compactRequest(response.request);
+    const doctorSummary = `${response.doctor.summary.errors} doctor errors/${response.doctor.summary.warnings} warnings`;
+    const contractsSummary = `${response.contracts.summary.errors} contract errors/${response.contracts.summary.warnings} warnings`;
+    const traceSummary = request
+        ? `${request.method} ${request.path} status=${request.statusCode ?? 'pending'} durationMs=${request.durationMs ?? 'pending'}`
+        : 'no matching request trace';
+
+    return createMcpPayload({
+        summary: `${response.query || 'request'}: ${traceSummary}; ${doctorSummary}; ${contractsSummary}`,
+        data: {
+            query: response.query,
+            request,
+            owner: {
+                top: response.owner.matches[0] ? compactOwnerMatch(response.owner.matches[0]) : undefined,
+                matches: compactList(response.owner.matches, 5).map(compactOwnerMatch),
+                totalReturned: response.owner.matches.length,
+            },
+            suspects: compactList(response.suspects, 8),
+            chain: compactList(response.chain || [], 10),
+            diagnostics: {
+                doctor: {
+                    summary: response.doctor.summary,
+                    top: compactList(response.doctor.diagnostics, 8).map(compactDiagnostic),
+                    total: response.doctor.diagnostics.length,
+                },
+                contracts: {
+                    summary: response.contracts.summary,
+                    top: compactList(response.contracts.diagnostics, 8).map(compactDiagnostic),
+                    total: response.contracts.diagnostics.length,
+                },
+            },
+            logs: compactList(response.serverLogs.logs, 12).map((entry) => ({
+                level: entry.level,
+                time: entry.time,
+                text: truncateForMcp(entry.text),
+            })),
+            instructions: response.orientation
+                ? {
+                      mustRead: [...new Set([response.orientation.guidance.agents, ...response.orientation.guidance.areaAgents])],
+                      diagnostics: response.orientation.guidance.diagnostics,
+                      codingStyle: response.orientation.guidance.codingStyle,
+                      optimizations: response.orientation.guidance.optimizations,
+                  }
+                : undefined,
+        },
+        nextActions: response.orientation?.nextSteps.map((step) => ({
+            command: step.command,
+            label: step.label,
+            reason: step.reason,
+        })),
+        omitted: response.request
+            ? [
+                  {
+                      reason: 'Full request events, payload summaries, and SQL text are omitted from MCP diagnose output.',
+                      tool: 'trace_show',
+                      toolArgs: { requestId: response.request.id, detail: 'full', limit: 50 },
+                  },
+              ]
+            : undefined,
+    });
+};
+
+const compactTraceCall = (call: TRequestTrace['calls'][number]) => ({
+    id: call.id,
+    origin: call.origin,
+    label: call.label,
+    method: call.method,
+    path: call.path,
+    statusCode: call.statusCode,
+    durationMs: call.durationMs,
+    errorMessage: call.errorMessage ? truncateForMcp(call.errorMessage) : undefined,
+});
+
+const compactTraceSql = (query: TRequestTrace['sqlQueries'][number], includeQuery = false) => ({
+    id: query.id,
+    caller: query.callerLabel || `${query.callerMethod} ${query.callerPath}`,
+    kind: query.kind,
+    operation: query.operation,
+    model: query.model,
+    durationMs: query.durationMs,
+    fingerprint: query.fingerprint,
+    query: includeQuery ? truncateForMcp(query.query, 180) : undefined,
+});
+
+const compactTraceEvent = (event: TRequestTrace['events'][number], includeDetails = false) => ({
+    index: event.index,
+    elapsedMs: event.elapsedMs,
+    type: event.type,
+    detailKeys: Object.keys(event.details),
+    details: includeDetails ? event.details : undefined,
+});
+
+export const compactTraceResponse = ({
+    detail = 'compact',
+    limit = 50,
+    offset = 0,
+    request,
+}: {
+    detail?: 'compact' | 'full';
+    limit?: number;
+    offset?: number;
+    request: TRequestTrace;
+}) => {
+    const failedCalls = request.calls.filter((call) => call.errorMessage || (call.statusCode !== undefined && call.statusCode >= 400));
+    const errorEvents = request.events.filter((event) => event.type === 'error');
+    const hotCalls = [...request.calls].sort((left, right) => (right.durationMs || 0) - (left.durationMs || 0));
+    const hotSql = [...request.sqlQueries].sort((left, right) => right.durationMs - left.durationMs);
+    const pageOffset = Math.max(0, offset);
+    const pageLimit = Math.max(1, Math.min(100, limit));
+    const full = detail === 'full';
+
+    return createMcpPayload({
+        summary: `${request.id}: ${request.method} ${request.path} status=${request.statusCode ?? 'pending'} durationMs=${request.durationMs ?? 'pending'} events=${request.events.length} calls=${request.calls.length} sql=${request.sqlQueries.length}`,
+        data: {
+            request: {
+                id: request.id,
+                method: request.method,
+                path: request.path,
+                statusCode: request.statusCode,
+                durationMs: request.durationMs,
+                capture: request.capture,
+                user: request.user,
+                errorMessage: request.errorMessage ? truncateForMcp(request.errorMessage) : undefined,
+                droppedEvents: request.droppedEvents,
+                persistedFilepath: request.persistedFilepath,
+            },
+            counts: {
+                calls: request.calls.length,
+                events: request.events.length,
+                sqlQueries: request.sqlQueries.length,
+            },
+            failedCalls: compactList(failedCalls, 6).map(compactTraceCall),
+            errorEvents: compactList(errorEvents, 6).map((event) => compactTraceEvent(event, full)),
+            hotCalls: compactList(hotCalls, 6).map(compactTraceCall),
+            hotSql: compactList(hotSql, 6).map((query) => compactTraceSql(query, full)),
+            page: full
+                ? {
+                      offset: pageOffset,
+                      limit: pageLimit,
+                      events: request.events.slice(pageOffset, pageOffset + pageLimit).map((event) => compactTraceEvent(event, true)),
+                      calls: request.calls.slice(pageOffset, pageOffset + pageLimit).map(compactTraceCall),
+                      sqlQueries: request.sqlQueries
+                          .slice(pageOffset, pageOffset + pageLimit)
+                          .map((query) => compactTraceSql(query, true)),
+                      hasMore:
+                          request.events.length > pageOffset + pageLimit ||
+                          request.calls.length > pageOffset + pageLimit ||
+                          request.sqlQueries.length > pageOffset + pageLimit,
+                  }
+                : undefined,
+        },
+        nextActions: [
+            {
+                label: 'Diagnose Request',
+                tool: 'diagnose',
+                toolArgs: { requestId: request.id, query: request.path },
+                reason: 'Combine this trace with owner lookup, diagnostics, suspects, and server logs.',
+            },
+            {
+                label: 'Perf Request',
+                tool: 'perf_request',
+                toolArgs: { query: request.id },
+                reason: 'Inspect request timing, SQL, render, and memory rollups without full events.',
+            },
+        ],
+        omitted: full
+            ? undefined
+            : [
+                  {
+                      reason: 'Full events, payload summaries, raw SQL, and call bodies are omitted by default.',
+                      tool: 'trace_show',
+                      toolArgs: { requestId: request.id, detail: 'full', limit: 50 },
+                  },
+              ],
+    });
+};
+
+const formatDuration = (value?: number) => (value === undefined ? 'n/a' : `${Math.round(value)} ms`);
+
+const compactTopLikeRow = (row: TPerfTopResponse['rows'][number]) => ({
+    label: row.label,
+    requestCount: row.requestCount,
+    avgDurationMs: row.avgDurationMs,
+    p95DurationMs: row.p95DurationMs,
+    maxDurationMs: row.maxDurationMs,
+    avgCpuMs: row.avgCpuMs,
+    avgSqlDurationMs: row.avgSqlDurationMs,
+    avgRenderDurationMs: row.avgRenderDurationMs,
+    avgHeapDeltaBytes: row.avgHeapDeltaBytes,
+    slowestRequestId: row.slowestRequestId,
+});
+
+export const compactPerfTopResponse = (response: TPerfTopResponse) =>
+    createMcpPayload({
+        summary: `Perf top ${response.groupBy}: ${response.summary.requestCount} requests, ${response.summary.errorCount} errors, p95=${formatDuration(response.summary.p95DurationMs)}`,
+        data: {
+            groupBy: response.groupBy,
+            window: response.window,
+            summary: response.summary,
+            rows: compactList(response.rows, 10).map(compactTopLikeRow),
+            totalRows: response.rows.length,
+        },
+        omitted:
+            response.rows.length > 10
+                ? [{ reason: 'Perf rows are capped. Increase the tool limit or use `proteum perf top --full` for raw detail.' }]
+                : undefined,
+    });
+
+const compactPerfSql = (query: TPerfRequestResponse['request']['hottestSqlQueries'][number]) => ({
+    callerLabel: query.callerLabel,
+    operation: query.operation,
+    model: query.model,
+    fingerprint: query.fingerprint,
+    durationMs: query.durationMs,
+    query: truncateForMcp(query.query, 160),
+});
+
+export const compactPerfRequestResponse = (response: TPerfRequestResponse) =>
+    createMcpPayload({
+        summary: `${response.request.requestId}: ${response.request.method} ${response.request.path} total=${formatDuration(response.request.totalDurationMs)} cpu=${formatDuration(response.request.cpuTotalMs)} sql=${formatDuration(response.request.sqlDurationMs)}`,
+        data: {
+            request: {
+                requestId: response.request.requestId,
+                method: response.request.method,
+                path: response.request.path,
+                statusCode: response.request.statusCode,
+                routeLabel: response.request.routeLabel,
+                controllerLabel: response.request.controllerLabel,
+                totalDurationMs: response.request.totalDurationMs,
+                cpuTotalMs: response.request.cpuTotalMs,
+                sqlDurationMs: response.request.sqlDurationMs,
+                callDurationMs: response.request.callDurationMs,
+                renderDurationMs: response.request.renderDurationMs,
+                selfDurationMs: response.request.selfDurationMs,
+                heapDeltaBytes: response.request.heapDeltaBytes,
+            },
+            stages: compactList(response.request.stages, 10),
+            hotCalls: compactList(response.request.hottestCalls, 8),
+            chain: compactList(response.request.chain || [], 10),
+            hotSql: compactList(response.request.hottestSqlQueries, 8).map(compactPerfSql),
+        },
+        nextActions: [
+            {
+                label: 'Diagnose Request',
+                tool: 'diagnose',
+                toolArgs: { query: response.request.path, requestId: response.request.requestId },
+                reason: 'Combine this request with owner, diagnostics, suspects, and logs.',
+            },
+            {
+                label: 'Trace Events',
+                tool: 'trace_show',
+                toolArgs: { requestId: response.request.requestId, detail: 'full', limit: 50 },
+                reason: 'Open raw event detail only if the compact waterfall is insufficient.',
+            },
+        ],
+    });
+
+export const compactLogsResponse = ({
+    level,
+    limit,
+    response,
+}: {
+    level: TDevConsoleLogLevel;
+    limit: number;
+    response: TDevConsoleLogsResponse;
+}) =>
+    createMcpPayload({
+        summary: `${response.logs.length} dev log lines at level >= ${level}`,
+        data: {
+            level,
+            limit,
+            logs: response.logs.map((entry) => ({
+                level: entry.level,
+                time: entry.time,
+                text: truncateForMcp(entry.text),
+            })),
+        },
+        omitted:
+            response.logs.length >= limit
+                ? [{ reason: 'Log output reached the requested cap. Increase limit only when the latest compact lines are insufficient.' }]
+                : undefined,
+    });
+
+const readPreview = (filepath: string) => {
+    if (fs === undefined) return undefined;
+    try {
+        return truncateForMcp(fs.readFileSync(filepath, 'utf8').replace(/\s+/g, ' ').trim(), maxInstructionPreviewLength);
+    } catch (_error) {
+        return undefined;
+    }
+};
+
+const findNearestRootWith = (startDir: string, relativeFilepath: string) => {
+    if (path === undefined) return undefined;
+    let current = path.resolve(startDir);
+
+    while (true) {
+        if (fileExists(path.join(current, relativeFilepath))) return current;
+        const parent = path.dirname(current);
+        if (parent === current) return undefined;
+        current = parent;
+    }
+};
+
+const findLikelyRepoRoot = (appRoot: string) => {
+    if (path === undefined) return appRoot;
+    let current = path.resolve(appRoot);
+
+    while (true) {
+        if (directoryExists(path.join(current, '.git'))) return current;
+        const parent = path.dirname(current);
+        if (parent === current) return appRoot;
+        current = parent;
+    }
+};
+
+const resolveDocumentFile = ({
+    appRoot,
+    repoRoot,
+    relativeFilepath,
+}: {
+    appRoot: string;
+    repoRoot: string;
+    relativeFilepath: string;
+}) => {
+    if (path === undefined) return undefined;
+
+    const appFilepath = path.join(appRoot, relativeFilepath);
+    if (fileExists(appFilepath)) return appFilepath;
+
+    const repoFilepath = path.join(repoRoot, relativeFilepath);
+    if (fileExists(repoFilepath)) return repoFilepath;
+
+    const nearestRoot = findNearestRootWith(appRoot, relativeFilepath);
+    return nearestRoot ? path.join(nearestRoot, relativeFilepath) : undefined;
+};
+
+export const resolveInstructionRouting = ({
+    appRoot,
+    query = '',
+}: {
+    appRoot: string;
+    query?: string;
+}) => {
+    const normalizedQuery = query.trim();
+    const repoRoot = findLikelyRepoRoot(appRoot);
+    const selected = new Map<string, { file: string; reason: string; preview?: string }>();
+    const readWhen: Array<{ file?: string; when: string }> = [];
+    const addInstruction = (relativeFilepath: string, reason: string, preferAppRoot = true) => {
+        if (path === undefined) return;
+        const roots = preferAppRoot ? [appRoot, repoRoot] : [repoRoot, appRoot];
+        for (const root of [...new Set(roots)]) {
+            const filepath = path.join(root, relativeFilepath);
+            if (!fileExists(filepath)) continue;
+            selected.set(filepath, { file: filepath, reason, preview: readPreview(filepath) });
+            return;
+        }
+    };
+    const addReadWhen = (relativeFilepath: string, when: string) => {
+        const filepath = resolveDocumentFile({ appRoot, repoRoot, relativeFilepath });
+        readWhen.push({ file: filepath, when });
+    };
+    const lowerQuery = normalizedQuery.toLowerCase();
+    const looksLikePage = lowerQuery.startsWith('/') || lowerQuery.includes('client/pages') || lowerQuery.includes('.tsx');
+    const looksLikeClient = looksLikePage || lowerQuery.includes('client/') || lowerQuery.includes('component') || lowerQuery.includes('island');
+    const looksLikeServerRoute =
+        lowerQuery.includes('server/routes') ||
+        lowerQuery.includes('route') ||
+        lowerQuery.includes('sitemap') ||
+        lowerQuery.includes('rss') ||
+        lowerQuery.startsWith('/api');
+    const looksLikeService =
+        lowerQuery.includes('server/services') ||
+        lowerQuery.includes('.controller') ||
+        lowerQuery.includes('controller') ||
+        lowerQuery.includes('service');
+    const looksLikeE2e = lowerQuery.includes('tests/e2e') || lowerQuery.includes('playwright') || lowerQuery.includes('journey');
+
+    addInstruction('AGENTS.md', 'Start with the root/app routing contract.');
+    if (repoRoot !== appRoot) addInstruction('AGENTS.md', 'Also apply the monorepo root routing contract.', false);
+    if (looksLikeClient) addInstruction('client/AGENTS.md', 'Client code or browser-visible behavior is in scope.');
+    if (looksLikePage) addInstruction('client/pages/AGENTS.md', 'Page routing, SSR data, or page render behavior may be in scope.');
+    if (looksLikeServerRoute) addInstruction('server/routes/AGENTS.md', 'Server route or crawlable endpoint behavior may be in scope.');
+    if (looksLikeService) addInstruction('server/services/AGENTS.md', 'Service/controller contracts or backend runtime behavior may be in scope.');
+    if (looksLikeE2e) {
+        addInstruction('tests/e2e/AGENTS.md', 'End-to-end behavior or Playwright workflow is in scope.');
+        addInstruction('tests/e2e/REAL_WORLD_JOURNEY_TESTS.md', 'Real-world journey coverage may be in scope.');
+    }
+
+    addReadWhen('diagnostics.md', 'Read for raw errors, failing requests, traces, perf regressions, or reproduction work.');
+    addReadWhen('CODING_STYLE.md', 'Read before editing implementation files.');
+    addReadWhen('optimizations.md', 'Read for client-side implementation, packages, build, runtime, or performance work.');
+
+    const selectedFiles = [...selected.values()];
+    return createMcpPayload({
+        summary: `${selectedFiles.length} instruction files selected for ${normalizedQuery || 'current app'}`,
+        data: {
+            query: normalizedQuery,
+            appRoot,
+            repoRoot,
+            selected: selectedFiles,
+            readWhen,
+            missingRuntime:
+                selectedFiles.length === 0
+                    ? 'No tracked instruction files were found. Run `proteum configure agents` or start `proteum dev` to refresh managed instructions.'
+                    : undefined,
+        },
+    });
+};
+
+export const buildRuntimeStatusPayload = ({
+    appRoot,
+    health,
+    manifest,
+    runtime,
+    sessions,
+}: {
+    appRoot: string;
+    health?: object;
+    manifest?: TProteumManifest;
+    runtime?: object;
+    sessions?: object[];
+}) =>
+    createMcpPayload({
+        summary: runtime
+            ? `Runtime available for ${manifest?.app.identity.identifier || appRoot}`
+            : manifest
+              ? `Manifest available for ${manifest.app.identity.identifier}; no live runtime selected`
+              : `No Proteum manifest found for ${appRoot}`,
+        data: {
+            appRoot,
+            manifest: summarizeManifest(manifest),
+            runtime,
+            sessions,
+            health,
+        },
+        nextActions: runtime
+            ? [
+                  {
+                      label: 'Diagnose Root',
+                      tool: 'diagnose',
+                      toolArgs: { query: '/', path: '/' },
+                      reason: 'Use the selected runtime for the smallest request-level diagnostic pass.',
+                  },
+              ]
+            : [
+                  {
+                      label: 'Start Dev',
+                      command: 'proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port <free-port>',
+                      reason: 'Create a tracked dev session before request-time diagnostics.',
+                  },
+              ],
+    });