@lightpath-dev/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightpath contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @lightpath-dev/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server of [Lightpath](https://github.com/Unknown-333/Lightpath#readme), so coding agents can ask which code ran for an action you just did in your app.
+
+Run it with `npx -y @lightpath-dev/cli mcp`. Setup for Claude Code, Cursor, VS Code, and Kiro: [Ask your coding agent](https://github.com/Unknown-333/Lightpath#ask-your-coding-agent).

package/dist/autostart.d.ts

@@ -0,0 +1,33 @@
+/** What `lightpath mcp` knows to start Lightpath by itself (D-122), from the CLI and the config. */
+export interface AutoStartOptions {
+    /** The CLI's `bin.js`, run with this Node as `dev --headless`. */
+    bin: string;
+    /** `command` from lightpath.config.json in the server's root, if any. */
+    command?: string | string[] | undefined;
+    /** `autoStart` from that config: only `true` starts anything. */
+    autoStart?: boolean | undefined;
+}
+/** Longest wait for the started daemon, and for run_action, its browser (design section 11). */
+export declare const AUTO_START_WAIT_MS = 60000;
+export declare const DEV_LOG = ".lightpath/dev.log";
+export declare const commandText: (c: string | string[]) => string;
+/**
+ * Starts `lightpath dev --headless` once, as a child of this MCP server, with its output appended
+ * to `.lightpath/dev.log`. The child doesn't hold this process open, and its whole tree is stopped
+ * when this process exits. A hard kill of this process leaves it running; its discovery file
+ * then lets the next MCP server reuse it.
+ */
+export declare class AutoStarter {
+    #private;
+    constructor(root: string, opts: AutoStartOptions | undefined);
+    /** True when the config allows a start: `command` and `autoStart: true`. */
+    get enabled(): boolean;
+    get pid(): number | undefined;
+    /** The message for a tool when Lightpath isn't running and nothing may start it. */
+    notRunning(): string;
+    /** Starts the child if it isn't running. Returns the line a tool result starts with. */
+    start(): string;
+    /** Stops the child and its whole tree. Synchronous, so it can run in an `exit` handler. */
+    stop(): void;
+}
+//# sourceMappingURL=autostart.d.ts.map

package/dist/autostart.js

@@ -0,0 +1,79 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { closeSync, mkdirSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+/** Longest wait for the started daemon, and for run_action, its browser (design section 11). */
+export const AUTO_START_WAIT_MS = 60_000;
+export const DEV_LOG = '.lightpath/dev.log';
+export const commandText = (c) => (typeof c === 'string' ? c : c.join(' '));
+/**
+ * Starts `lightpath dev --headless` once, as a child of this MCP server, with its output appended
+ * to `.lightpath/dev.log`. The child doesn't hold this process open, and its whole tree is stopped
+ * when this process exits. A hard kill of this process leaves it running; its discovery file
+ * then lets the next MCP server reuse it.
+ */
+export class AutoStarter {
+    #root;
+    #opts;
+    #child;
+    constructor(root, opts) {
+        this.#root = root;
+        this.#opts = opts;
+    }
+    /** True when the config allows a start: `command` and `autoStart: true`. */
+    get enabled() {
+        return Boolean(this.#opts?.autoStart && this.#opts.command && this.#opts.bin);
+    }
+    get pid() {
+        return this.#child?.exitCode === null ? this.#child.pid : undefined;
+    }
+    /** The message for a tool when Lightpath isn't running and nothing may start it. */
+    notRunning() {
+        const cmd = this.#opts?.command;
+        if (cmd) {
+            return (`Lightpath isn't running in ${this.#root}. Start it with: lightpath dev (it runs "${commandText(cmd)}" from lightpath.config.json). ` +
+                'To let tools start it by themselves, set "autoStart": true in lightpath.config.json.');
+        }
+        return `Lightpath isn't running in ${this.#root}. Start it with: lightpath dev -- <your dev command>`;
+    }
+    /** Starts the child if it isn't running. Returns the line a tool result starts with. */
+    start() {
+        const opts = this.#opts;
+        const note = `started lightpath dev ("${commandText(opts.command)}") in the background; log: ${DEV_LOG}`;
+        if (this.pid !== undefined)
+            return note;
+        mkdirSync(join(this.#root, '.lightpath'), { recursive: true });
+        const log = openSync(join(this.#root, DEV_LOG), 'a');
+        try {
+            this.#child = spawn(process.execPath, [opts.bin, 'dev', '--headless'], {
+                cwd: this.#root,
+                stdio: ['ignore', log, log],
+                // On POSIX a process group, so the dev command's own children stop with it.
+                detached: process.platform !== 'win32',
+                windowsHide: true,
+            });
+        }
+        finally {
+            closeSync(log);
+        }
+        this.#child.unref();
+        process.once('exit', () => this.stop());
+        return note;
+    }
+    /** Stops the child and its whole tree. Synchronous, so it can run in an `exit` handler. */
+    stop() {
+        const pid = this.pid;
+        this.#child = undefined;
+        if (pid === undefined)
+            return;
+        try {
+            if (process.platform === 'win32')
+                execFileSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+            else
+                process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+//# sourceMappingURL=autostart.js.map

package/dist/budget.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Every tool result is at most 16,000 characters: the 4,000-token budget N at 4 characters a token
+ * (D-109). Every tool's text goes through `fit()` or `fitText()` (design section 6.2).
+ */
+export declare const MAX_CHARS = 16000;
+/** One file's lines inside one phase of a summary. */
+export interface FileBlock {
+    path: string;
+    lines: string[];
+    functions: number;
+}
+export interface SummaryParts {
+    traceId: string;
+    /** Always printed: trace, action, page, requests. */
+    header: string[];
+    sections: {
+        title: string;
+        files: FileBlock[];
+    }[];
+    /** Printed after the sections (the "hidden:" line). */
+    footer: string[];
+    /** Rank of a file, across all its phases: higher stays longer. */
+    rank: (path: string) => {
+        background: boolean;
+        hits: number;
+    };
+}
+/**
+ * The summary as text, within MAX_CHARS. When the whole text doesn't fit, drops whole files,
+ * lowest rank first (background before foreground, then fewest hits), from every phase at once,
+ * and ends with one line saying what was cut and how to see it.
+ */
+export declare function fit(parts: SummaryParts, max?: number): string;
+/**
+ * The last guard for any tool's text: cuts at a line boundary under `max` and says so. The cut
+ * line names the call that shows the rest when there is one.
+ */
+export declare function fitText(text: string, max?: number, traceId?: string): string;
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.js

@@ -0,0 +1,77 @@
+/**
+ * Every tool result is at most 16,000 characters: the 4,000-token budget N at 4 characters a token
+ * (D-109). Every tool's text goes through `fit()` or `fitText()` (design section 6.2).
+ */
+export const MAX_CHARS = 16_000;
+const size = (lines) => lines.reduce((n, l) => n + l.length + 1, 0);
+function render(parts, keep) {
+    const out = [...parts.header];
+    for (const s of parts.sections) {
+        out.push(s.title);
+        for (const f of s.files)
+            if (keep(f.path))
+                out.push(...f.lines);
+    }
+    out.push(...parts.footer);
+    return out.join('\n');
+}
+/**
+ * The summary as text, within MAX_CHARS. When the whole text doesn't fit, drops whole files,
+ * lowest rank first (background before foreground, then fewest hits), from every phase at once,
+ * and ends with one line saying what was cut and how to see it.
+ */
+export function fit(parts, max = MAX_CHARS) {
+    const full = render(parts, () => true);
+    if (full.length <= max)
+        return full;
+    const bytes = new Map();
+    const fns = new Map();
+    for (const s of parts.sections) {
+        for (const f of s.files) {
+            bytes.set(f.path, (bytes.get(f.path) ?? 0) + size(f.lines));
+            fns.set(f.path, (fns.get(f.path) ?? 0) + f.functions);
+        }
+    }
+    // Lowest rank first.
+    const order = [...bytes.keys()].sort((a, b) => {
+        const ra = parts.rank(a);
+        const rb = parts.rank(b);
+        if (ra.background !== rb.background)
+            return ra.background ? -1 : 1;
+        return ra.hits - rb.hits || b.localeCompare(a);
+    });
+    const dropped = new Set();
+    let length = full.length;
+    let droppedChars = 0;
+    const cut = () => {
+        const top = [...dropped].at(-1) ?? '';
+        const n = dropped.size;
+        const m = [...dropped].reduce((sum, p) => sum + (fns.get(p) ?? 0), 0);
+        return (`not shown: ${n} file${n === 1 ? '' : 's'}, ${m} function${m === 1 ? '' : 's'} ` +
+            `(${droppedChars.toLocaleString('en-US')} chars). Call get_trace with traceId "${parts.traceId}" and file "${top}" to see one.`);
+    };
+    for (const path of order) {
+        if (length + 1 + cut().length <= max)
+            break;
+        dropped.add(path);
+        const b = bytes.get(path) ?? 0;
+        length -= b;
+        droppedChars += b;
+    }
+    return fitText(`${render(parts, (p) => !dropped.has(p))}\n${cut()}`, max, parts.traceId);
+}
+/**
+ * The last guard for any tool's text: cuts at a line boundary under `max` and says so. The cut
+ * line names the call that shows the rest when there is one.
+ */
+export function fitText(text, max = MAX_CHARS, traceId) {
+    if (text.length <= max)
+        return text;
+    const tail = traceId
+        ? `not shown: the rest (${(text.length).toLocaleString('en-US')} chars in all). Call get_trace with traceId "${traceId}" and a file or function to see one part.`
+        : `not shown: the rest (${(text.length).toLocaleString('en-US')} chars in all).`;
+    const room = max - tail.length - 1;
+    const at = text.lastIndexOf('\n', room);
+    return `${text.slice(0, at > 0 ? at : room)}\n${tail}`;
+}
+//# sourceMappingURL=budget.js.map

package/dist/diff.d.ts

@@ -0,0 +1,11 @@
+import type { Trace } from '@lightpath-dev/protocol';
+/** True when both traces carry function lists, so the function-level diff applies. */
+export declare function hasFunctions(t: Trace): boolean;
+/**
+ * `diff_traces` at function level (design section 6.4, D-118), in this order: requests whose
+ * status changed, functions that ran in only one trace, functions whose not-run lines changed
+ * (each side in its own line numbers), and functions whose call count changed. Problems join in
+ * build 4, when traces carry them.
+ */
+export declare function diffFunctions(a: Trace, b: Trace): string;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.js

@@ -0,0 +1,126 @@
+import { fitText } from './budget.js';
+import { errorsOf, failedRequestsOf, functionName, numberRanges, problemText } from './summary.js';
+/**
+ * Functions of one trace merged over phases and keyed by file, name and order among functions
+ * of that name in the file. Line numbers aren't in the key: a fix moves them (D-118).
+ */
+function functionsOf(trace) {
+    const byFn = new Map();
+    for (const f of trace.functions ?? []) {
+        const id = `${f.path}|${f.name}|${f.startLine}`;
+        const m = byFn.get(id);
+        if (m) {
+            m.count += f.count;
+            // Not run in every phase that ran it.
+            const mine = new Set((f.notRun ?? []).map((l) => l - f.startLine));
+            for (const o of m.notRun)
+                if (!mine.has(o))
+                    m.notRun.delete(o);
+        }
+        else {
+            byFn.set(id, {
+                path: f.path,
+                name: f.name,
+                startLine: f.startLine,
+                endLine: f.endLine,
+                count: f.count,
+                notRun: new Set((f.notRun ?? []).map((l) => l - f.startLine)),
+            });
+        }
+    }
+    const out = new Map();
+    const seen = new Map();
+    for (const m of [...byFn.values()].sort((a, b) => a.path.localeCompare(b.path) || a.startLine - b.startLine)) {
+        const base = `${m.path}|${m.name}`;
+        const n = seen.get(base) ?? 0;
+        seen.set(base, n + 1);
+        out.set(`${base}#${n}`, m);
+    }
+    return out;
+}
+const where = (m) => `${m.path} ${functionName(m)} (line ${m.startLine})`;
+const lines = (m, offsets) => numberRanges([...offsets].map((o) => o + m.startLine));
+/** True when both traces carry function lists, so the function-level diff applies. */
+export function hasFunctions(t) {
+    return t.functions !== undefined;
+}
+/**
+ * `diff_traces` at function level (design section 6.4, D-118), in this order: requests whose
+ * status changed, functions that ran in only one trace, functions whose not-run lines changed
+ * (each side in its own line numbers), and functions whose call count changed. Problems join in
+ * build 4, when traces carry them.
+ */
+export function diffFunctions(a, b) {
+    const out = [`Trace ${a.id} (${a.label}) → ${b.id} (${b.label}):`];
+    // Problems first (design 6.4): counts, and the first error that appeared or went away.
+    const ea = errorsOf(a);
+    const eb = errorsOf(b);
+    const fa0 = failedRequestsOf(a);
+    const fb0 = failedRequestsOf(b);
+    if (ea.total !== eb.total || fa0.join() !== fb0.join()) {
+        out.push(`problems: errors ${ea.total} → ${eb.total}, failed requests ${fa0.length} → ${fb0.length}`);
+        const msgs = (l) => new Set(l.map((p) => problemText(p)));
+        const ma = msgs(ea.list);
+        const mb = msgs(eb.list);
+        const gone = [...ma].find((m) => !mb.has(m));
+        const came = [...mb].find((m) => !ma.has(m));
+        if (gone)
+            out.push(`  went away: ${gone}`);
+        if (came)
+            out.push(`  appeared: ${came}`);
+    }
+    // Requests matched by method and path, in order.
+    const statuses = [];
+    const used = new Set();
+    for (const ra of a.requests) {
+        const j = b.requests.findIndex((rb, k) => !used.has(k) && rb.method === ra.method && rb.path === ra.path);
+        if (j < 0) {
+            statuses.push(`  ${ra.method} ${ra.path} ${ra.status ?? '?'} → not sent`);
+            continue;
+        }
+        used.add(j);
+        const rb = b.requests[j];
+        if (rb && rb.status !== ra.status)
+            statuses.push(`  ${ra.method} ${ra.path} ${ra.status ?? '?'} → ${rb.status ?? '?'}`);
+    }
+    for (const [k, rb] of b.requests.entries())
+        if (!used.has(k))
+            statuses.push(`  ${rb.method} ${rb.path} newly sent → ${rb.status ?? '?'}`);
+    if (statuses.length)
+        out.push('requests:', ...statuses);
+    const fa = functionsOf(a);
+    const fb = functionsOf(b);
+    const onlyA = [...fa].filter(([k]) => !fb.has(k)).map(([, m]) => `  ${where(m)} ×${m.count}`);
+    const onlyB = [...fb].filter(([k]) => !fa.has(k)).map(([, m]) => `  ${where(m)} ×${m.count}`);
+    if (onlyA.length)
+        out.push(`ran only in ${a.id}:`, ...onlyA);
+    if (onlyB.length)
+        out.push(`ran only in ${b.id}:`, ...onlyB);
+    const branches = [];
+    const counts = [];
+    for (const [k, ma] of fa) {
+        const mb = fb.get(k);
+        if (!mb)
+            continue;
+        const nowRuns = [...ma.notRun].filter((o) => !mb.notRun.has(o));
+        const noLonger = [...mb.notRun].filter((o) => !ma.notRun.has(o));
+        if (nowRuns.length || noLonger.length) {
+            const parts = [
+                ...(nowRuns.length ? [`now runs ${lines(ma, nowRuns)}`] : []),
+                ...(noLonger.length ? [`no longer runs ${lines(mb, noLonger)}`] : []),
+            ];
+            const shift = mb.startLine !== ma.startLine ? ` (line ${ma.startLine} → ${mb.startLine})` : '';
+            branches.push(`  ${ma.path} ${functionName(ma)}${shift}: ${parts.join('; ')}`);
+        }
+        if (ma.count !== mb.count)
+            counts.push(`  ${where(ma)}: ×${ma.count} → ×${mb.count}`);
+    }
+    if (branches.length)
+        out.push('branches changed (each side in its own line numbers):', ...branches);
+    if (counts.length)
+        out.push('call counts changed:', ...counts);
+    if (out.length === 1)
+        out.push('none: both traces ran the same functions and branches');
+    return fitText(out.join('\n'));
+}
+//# sourceMappingURL=diff.js.map

package/dist/format.d.ts

@@ -0,0 +1,33 @@
+import type { ActionRequest, ActionResult, LineHit, Trace, TraceSummary } from '@lightpath-dev/protocol';
+/** Compresses sorted line numbers into ranges: [1,2,3,7,9,10] → "1-3, 7, 9-10". */
+export declare function lineRanges(lines: readonly LineHit[]): string;
+/** A compact, agent-readable description of one trace. */
+export declare function describeTrace(trace: Trace): string;
+export declare function describeSummaries(traces: readonly TraceSummary[]): string;
+/** Lines that ran in only one of two traces, per file. */
+export declare function diffTraces(a: Trace, b: Trace): string;
+type ActionInput = Pick<ActionRequest, 'target' | 'within' | 'action' | 'key' | 'fill'>;
+/** `click button "Checkout"`, `press Enter on textbox "Search" within "Header"`. */
+export declare function describeAction(input: ActionInput): string;
+/**
+ * run_action's answer (design section 4.5): the trace's first line, the action and page lines,
+ * warnings, then the summary by phase (section 6.1). On failure, the outcome and the candidates.
+ * Every fill value in the text is redacted (rule 6). itText runs again after redaction, which can lengthen
+ * the text.
+ */
+export declare function describeActionResult(input: ActionInput, result: ActionResult): string;
+/**
+ * run_request's answer (design section 4A): one `sent:` line with the method, the path (never the
+ * query), status, response size and time, then the backend trace summary. The request body, its
+ * headers and the response's body and headers never appear.
+ */
+export declare function describeRequestResult(method: string, path: string, sent: {
+    status: number;
+    bytes: number;
+    durationMs: number;
+    redirect?: string | undefined;
+}, trace: Trace): string;
+/** For a 3xx: that it wasn't followed, and where it points when that is loopback. */
+export declare function redirectNote(status: number, loopbackTarget: string | undefined): string | undefined;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,118 @@
+import { fitText, MAX_CHARS } from './budget.js';
+import { redactFillValues } from './redact.js';
+import { summarizeTrace } from './summary.js';
+/** Compresses sorted line numbers into ranges: [1,2,3,7,9,10] → "1-3, 7, 9-10". */
+export function lineRanges(lines) {
+    const parts = [];
+    let start;
+    let prev;
+    for (const { line } of lines) {
+        if (start === undefined)
+            start = line;
+        else if (prev !== undefined && line !== prev + 1) {
+            parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+            start = line;
+        }
+        prev = line;
+    }
+    if (start !== undefined && prev !== undefined)
+        parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+    return parts.join(', ');
+}
+/** A compact, agent-readable description of one trace. */
+export function describeTrace(trace) {
+    const out = [`Trace ${trace.id}: ${trace.label}`];
+    for (const r of trace.requests) {
+        out.push(`  request: ${r.method} ${r.path}${r.status ? ` → ${r.status}` : ''} (${r.collector}, ${Math.round(r.durationMs)} ms${r.overlapped ? ', overlapped with another request' : ''})`);
+    }
+    if (trace.files.length === 0)
+        out.push('  no workspace code ran');
+    for (const f of trace.files) {
+        const hottest = Math.max(...f.lines.map((l) => l.count));
+        const bg = f.background ? ' (background: only code that also runs while idle, likely unrelated)' : '';
+        out.push(`  ${f.path} [${f.collector}] lines ${lineRanges(f.lines)}${hottest > 1 ? ` (max ${hottest} hits)` : ''}${bg}`);
+    }
+    const dropped = trace.dropped.filter((d) => d.count > 0);
+    if (dropped.length > 0)
+        out.push(`  not shown: ${dropped.map((d) => `${d.count} ${d.reason}`).join(', ')}`);
+    return out.join('\n');
+}
+export function describeSummaries(traces) {
+    if (traces.length === 0)
+        return 'No traces yet. Click something in the app opened by `lightpath dev`.';
+    return traces
+        .map((t) => `${t.id}  ${new Date(t.startedAt).toISOString()}  ${t.label}  (${t.fileCount} files${t.problemCount ? `, ${t.problemCount} problem${t.problemCount === 1 ? '' : 's'}` : ''})`)
+        .join('\n');
+}
+/** Lines that ran in only one of two traces, per file. */
+export function diffTraces(a, b) {
+    const index = (t) => new Map(t.files.map((f) => [f.path, new Set(f.lines.map((l) => l.line))]));
+    const ia = index(a);
+    const ib = index(b);
+    const out = [`Lines that ran in only one of ${a.id} (${a.label}) and ${b.id} (${b.label}):`];
+    for (const path of [...new Set([...ia.keys(), ...ib.keys()])].sort()) {
+        const la = ia.get(path) ?? new Set();
+        const lb = ib.get(path) ?? new Set();
+        const onlyA = [...la].filter((l) => !lb.has(l)).sort((x, y) => x - y);
+        const onlyB = [...lb].filter((l) => !la.has(l)).sort((x, y) => x - y);
+        const fmt = (ls) => lineRanges(ls.map((line) => ({ line, count: 1 })));
+        if (onlyA.length)
+            out.push(`  ${path}: only in A: ${fmt(onlyA)}`);
+        if (onlyB.length)
+            out.push(`  ${path}: only in B: ${fmt(onlyB)}`);
+    }
+    return out.length === 1 ? `${out[0]}\n  none, both traces ran the same lines` : out.join('\n');
+}
+/** `click button "Checkout"`, `press Enter on textbox "Search" within "Header"`. */
+export function describeAction(input) {
+    const where = `${input.target}${input.within ? ` within "${input.within}"` : ''}`;
+    const verb = input.action === 'press' ? `press ${input.key ?? 'Enter'} on ${where}` : `click ${where}`;
+    const n = input.fill?.length ?? 0;
+    return n > 0 ? `${verb}, after filling ${n} field${n === 1 ? '' : 's'}` : verb;
+}
+/**
+ * run_action's answer (design section 4.5): the trace's first line, the action and page lines,
+ * warnings, then the summary by phase (section 6.1). On failure, the outcome and the candidates.
+ * Every fill value in the text is redacted (rule 6). itText runs again after redaction, which can lengthen
+ * the text.
+ */
+export function describeActionResult(input, result) {
+    const values = (input.fill ?? []).map((f) => f.value);
+    if (!result.ok) {
+        const { error } = result;
+        const out = [`run_action did not record a trace: ${error.code}. ${error.message}`];
+        if (error.candidates?.length) {
+            out.push(error.code === 'ambiguous' ? 'Matches:' : 'Closest targets on the page:');
+            for (const c of error.candidates)
+                out.push(`  ${c}`);
+        }
+        return redactFillValues(out.join('\n'), values);
+    }
+    const text = summarizeTrace(result.trace, [
+        `action: ${describeAction(input)} (boundary ${result.boundary}, settled ${result.settled})`,
+        `page: ${result.pageUrl}`,
+        ...result.warnings.map((w) => `warning (${w.code}): ${w.message}`),
+    ]);
+    return fitText(redactFillValues(text, values), MAX_CHARS, result.trace.id);
+}
+/**
+ * run_request's answer (design section 4A): one `sent:` line with the method, the path (never the
+ * query), status, response size and time, then the backend trace summary. The request body, its
+ * headers and the response's body and headers never appear.
+ */
+export function describeRequestResult(method, path, sent, trace) {
+    const lines = [
+        `sent: ${method} ${path} → ${sent.status} (${sent.bytes.toLocaleString('en-US')} bytes, ${Math.round(sent.durationMs)} ms)`,
+    ];
+    const note = redirectNote(sent.status, sent.redirect);
+    if (note)
+        lines.push(note);
+    return fitText(summarizeTrace(trace, lines), MAX_CHARS, trace.id);
+}
+/** For a 3xx: that it wasn't followed, and where it points when that is loopback. */
+export function redirectNote(status, loopbackTarget) {
+    if (status < 300 || status >= 400)
+        return undefined;
+    return `redirect not followed${loopbackTarget ? `: it points to ${loopbackTarget}` : ' (it points off loopback, or nowhere)'}`;
+}
+//# sourceMappingURL=format.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { fit, fitText, MAX_CHARS } from './budget.js';
+export { diffFunctions } from './diff.js';
+export { describeAction, describeActionResult, describeSummaries, describeTrace, diffTraces, lineRanges, } from './format.js';
+export { MIN_SECRET_LENGTH, redact, redactFillValues } from './redact.js';
+export { isLoopbackAddress, resolveTarget as resolveRequestTarget } from './request.js';
+export { createMcpServer, type McpOptions, RUN_ACTION_DESCRIPTION, runMcpServer } from './server.js';
+export { sliceTrace } from './slices.js';
+export { summarizeTrace } from './summary.js';
+export { DESCRIPTIONS, INSTRUCTIONS } from './texts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,10 @@
+export { fit, fitText, MAX_CHARS } from './budget.js';
+export { diffFunctions } from './diff.js';
+export { describeAction, describeActionResult, describeSummaries, describeTrace, diffTraces, lineRanges, } from './format.js';
+export { MIN_SECRET_LENGTH, redact, redactFillValues } from './redact.js';
+export { isLoopbackAddress, resolveTarget as resolveRequestTarget } from './request.js';
+export { createMcpServer, RUN_ACTION_DESCRIPTION, runMcpServer } from './server.js';
+export { sliceTrace } from './slices.js';
+export { summarizeTrace } from './summary.js';
+export { DESCRIPTIONS, INSTRUCTIONS } from './texts.js';
+//# sourceMappingURL=index.js.map

package/dist/redact.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Redaction rules 2 to 5 (D-123, design section 9), for every runtime string a tool prints:
+ * problem messages, request paths and URLs, the page URL, labels. Never for source slices.
+ * Rules 2 and 5 over-redact on purpose (`monkey=1`): a missed secret is worse.
+ */
+export declare function redact(text: string): string;
+/** Shortest `fill` value that is redacted; shorter ones would hide ordinary words and numbers. */
+export declare const MIN_SECRET_LENGTH = 4;
+/**
+ * Redaction rule 6 (D-123, design section 9): every occurrence of a value run_action filled in this
+ * call, 4 characters or longer, becomes `[redacted]` in the result text. Rules 2 to 5 come with
+ * build 4.
+ */
+export declare function redactFillValues(text: string, values: readonly string[]): string;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.js

@@ -0,0 +1,41 @@
+const WORDS = 'token|key|secret|pass|auth|session|sig';
+const R = '[redacted]';
+/** Rule 2: URL query values whose name holds a secret word, any case. */
+const QUERY = new RegExp(`([?&][^=&#\\s]*(?:${WORDS})[^=&#\\s]*=)([^&#\\s]*)`, 'gi');
+/** Rule 3: bearer tokens. */
+const BEARER = /\b(Bearer\s+)(?!\[redacted\])[^\s"',;]+/gi;
+/** Rule 4: JWT-like strings, three base64url parts, the first starting `eyJ`. */
+const JWT = /\beyJ[\w-]*\.[\w-]+\.[\w-]+/g;
+/** Rule 5: `key=value` and `key: value` (quoted or not) whose key holds a secret word. */
+const PAIR = new RegExp(`(["']?)([\\w.-]*(?:${WORDS})[\\w.-]*)\\1(\\s*[:=]\\s*)(["']?)(?!\\[redacted\\])([^\\s"'&,;)}\\]]+)\\4`, 'gi');
+/**
+ * Redaction rules 2 to 5 (D-123, design section 9), for every runtime string a tool prints:
+ * problem messages, request paths and URLs, the page URL, labels. Never for source slices.
+ * Rules 2 and 5 over-redact on purpose (`monkey=1`): a missed secret is worse.
+ */
+export function redact(text) {
+    return text
+        .replace(JWT, R)
+        .replace(BEARER, `$1${R}`)
+        .replace(QUERY, `$1${R}`)
+        .replace(PAIR, (_m, q, key, sep, vq) => `${q}${key}${q}${sep}${vq}${R}${vq}`);
+}
+/** Shortest `fill` value that is redacted; shorter ones would hide ordinary words and numbers. */
+export const MIN_SECRET_LENGTH = 4;
+/**
+ * Redaction rule 6 (D-123, design section 9): every occurrence of a value run_action filled in this
+ * call, 4 characters or longer, becomes `[redacted]` in the result text. Rules 2 to 5 come with
+ * build 4.
+ */
+export function redactFillValues(text, values) {
+    // A value the app put in a URL appears percent-encoded there ('my pass' as 'my%20pass').
+    const forms = values
+        .filter((v) => v.length >= MIN_SECRET_LENGTH)
+        .flatMap((v) => [v, encodeURIComponent(v)]);
+    const secrets = [...new Set(forms)].sort((a, b) => b.length - a.length);
+    let out = text;
+    for (const s of secrets)
+        out = out.split(s).join('[redacted]');
+    return out;
+}
+//# sourceMappingURL=redact.js.map