@lightpath-dev/mcp 0.0.0-stage → 0.1.0

package/dist/request.d.ts

@@ -0,0 +1,64 @@
+import { type Trace, type TraceId } from '@lightpath-dev/protocol';
+/** Longest wait after the response for the backend trace (design section 4A, D-125). */
+export declare const REQUEST_TRACE_WAIT_MS = 1500;
+export declare const REQUEST_METHODS: readonly ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+export type RequestMethod = (typeof REQUEST_METHODS)[number];
+export interface RunRequestInput {
+    method?: RequestMethod | undefined;
+    /** A path (`/api/orders`), resolved against the app's URL, or a full loopback URL. */
+    url: string;
+    body?: string | undefined;
+    contentType?: string | undefined;
+    timeoutMs?: number | undefined;
+}
+export type Resolver = (host: string) => Promise<{
+    address: string;
+    family: number;
+}[]>;
+/** True for 127.0.0.0/8 and ::1 (and ::ffff:127.x), the only addresses a request may go to. */
+export declare function isLoopbackAddress(address: string): boolean;
+export type Target = {
+    ok: true;
+    url: URL;
+    address: string;
+    family: number;
+} | {
+    ok: false;
+    code: 'not_loopback' | 'no_app_url';
+    message: string;
+};
+/**
+ * Checks where a request would go, before any network call (design section 4A): http or https,
+ * host `localhost`, `127.0.0.1` or `[::1]`, and every address `localhost` resolves to on loopback.
+ * Returns the vetted address, so the request connects there and can't be sent elsewhere by a
+ * second lookup.
+ */
+export declare function resolveTarget(raw: string, appUrl: string | undefined, resolve?: Resolver): Promise<Target>;
+/** `/api/orders?token=x` → `/api/orders`: queries never reach the output (they can hold secrets). */
+export declare const pathOnly: (pathOrUrl: string) => string;
+/** `t_` + 12 random base36 characters, the TraceId format (packages/protocol/src/model.ts). */
+export declare function newRequestTraceId(): TraceId;
+export type Sent = {
+    ok: true;
+    status: number;
+    bytes: number;
+    durationMs: number;
+    location?: string | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Sends one request to a vetted loopback address with Lightpath's trace header. Uses node:http
+ * with its own agent: no proxy (HTTP_PROXY, HTTPS_PROXY and NODE_USE_ENV_PROXY are ignored), no
+ * redirect followed, and the connection goes to the address `resolveTarget` checked. The response
+ * body is read for its size only and never kept.
+ */
+export declare function sendRequest(target: Extract<Target, {
+    ok: true;
+}>, input: RunRequestInput, traceId: TraceId): Promise<Sent>;
+/** Where a redirect points, when that is loopback too: its origin only. Undefined otherwise. */
+export declare function loopbackLocation(location: string | undefined, base: URL): string | undefined;
+/** True once the trace holds the backend side of the request (a non-browser request entry). */
+export declare const hasBackend: (t: Trace | null | undefined) => boolean;
+//# sourceMappingURL=request.d.ts.map

package/dist/request.js

@@ -0,0 +1,165 @@
+import { randomBytes } from 'node:crypto';
+import { lookup as dnsLookup } from 'node:dns/promises';
+import http from 'node:http';
+import https from 'node:https';
+import { TRACE_HEADER } from '@lightpath-dev/protocol';
+/** Longest wait after the response for the backend trace (design section 4A, D-125). */
+export const REQUEST_TRACE_WAIT_MS = 1500;
+export const REQUEST_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** True for 127.0.0.0/8 and ::1 (and ::ffff:127.x), the only addresses a request may go to. */
+export function isLoopbackAddress(address) {
+    const v4 = address.startsWith('::ffff:') ? address.slice('::ffff:'.length) : address;
+    if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(v4))
+        return true;
+    return address === '::1' || address === '0:0:0:0:0:0:0:1';
+}
+/**
+ * Checks where a request would go, before any network call (design section 4A): http or https,
+ * host `localhost`, `127.0.0.1` or `[::1]`, and every address `localhost` resolves to on loopback.
+ * Returns the vetted address, so the request connects there and can't be sent elsewhere by a
+ * second lookup.
+ */
+export async function resolveTarget(raw, appUrl, resolve = (host) => dnsLookup(host, { all: true, verbatim: true })) {
+    let url;
+    if (raw.startsWith('/')) {
+        if (!appUrl) {
+            return {
+                ok: false,
+                code: 'no_app_url',
+                message: `"${pathOnly(raw)}" is a path, but no app URL is set. Pass a full loopback URL like http://localhost:3001${pathOnly(raw)}, or set "url" in lightpath.config.json.`,
+            };
+        }
+        try {
+            url = new URL(raw, appUrl);
+        }
+        catch {
+            return { ok: false, code: 'not_loopback', message: `"url" in lightpath.config.json isn't a URL.` };
+        }
+    }
+    else {
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            return {
+                ok: false,
+                code: 'not_loopback',
+                message: 'Not a URL. Pass a path like /api/orders or http://localhost:3001/api/orders.',
+            };
+        }
+    }
+    const refuse = (why) => ({
+        ok: false,
+        code: 'not_loopback',
+        message: `Refused before sending: ${why}. run_request only sends to localhost, 127.0.0.1 or [::1], so nothing leaves this machine.`,
+    });
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return refuse(`the scheme is ${url.protocol.replace(':', '')}`);
+    if (url.username || url.password)
+        return refuse('the URL has a user name or password');
+    if (!LOOPBACK_HOSTS.has(url.hostname))
+        return refuse(`the host is ${url.hostname}`);
+    if (url.hostname === '127.0.0.1')
+        return { ok: true, url, address: '127.0.0.1', family: 4 };
+    if (url.hostname === '[::1]')
+        return { ok: true, url, address: '::1', family: 6 };
+    let addresses;
+    try {
+        addresses = await resolve('localhost');
+    }
+    catch {
+        return refuse('localhost did not resolve');
+    }
+    if (addresses.length === 0 || !addresses.every((a) => isLoopbackAddress(a.address))) {
+        return refuse(`localhost resolves to ${addresses.map((a) => a.address).join(', ') || 'nothing'}, not only loopback`);
+    }
+    // Prefer IPv4, as dev servers bound to 127.0.0.1 are the common case; fall back to the rest.
+    const first = addresses.find((a) => a.family === 4) ?? addresses[0];
+    return { ok: true, url, address: first.address, family: first.family };
+}
+/** `/api/orders?token=x` → `/api/orders`: queries never reach the output (they can hold secrets). */
+export const pathOnly = (pathOrUrl) => pathOrUrl.split(/[?#]/)[0] ?? pathOrUrl;
+/** `t_` + 12 random base36 characters, the TraceId format (packages/protocol/src/model.ts). */
+export function newRequestTraceId() {
+    const alphabet = '0123456789abcdefghijklmnopqrstuvwxyz';
+    const bytes = randomBytes(12);
+    let id = 't_';
+    for (const b of bytes)
+        id += alphabet[b % 36];
+    return id;
+}
+/**
+ * Sends one request to a vetted loopback address with Lightpath's trace header. Uses node:http
+ * with its own agent: no proxy (HTTP_PROXY, HTTPS_PROXY and NODE_USE_ENV_PROXY are ignored), no
+ * redirect followed, and the connection goes to the address `resolveTarget` checked. The response
+ * body is read for its size only and never kept.
+ */
+export function sendRequest(target, input, traceId) {
+    const { url } = target;
+    const lib = url.protocol === 'https:' ? https : http;
+    const agent = new lib.Agent({ keepAlive: false });
+    const lookup = (_host, options, callback) => {
+        const all = typeof options === 'object' && options !== null && 'all' in options && options.all;
+        if (all)
+            callback(null, [
+                { address: target.address, family: target.family },
+            ]);
+        else
+            callback(null, target.address, target.family);
+    };
+    const headers = { [TRACE_HEADER]: traceId };
+    if (input.body !== undefined) {
+        headers['content-type'] = input.contentType ?? 'application/json';
+        headers['content-length'] = String(Buffer.byteLength(input.body));
+    }
+    else if (input.contentType)
+        headers['content-type'] = input.contentType;
+    const started = performance.now();
+    const timeoutMs = input.timeoutMs ?? 10_000;
+    return new Promise((resolve) => {
+        const req = lib.request(url, { method: input.method ?? 'GET', headers, agent, lookup, timeout: timeoutMs }, (res) => {
+            let bytes = 0;
+            res.on('data', (chunk) => {
+                bytes += chunk.length;
+            });
+            res.on('end', () => {
+                agent.destroy();
+                resolve({
+                    ok: true,
+                    status: res.statusCode ?? 0,
+                    bytes,
+                    durationMs: performance.now() - started,
+                    location: typeof res.headers.location === 'string' ? res.headers.location : undefined,
+                });
+            });
+            res.on('error', (err) => {
+                agent.destroy();
+                resolve({ ok: false, message: err.message });
+            });
+        });
+        req.on('timeout', () => req.destroy(new Error(`no response within ${timeoutMs} ms`)));
+        req.on('error', (err) => {
+            agent.destroy();
+            resolve({ ok: false, message: err.code ?? err.message });
+        });
+        if (input.body !== undefined)
+            req.write(input.body);
+        req.end();
+    });
+}
+/** Where a redirect points, when that is loopback too: its origin only. Undefined otherwise. */
+export function loopbackLocation(location, base) {
+    if (!location)
+        return undefined;
+    try {
+        const to = new URL(location, base);
+        return LOOPBACK_HOSTS.has(to.hostname) ? `${to.origin}${pathOnly(to.pathname)}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True once the trace holds the backend side of the request (a non-browser request entry). */
+export const hasBackend = (t) => Boolean(t?.requests.some((r) => r.collector !== 'browser'));
+//# sourceMappingURL=request.js.map

package/dist/server.d.ts

@@ -0,0 +1,32 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AutoStartOptions } from './autostart.js';
+import { type Resolver } from './request.js';
+import { type ReadSource } from './slices.js';
+/**
+ * The run_action description (docs/design/agent-loop.md section 3, D-119; bug-report trigger and
+ * one step per call, D-134): under 300 characters.
+ */
+export declare const RUN_ACTION_DESCRIPTION: string;
+export interface McpOptions {
+    workspaceRoot: string;
+    /** Resolves `localhost` for run_request's loopback check (tests pass a fake). */
+    resolver?: Resolver;
+    /** How long run_request waits for the backend trace after the response (default 1,500 ms). */
+    requestTraceWaitMs?: number;
+    /** Starting Lightpath when it isn't running (D-122): set by `lightpath mcp` from the config. */
+    autoStart?: AutoStartOptions;
+    /** How long to wait for an auto-started daemon and its browser (default 60 s). */
+    autoStartWaitMs?: number;
+}
+/**
+ * Builds the MCP server (docs/ARCHITECTURE.md section 9.3). Every call reads the discovery file
+ * and connects fresh, so the server works whether `lightpath dev` started before or after it.
+ */
+export declare function createMcpServer(options: McpOptions): McpServer;
+export declare function runMcpServer(options: McpOptions): Promise<void>;
+/**
+ * Reads trace files for slices (D-117): only a workspace-relative path whose real path is inside
+ * one of the daemon's workspace roots. The daemon never reads files for clients (ARCHITECTURE 7.2).
+ */
+export declare function workspaceReader(roots: readonly string[]): ReadSource;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,341 @@
+import { readFileSync } from 'node:fs';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { DaemonClient, DaemonDiscovery, DISCOVERY_FILE, PROTOCOL_VERSION, postAction, } from '@lightpath-dev/protocol';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { AUTO_START_WAIT_MS, AutoStarter, DEV_LOG } from './autostart.js';
+import { fitText } from './budget.js';
+import { diffFunctions, hasFunctions } from './diff.js';
+import { describeActionResult, describeRequestResult, describeSummaries, diffTraces, redirectNote, } from './format.js';
+import { redact, redactFillValues } from './redact.js';
+import { hasBackend, loopbackLocation, newRequestTraceId, pathOnly, REQUEST_METHODS, REQUEST_TRACE_WAIT_MS, resolveTarget as resolveRequestTarget, sendRequest, } from './request.js';
+import { sliceTrace } from './slices.js';
+import { summarizeTrace } from './summary.js';
+import { DESCRIPTIONS, INSTRUCTIONS } from './texts.js';
+/**
+ * The run_action description (docs/design/agent-loop.md section 3, D-119; bug-report trigger and
+ * one step per call, D-134): under 300 characters.
+ */
+export const RUN_ACTION_DESCRIPTION = "Do one step in the user's running app (click a button or link, or press Enter or Space, after filling " +
+    'fields) and return the code it ran, browser and server. Page, sign-in and data stay between calls. ' +
+    'Use it first to reproduce a reported bug step by step, and again after the fix.';
+const targetSchema = z.string().min(1).max(500).describe('button "Save", text, or css=<selector>');
+const withinSchema = z.string().min(1).max(200).describe('Text of its row or section');
+/**
+ * The app URL that run_request resolves a path against: `url` in `lightpath.config.json`, in the
+ * folder that holds the daemon's discovery file, or else in the workspace root.
+ */
+async function appUrl(dirs) {
+    for (const dir of dirs) {
+        try {
+            const raw = await readFile(join(dir, 'lightpath.config.json'), 'utf8');
+            const url = JSON.parse(raw.replace(/^\uFEFF/, '')).url;
+            if (typeof url === 'string')
+                return url;
+        }
+        catch {
+            // No config here, or not JSON.
+        }
+    }
+    return undefined;
+}
+/** run_request (design section 4A, D-125): one request on loopback, then its backend trace. */
+async function runRequest(options, found, input) {
+    const method = input.method ?? 'GET';
+    const target = await resolveRequestTarget(input.url, await appUrl([found.root, options.workspaceRoot]), options.resolver);
+    if (!target.ok)
+        return `run_request did not send anything: ${target.code}. ${target.message}`;
+    const path = pathOnly(target.url.pathname);
+    const traceId = newRequestTraceId();
+    const client = await DaemonClient.connect(found.info.port, found.info.token);
+    try {
+        // Listen before sending: the backend delta can arrive before the response does.
+        let latest;
+        let wake = () => { };
+        const off = client.onTrace((t) => {
+            if (t.id !== traceId)
+                return;
+            latest = t;
+            if (hasBackend(t))
+                wake();
+        });
+        try {
+            const sent = await sendRequest(target, input, traceId);
+            if (!sent.ok) {
+                return `run_request got no response: no_response. ${method} ${target.url.origin}${path} failed (${sent.message}). Is your server running under lightpath dev?`;
+            }
+            if (!hasBackend(latest)) {
+                await new Promise((resolve) => {
+                    const timer = setTimeout(resolve, options.requestTraceWaitMs ?? REQUEST_TRACE_WAIT_MS);
+                    wake = () => {
+                        clearTimeout(timer);
+                        resolve();
+                    };
+                });
+            }
+            const trace = hasBackend(latest) ? latest : await client.getTrace(traceId);
+            if (!trace || !hasBackend(trace)) {
+                const note = redirectNote(sent.status, loopbackLocation(sent.location, target.url));
+                return (`run_request got ${method} ${path} → ${sent.status} (${sent.bytes.toLocaleString('en-US')} bytes, ${Math.round(sent.durationMs)} ms), but no trace: no_trace. ` +
+                    "No backend lines arrived: the server isn't running under lightpath dev, or Lightpath skips this process." +
+                    (note ? `\n${note}` : ''));
+            }
+            return describeRequestResult(method, path, { ...sent, redirect: loopbackLocation(sent.location, target.url) }, trace);
+        }
+        finally {
+            off();
+        }
+    }
+    finally {
+        client.close();
+    }
+}
+/** This package's version, read from package.json next to dist/ so it can't drift. */
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+/**
+ * Every tool result goes out through here: redaction rules 2 to 5 (D-123), then the 16,000-character
+ * cap again, since a `[redacted]` can be longer than what it hides.
+ */
+const text = (t) => ({ content: [{ type: 'text', text: fitText(redact(t)) }] });
+/** Source slices only: the user's own files are never redacted (design section 9). */
+const sourceText = (t) => ({ content: [{ type: 'text', text: t }] });
+const traceIdSchema = z.string().regex(/^t_[a-z0-9]{12}$/);
+/**
+ * Builds the MCP server (docs/ARCHITECTURE.md section 9.3). Every call reads the discovery file
+ * and connects fresh, so the server works whether `lightpath dev` started before or after it.
+ */
+export function createMcpServer(options) {
+    const server = new McpServer({ name: 'lightpath', version: VERSION }, { instructions: INSTRUCTIONS });
+    const starter = new AutoStarter(resolve(options.workspaceRoot), options.autoStart);
+    /** The auto-start line, printed at the start of the next tool result (D-122). */
+    let note;
+    const ensure = async () => {
+        const live = await liveDaemon(options.workspaceRoot);
+        if (live)
+            return live;
+        if (!starter.enabled)
+            throw new Error(redact(starter.notRunning()));
+        note = starter.start();
+        const deadline = Date.now() + (options.autoStartWaitMs ?? AUTO_START_WAIT_MS);
+        while (Date.now() < deadline) {
+            await sleep(250);
+            const up = await liveDaemon(options.workspaceRoot);
+            if (up)
+                return { ...up, started: true };
+            if (starter.pid === undefined)
+                break;
+        }
+        throw new Error(redact(`${note}, but it didn't start within 60 s, or it exited. See ${DEV_LOG}.`));
+    };
+    /** Every tool result: the auto-start line first, when this call started Lightpath. */
+    const reply = (t) => {
+        const n = note;
+        note = undefined;
+        return text(n ? `${n}\n${t}` : t);
+    };
+    /** A source slice: the start line, redacted like any other, then the user's lines as they are. */
+    const sourceReply = (t) => {
+        const n = note;
+        note = undefined;
+        return sourceText(n ? `${redact(n)}\n${t}` : t);
+    };
+    const withClient = async (fn) => {
+        const { info } = await ensure();
+        const client = await DaemonClient.connect(info.port, info.token);
+        try {
+            return await fn(client);
+        }
+        finally {
+            client.close();
+        }
+    };
+    server.registerTool('run_action', {
+        description: RUN_ACTION_DESCRIPTION,
+        inputSchema: {
+            target: targetSchema,
+            within: withinSchema.optional(),
+            action: z.enum(['click', 'press']).optional().describe('Default click'),
+            key: z.enum(['Enter', 'Space']).optional().describe('With press; default Enter'),
+            timeoutMs: z.number().int().min(500).max(30_000).optional().describe('Settle cap, default 5000'),
+            fill: z
+                .array(
+            // Same forms as target and within. Bounds and descriptions aren't repeated here, to keep
+            // tools/list under 4,000 characters (D-129); the daemon checks them (400).
+            z.object({ target: z.string(), within: z.string().optional(), value: z.string() }))
+                .max(20)
+                .optional()
+                .describe('Filled first, in order; values never shown'),
+        },
+    }, async (input) => {
+        const request = { protocolVersion: PROTOCOL_VERSION, ...input };
+        const values = (input.fill ?? []).map((f) => f.value);
+        try {
+            const { info, started } = await ensure();
+            // The daemon answers after the settle cap, the backend wait (1.5 s) and the press wait (2 s).
+            const send = () => postAction(info.port, info.token, request, (input.timeoutMs ?? 5000) + 30_000);
+            let result = await send();
+            // A daemon this server just started opens its browser a little later (design section 11),
+            // and the app may still be rendering its first data then (seen in CI: the shop's product
+            // rows weren't there yet). So right after a start, `no_browser` is retried up to the
+            // start wait, and `not_found` for up to 10 s more.
+            const deadline = Date.now() + (options.autoStartWaitMs ?? AUTO_START_WAIT_MS);
+            let renderDeadline = Number.POSITIVE_INFINITY;
+            while (started && !result.ok && Date.now() < deadline) {
+                if (result.error.code === 'not_found') {
+                    if (renderDeadline === Number.POSITIVE_INFINITY)
+                        renderDeadline = Date.now() + STARTED_RENDER_WAIT_MS;
+                    if (Date.now() >= renderDeadline)
+                        break;
+                }
+                else if (result.error.code !== 'no_browser')
+                    break;
+                await sleep(500);
+                result = await send();
+            }
+            return { ...reply(describeActionResult(input, result)), ...(result.ok ? {} : { isError: true }) };
+        }
+        catch (err) {
+            return { ...reply(redactFillValues(err.message, values)), isError: true };
+        }
+    });
+    server.registerTool('run_request', {
+        description: DESCRIPTIONS.run_request,
+        inputSchema: {
+            method: z.enum(REQUEST_METHODS).optional().describe('Default GET'),
+            url: z.string().min(1).max(2000).describe('Path or loopback URL'),
+            body: z.string().max(100_000).optional().describe('Never shown back'),
+            contentType: z.string().min(1).optional(),
+            timeoutMs: z.number().int().min(500).max(30_000).optional(),
+        },
+    }, async (input) => {
+        let live;
+        try {
+            live = await ensure();
+        }
+        catch (err) {
+            return reply(`${err.message} Nothing was sent.`);
+        }
+        return reply(await runRequest(options, live, input));
+    });
+    server.registerTool('find_code_for_action', {
+        description: DESCRIPTIONS.find_code_for_action,
+        inputSchema: { action: z.string().min(1).describe('Words from the button or link label') },
+    }, async ({ action }) => {
+        const trace = await withClient(async (c) => {
+            const [match] = await c.listTraces({ label: action, limit: 1 });
+            return match ? c.getTrace(match.id) : null;
+        });
+        return reply(trace
+            ? summarizeTrace(trace)
+            : `No recorded action matches "${action}". Do it with run_action, or ask the user to click it in the app opened by \`lightpath dev\`, then try again.`);
+    });
+    server.registerTool('get_trace', {
+        description: DESCRIPTIONS.get_trace,
+        inputSchema: {
+            traceId: traceIdSchema,
+            file: z.string().min(1).optional(),
+            function: z.string().min(1).optional(),
+            page: z.number().int().min(1).optional(),
+        },
+    }, async ({ traceId, file, function: fn, page }) => {
+        const found = await withClient(async (c) => ({
+            trace: await c.getTrace(traceId),
+            roots: c.workspaceRoots,
+        }));
+        if (!found.trace)
+            return reply(`No trace ${traceId}; it may have been evicted.`);
+        if (file === undefined && fn === undefined)
+            return reply(summarizeTrace(found.trace));
+        return sourceReply(await sliceTrace(found.trace, { file, function: fn, page }, workspaceReader(found.roots)));
+    });
+    server.registerTool('list_traces', {
+        description: DESCRIPTIONS.list_traces,
+        inputSchema: {
+            label: z.string().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+    }, async ({ label, limit }) => reply(fitText(describeSummaries(await withClient((c) => c.listTraces({ limit: limit ?? 20, ...(label ? { label } : {}) }))))));
+    server.registerTool('diff_traces', {
+        description: DESCRIPTIONS.diff_traces,
+        inputSchema: { a: traceIdSchema, b: traceIdSchema },
+    }, async ({ a, b }) => {
+        const [ta, tb] = await withClient((c) => Promise.all([c.getTrace(a), c.getTrace(b)]));
+        if (!ta || !tb)
+            return reply(`Trace not found: ${[!ta && a, !tb && b].filter(Boolean).join(', ')}`);
+        // Traces from a daemon before build 2 have no function list: compare lines.
+        return reply(hasFunctions(ta) && hasFunctions(tb)
+            ? diffFunctions(ta, tb)
+            : fitText(diffTraces(ta, tb)));
+    });
+    return server;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** After an auto-start, how long run_action retries a target that isn't on the page yet. */
+const STARTED_RENDER_WAIT_MS = 10_000;
+/** The discovery file's daemon, if it is up: a stale file (a hard-killed daemon) counts as none. */
+async function liveDaemon(workspaceRoot) {
+    let found;
+    try {
+        found = await findDaemonWithRoot(workspaceRoot);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const res = await fetch(`http://127.0.0.1:${found.info.port}/v1/health`, {
+            signal: AbortSignal.timeout(1500),
+        });
+        return res.ok ? found : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function runMcpServer(options) {
+    await createMcpServer(options).connect(new StdioServerTransport());
+}
+/**
+ * Reads trace files for slices (D-117): only a workspace-relative path whose real path is inside
+ * one of the daemon's workspace roots. The daemon never reads files for clients (ARCHITECTURE 7.2).
+ */
+export function workspaceReader(roots) {
+    return async (path) => {
+        if (isAbsolute(path) || path.split(/[\\/]/).includes('..'))
+            return undefined;
+        for (const root of roots) {
+            try {
+                const realRoot = await realpath(root);
+                const real = await realpath(join(root, path));
+                const rel = relative(realRoot, real);
+                if (!rel || rel.startsWith('..') || isAbsolute(rel))
+                    continue;
+                const [text, info] = await Promise.all([readFile(real, 'utf8'), stat(real)]);
+                return { text, mtimeMs: info.mtimeMs };
+            }
+            catch {
+                // Not in this root.
+            }
+        }
+        return undefined;
+    };
+}
+async function findDaemonWithRoot(workspaceRoot) {
+    // The nearest folder at or above the root with a discovery file: editors don't always start
+    // MCP servers in the project folder itself.
+    let raw;
+    let dir = resolve(workspaceRoot);
+    for (;;) {
+        raw = await readFile(join(dir, DISCOVERY_FILE), 'utf8').catch(() => undefined);
+        const parent = dirname(dir);
+        if (raw !== undefined || parent === dir)
+            break;
+        dir = parent;
+    }
+    if (raw === undefined) {
+        throw new Error(`Lightpath isn't running in ${workspaceRoot}. Start it with: lightpath dev -- <your dev command>`);
+    }
+    return { info: DaemonDiscovery.parse(JSON.parse(raw)), root: dir };
+}
+//# sourceMappingURL=server.js.map

package/dist/slices.d.ts

@@ -0,0 +1,21 @@
+import type { Trace } from '@lightpath-dev/protocol';
+export interface SourceFile {
+    text: string;
+    mtimeMs: number;
+}
+/** Reads a trace path from the workspace, or undefined (not inside a root, missing, unreadable). */
+export type ReadSource = (path: string) => Promise<SourceFile | undefined>;
+export interface SliceQuery {
+    file?: string | undefined;
+    function?: string | undefined;
+    /** 1-based. */
+    page?: number | undefined;
+}
+/**
+ * `get_trace` with `file` or `function` (design section 6.3, D-117): the executed lines of each
+ * outermost function that ran, with numbers, merged over every phase. A run of not-run lines folds
+ * into one marker, an untaken block inside a line that ran is named after the line, lines with no
+ * coverage (blank, comments, types) are left out. Paged under 16,000 characters.
+ */
+export declare function sliceTrace(trace: Trace, query: SliceQuery, read: ReadSource): Promise<string>;
+//# sourceMappingURL=slices.d.ts.map