@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/tools/file-tools.js

@@ -1,13 +1,42 @@
+/**
+ * file-tools - Pugi CLI file/bash/glob/grep tool surface.
+ *
+ * Workspace-binding contract (CEO red-alert follow-up):
+ *
+ *  Every tool dispatch path threads `ctx.root` from the operator's
+ *  `process.cwd()` through `EngineTask.workspaceRoot` ->
+ *  `native-pugi.run()` -> `toolCtx.root` -> here. Tools call
+ *  `resolveWorkspacePath(ctx.root, path)` for every on-disk operation
+ *  so a dispatched specialist (e.g. Hiroshi writing tic-tac-toe HTML)
+ *  produces files in the OPERATOR'S cwd, never in a server-side temp
+ *  space. The path-security gate refuses traversal (`../etc/passwd`,
+ *  URL-encoded variants, symlink escapes at the target).
+ *
+ *  Wiring chain:
+ *    1. runtime/cli.ts:   workspaceRoot = process.cwd()
+ *    2. EngineTask.workspaceRoot threads through to native-pugi.run().
+ *    3. native-pugi:      const root = task.workspaceRoot
+ *    4. tool-bridge:      passes ctx.root to file-tools / bash.
+ *    5. file-tools:       resolveWorkspacePath(ctx.root, path).
+ *
+ *  The contract is locked by `test/tools-write-to-workspace.spec.ts`
+ *  (6 cases covering relative + nested + absolute paths + traversal
+ *  refusal). If any layer of the chain regressed silently, dispatched
+ *  files would land in `/tmp` instead of the operator's repo, which
+ *  is the same failure surface as the menu-mode anti-pattern the
+ *  sibling commits close.
+ */
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, relative } from 'node:path';
 import { globSync } from 'node:fs';
 import { decidePermission } from '../core/permission.js';
-import { createReadRecord, hashContent } from '../core/file-cache.js';
+import { StaleReadError, createReadRecord, hashContent, } from '../core/file-cache.js';
 import { resolveWorkspacePath } from '../core/path-security.js';
+import { scanForInjection, summarizeFindings } from '../core/security/injection-scanner.js';
 import { recordFileMutation, recordToolCall, recordToolResult } from '../core/session.js';
 /**
- * α6.9 WriteGate marker — thrown by `gateOnCancellation` when the
+ * WriteGate marker — thrown by `gateOnCancellation` when the
  * caller supplied a cancellation token that has already aborted. The
  * tool dispatch loop in `tool-bridge.ts` recognises the name and folds
  * the throw into a `status: 'aborted'` tool result rather than a hard
@@ -19,8 +48,13 @@ export class OperatorAbortedError extends Error {
         this.name = 'OperatorAbortedError';
     }
 }
+// Re-export StaleReadError so tool-bridge / test consumers can import
+// the typed error from a single file-tools surface alongside
+// OperatorAbortedError. Same shape as the existing OperatorAbortedError
+// re-surface pattern.
+export { StaleReadError } from '../core/file-cache.js';
 /**
- * α6.9 WriteGate: refuse the tool dispatch when the active
+ * WriteGate: refuse the tool dispatch when the active
  * cancellation token has aborted. Idempotent (the token's `isAborted`
  * is a getter, no side effects). Returns void on the happy path so the
  * tool can proceed; throws `OperatorAbortedError` when cancelled.
@@ -71,7 +105,7 @@ function permissionGatedResolve(ctx, inputPath, action, toolName) {
 }
 export function readTool(ctx, path) {
     const toolCallId = recordToolCall(ctx.session, 'read', path);
-    // α6.9 WriteGate: fail fast on operator cancel BEFORE permission
+    // WriteGate: fail fast on operator cancel BEFORE permission
     // decision so a half-second post-cancel race never lands the read.
     if (ctx.cancellation && ctx.cancellation.isAborted) {
         const reason = 'operator_aborted: read refused';
@@ -100,7 +134,7 @@ export function readTool(ctx, path) {
 }
 export function writeTool(ctx, path, content) {
     const toolCallId = recordToolCall(ctx.session, 'write', path);
-    // α6.9 WriteGate: refuse the write when the operator has cancelled
+    // WriteGate: refuse the write when the operator has cancelled
     // the dispatch. The audit log captures the cancellation reason so a
     // post-mortem can distinguish operator_aborted from settings-deny.
     if (ctx.cancellation && ctx.cancellation.isAborted) {
@@ -124,10 +158,45 @@ export function writeTool(ctx, path, content) {
         throw error;
     }
     const existed = existsSync(resolved);
-    const before = existed ? readFileSync(resolved, 'utf8') : undefined;
+    // stale-read gate for writeTool's update-existing path. The
+    // model uses writeTool for two distinct intents:
+    //
+    //  - create-new: path does not exist on disk. There is no prior
+    //    read to validate against; skip the gate. This is the
+    //    intentional escape hatch the leak spec also calls out.
+    //  - overwrite-existing: path exists. Without the gate the model
+    //    could blind-clobber an externally-modified file, losing the
+    //    concurrent change silently. Force the model to re-read first.
+    //
+    // We deliberately apply the SAME stale-validation primitive editTool
+    // uses so the two write surfaces stay symmetric and a future fix to
+    // either one cannot accidentally weaken the other.
+    let before;
+    if (existed) {
+        before = readFileSync(resolved, 'utf8');
+        const currentStat = statSync(resolved);
+        const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
+        if (validation.stale) {
+            const reason = `stale_read: write ${path} refused — ${validation.detail}`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            throw new StaleReadError(path, validation.reason, validation.detail);
+        }
+    }
     const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
     writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o600 });
     renameSync(tmp, resolved);
+    // Injection scan (ported an external utility,
+    // Apache-2.0). Scan the BODY (never the path — path security is
+    // owned by `path-security.ts`). Findings are SURFACED as an extra
+    // line on the session tool-result, never block the write. Hard-
+    // block requires a separate CEO-signed PR. Failure here must NOT
+    // throw: a buggy scanner cannot rugpull the write that already
+    // landed on disk above.
+    surfaceInjectionWarning(ctx, toolCallId, 'write', path, content);
+    // Refresh the cache with the post-write content so the model can
+    // chain a follow-up read+edit on the same file without an extra
+    // round-trip. Same pattern editTool uses below.
+    ctx.readCache.set(createReadRecord(ctx.root, path, content, 'read_tool'));
     recordFileMutation(ctx.session, {
         toolCallId,
         path,
@@ -137,9 +206,39 @@ export function writeTool(ctx, path, content) {
     });
     recordToolResult(ctx.session, toolCallId, 'success', `${existed ? 'Updated' : 'Created'} ${path}`);
 }
+/**
+ * Surface an injection-scan warning on a file write/edit BODY. The
+ * scan never blocks — it folds findings into the session as a
+ * `tool_result` with status `warn` so an operator (or SOC pipeline
+ * tailing `<workspace>/.pugi/events.jsonl`) sees the signal without a
+ * mid-dispatch rollback.
+ *
+ * Wrapped in try/catch so a malformed scanner never crashes the tool
+ * loop — the write itself has already landed on disk by the time we
+ * call this.
+ */
+function surfaceInjectionWarning(ctx, triggeringToolCallId, tool, path, body) {
+    try {
+        const findings = scanForInjection(body);
+        if (findings.length === 0)
+            return;
+        const summary = summarizeFindings(findings);
+        const warnCallId = recordToolCall(ctx.session, 'injection_warning', path);
+        const message = `injection_warning: ${tool} ${path} — ${summary.total} pattern(s) ` +
+            `(score=${summary.score}, kinds=${summary.kinds.join('|')}). ` +
+            `Triggering call: ${triggeringToolCallId}. ` +
+            `Detector: external-injection-patterns. Write was NOT blocked.`;
+        recordToolResult(ctx.session, warnCallId, 'success', message);
+    }
+    catch {
+        // Scanner failure must NEVER throw — the write has already
+        // landed and the tool loop has to continue. Silent no-op
+        // mirrors the audit-trail contract.
+    }
+}
 export function editTool(ctx, path, oldString, newString) {
     const toolCallId = recordToolCall(ctx.session, 'edit', path);
-    // α6.9 WriteGate: refuse the edit when the operator has cancelled
+    // WriteGate: refuse the edit when the operator has cancelled
     // the dispatch. Edits are higher-risk than reads — surface the abort
     // BEFORE we even consult permissions so a cancel-during-tool-loop
     // never partially mutates the workspace.
@@ -154,10 +253,6 @@ export function editTool(ctx, path, oldString, newString) {
         recordToolResult(ctx.session, toolCallId, 'error', reason);
         throw new Error(reason);
     }
-    const readRecord = ctx.readCache.get(ctx.root, path);
-    if (!readRecord) {
-        throw new Error(`Cannot edit ${path}: file must be read first`);
-    }
     let resolved;
     try {
         resolved = permissionGatedResolve(ctx, path, 'edit', 'edit');
@@ -167,20 +262,42 @@ export function editTool(ctx, path, oldString, newString) {
         recordToolResult(ctx.session, toolCallId, 'error', reason);
         throw error;
     }
+    // stale-read gate. Validate the model's read-time view of
+    // the file against the on-disk state BEFORE applying the mutation.
+    // We read disk content once and feed it to the validator so a single
+    // syscall covers both the gate decision AND the oldString/newString
+    // replacement below.
     const before = readFileSync(resolved, 'utf8');
-    const currentHash = hashContent(before);
-    if (currentHash !== readRecord.sha256) {
-        throw new Error(`Cannot edit ${path}: file changed since last read`);
+    const currentStat = statSync(resolved);
+    const validation = ctx.readCache.validate(ctx.root, path, currentStat.mtimeMs, before);
+    if (validation.stale) {
+        const reason = `stale_read: edit ${path} refused — ${validation.detail}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new StaleReadError(path, validation.reason, validation.detail);
     }
+    const currentHash = hashContent(before);
     const matches = before.split(oldString).length - 1;
-    if (matches === 0)
-        throw new Error(`Cannot edit ${path}: oldString not found`);
-    if (matches > 1)
-        throw new Error(`Cannot edit ${path}: oldString is not unique`);
+    if (matches === 0) {
+        const reason = `Cannot edit ${path}: oldString not found`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    if (matches > 1) {
+        const reason = `Cannot edit ${path}: oldString is not unique`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
     const after = before.replace(oldString, newString);
     const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
     writeFileSync(tmp, after, { encoding: 'utf8', mode: 0o600 });
     renameSync(tmp, resolved);
+    // Injection scan (ported an external utility,
+    // Apache-2.0). We scan the NEW SUBSTRING the model is inserting,
+    // not the full post-edit file — the rest of the file is operator-
+    // owned content that pre-dates this dispatch. False-positive on
+    // legitimate prose that mentions banned phrases is the worst
+    // outcome and the warn-only contract bounds the cost.
+    surfaceInjectionWarning(ctx, toolCallId, 'edit', path, newString);
     ctx.readCache.set(createReadRecord(ctx.root, path, after, 'read_tool'));
     recordFileMutation(ctx.session, {
         toolCallId,
@@ -193,7 +310,7 @@ export function editTool(ctx, path, oldString, newString) {
 }
 export function globTool(ctx, pattern) {
     const toolCallId = recordToolCall(ctx.session, 'glob', pattern);
-    // α6.9 WriteGate: cancel-aware short-circuit. Glob is read-only but
+    // WriteGate: cancel-aware short-circuit. Glob is read-only but
     // can be expensive on large trees; respecting the abort here keeps
     // the tool loop responsive when the operator hits Ctrl+C mid-scan.
     if (ctx.cancellation && ctx.cancellation.isAborted) {
@@ -203,11 +320,11 @@ export function globTool(ctx, pattern) {
     }
     // Pugi globs are workspace-scoped. Reject any pattern that could enumerate
     // outside the workspace:
-    //   1. absolute paths (`/etc/**/*`) — globSync resolves these against `/`
-    //      regardless of `cwd`, so they fan out outside the repo.
-    //   2. `..` as a path SEGMENT (`../*`, `src/../etc`) — parent traversal.
-    //      A substring check would over-reject legitimate names like
-    //      `src/v1..v2/*` so we split on `/` instead.
+    //  1. absolute paths (`/etc/**/*`) — globSync resolves these against `/`
+    //     regardless of `cwd`, so they fan out outside the repo.
+    //  2. `..` as a path SEGMENT (`../*`, `src/../etc`) — parent traversal.
+    //     A substring check would over-reject legitimate names like
+    //     `src/v1..v2/*` so we split on `/` instead.
     if (isAbsolute(pattern)) {
         const reason = `Absolute glob patterns are not allowed: ${pattern}`;
         recordToolResult(ctx.session, toolCallId, 'error', reason);
@@ -230,7 +347,7 @@ export function globTool(ctx, pattern) {
 }
 export function grepTool(ctx, query) {
     const toolCallId = recordToolCall(ctx.session, 'grep', query);
-    // α6.9 WriteGate: refuse before scanning. Grep walks the whole
+    // WriteGate: refuse before scanning. Grep walks the whole
     // workspace and can take seconds on a large repo; check abort first
     // so a cancel mid-scan returns immediately rather than after the
     // full walk completes.
@@ -244,7 +361,7 @@ export function grepTool(ctx, query) {
     for (const path of files) {
         if (matches.length >= 200)
             break;
-        // α6.9 WriteGate: poll abort inside the file loop so a cancel
+        // WriteGate: poll abort inside the file loop so a cancel
         // arriving mid-scan terminates early. The per-file branch keeps
         // the responsiveness bounded by the slowest single-file read.
         if (ctx.cancellation && ctx.cancellation.isAborted) {
@@ -289,18 +406,18 @@ export function grepTool(ctx, query) {
 }
 /**
  * Workspace-scoped bash tool. Sized for the M1 engine adapter:
- *   - Runs through `/bin/sh -c <command>` so the model can use pipes,
- *     redirection, and shell builtins (`ls | wc -l`, `git status`).
- *   - `cwd` is pinned to the workspace root so a stray `cd /` cannot
- *     leak commands outside the repo (the child process inherits root
- *     filesystem visibility — destructive patterns are blocked by
- *     `decidePermission`, not by chroot).
- *   - Output capped at 64KB combined stdout/stderr to keep the
- *     transcript bounded; the model gets the head + a `(...truncated)`
- *     marker if the cap fires.
- *   - 30s wall-clock timeout. The engine loop's per-tool error path
- *     surfaces the timeout to the model so it can retry with a narrower
- *     command or give up.
+ *  - Runs through `/bin/sh -c <command>` so the model can use pipes,
+ *    redirection, and shell builtins (`ls | wc -l`, `git status`).
+ *  - `cwd` is pinned to the workspace root so a stray `cd /` cannot
+ *    leak commands outside the repo (the child process inherits root
+ *    filesystem visibility — destructive patterns are blocked by
+ *    `decidePermission`, not by chroot).
+ *  - Output capped at 64KB combined stdout/stderr to keep the
+ *    transcript bounded; the model gets the head + a `(...truncated)`
+ *    marker if the cap fires.
+ *  - 30s wall-clock timeout. The engine loop's per-tool error path
+ *    surfaces the timeout to the model so it can retry with a narrower
+ *    command or give up.
  *
  * Permission gating: `kind: 'bash'`. The CLI's permission module already
  * hard-denies the destructive-patterns list (rm -rf /, DROP DATABASE,
@@ -311,7 +428,7 @@ export const BASH_OUTPUT_CAP = 64 * 1024;
 export const BASH_DEFAULT_TIMEOUT_MS = 30_000;
 // Child-process stdio buffer — large enough that the model-facing
 // truncation cap (`BASH_OUTPUT_CAP`) is always the gate, never the
-// child's internal buffer. Code Reviewer P2 retro 2026-05-23 flagged
+// child's internal buffer. Code Reviewer P2 retro flagged
 // `BASH_OUTPUT_CAP * 2` as too tight: real builds (`pnpm build`,
 // `tsc --noEmit`) routinely exceed 128 KB combined and the model
 // then saw a fatal `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` instead of a
@@ -319,7 +436,7 @@ export const BASH_DEFAULT_TIMEOUT_MS = 30_000;
 export const BASH_CHILD_MAXBUFFER = 10 * 1024 * 1024;
 export function bashTool(ctx, command, options = {}) {
     const toolCallId = recordToolCall(ctx.session, 'bash', command);
-    // α6.9 WriteGate: bash is the highest-risk tool surface. Refuse
+    // WriteGate: bash is the highest-risk tool surface. Refuse
     // before the destructive-pattern classifier even runs so a
     // cancelled dispatch never spawns a child process. Note: this is
     // pre-spawn cancellation only; once the /bin/sh -c process is
@@ -343,7 +460,7 @@ export function bashTool(ctx, command, options = {}) {
     //
     // Env sanitisation strategy: build the child env from an explicit
     // allow-list rather than inheriting `process.env` and trying to
-    // strip secrets after the fact. Code Reviewer P1 2026-05-23 flagged
+    // strip secrets after the fact. Code Reviewer P1 flagged
     // that the deny-list approach missed ANTHROPIC_API_KEY / GH_TOKEN
     // / AWS_SECRET_ACCESS_KEY / DATABASE_URL / arbitrary *_TOKEN /
     // *_SECRET / *_KEY variables — every CI agent rotation would risk
@@ -372,7 +489,7 @@ export function bashTool(ctx, command, options = {}) {
     }
     const timeoutMs = options.timeoutMs ?? BASH_DEFAULT_TIMEOUT_MS;
     // `spawnSync` (vs `execFileSync`) captures stdout AND stderr on
-    // BOTH success and failure paths. Code Reviewer P1 2026-05-23:
+    // BOTH success and failure paths. Code Reviewer P1:
     // `execFileSync` returns only stdout on exit 0, silently dropping
     // stderr output from `tsc`, `eslint`, `pytest`, etc. — the model
     // would see `(no output)` for successful runs that emitted real
@@ -381,7 +498,7 @@ export function bashTool(ctx, command, options = {}) {
     // maxBuffer is generous (10 MB) so the child process is never the
     // truncation gate — the post-hoc `.slice(0, BASH_OUTPUT_CAP)` below
     // is the single source of truth for what the model sees. Code
-    // Reviewer P2 retro 2026-05-23: the previous `BASH_OUTPUT_CAP * 2`
+    // Reviewer P2 retro: the previous `BASH_OUTPUT_CAP * 2`
     // (128 KB) would hard-throw `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`
     // on noisy commands (`pnpm build`, `tsc --noEmit` on the whole
     // monorepo) instead of returning the truncated head.

package/dist/tools/lsp-tools.js

@@ -0,0 +1,189 @@
+import { gateOnCancellation, OperatorAbortedError } from './file-tools.js';
+import { recordToolCall, recordToolResult } from '../core/session.js';
+/** Cap for any single LSP tool's payload size. Keeps model context lean. */
+const LSP_PAYLOAD_CAP_BYTES = 8 * 1024;
+export async function lspHover(ctx, lang, file, line, col) {
+    const toolCallId = recordToolCall(ctx.session, 'lsp_hover', `${lang}:${file}:${line}:${col}`);
+    return guard(ctx, 'lsp_hover', toolCallId, async () => {
+        const client = ctx.lspClients?.get(lang);
+        if (!client)
+            return unavailable(lang);
+        const result = await client.hover(file, { line, character: col }, ctx.cancellation);
+        if (!result.ok)
+            return failure(result);
+        if (!result.value) {
+            return { ok: true, value: { content: '' } };
+        }
+        const content = truncate(result.value.content);
+        return {
+            ok: true,
+            value: {
+                content: content.text,
+                ...(result.value.range ? { range: result.value.range } : {}),
+            },
+            ...(content.truncated ? { truncated: true } : {}),
+        };
+    });
+}
+export async function lspDefinition(ctx, lang, file, line, col) {
+    const toolCallId = recordToolCall(ctx.session, 'lsp_definition', `${lang}:${file}:${line}:${col}`);
+    return guard(ctx, 'lsp_definition', toolCallId, async () => {
+        const client = ctx.lspClients?.get(lang);
+        if (!client)
+            return unavailable(lang);
+        const result = await client.definition(file, { line, character: col }, ctx.cancellation);
+        if (!result.ok)
+            return failure(result);
+        const capped = capLocations(result.value);
+        return {
+            ok: true,
+            value: capped.value,
+            ...(capped.truncated ? { truncated: true } : {}),
+        };
+    });
+}
+export async function lspReferences(ctx, lang, file, line, col) {
+    const toolCallId = recordToolCall(ctx.session, 'lsp_references', `${lang}:${file}:${line}:${col}`);
+    return guard(ctx, 'lsp_references', toolCallId, async () => {
+        const client = ctx.lspClients?.get(lang);
+        if (!client)
+            return unavailable(lang);
+        const result = await client.references(file, { line, character: col }, ctx.cancellation);
+        if (!result.ok)
+            return failure(result);
+        const capped = capLocations(result.value);
+        return {
+            ok: true,
+            value: capped.value,
+            ...(capped.truncated ? { truncated: true } : {}),
+        };
+    });
+}
+export async function lspDiagnostics(ctx, lang, file) {
+    const toolCallId = recordToolCall(ctx.session, 'lsp_diagnostics', `${lang}:${file}`);
+    return guard(ctx, 'lsp_diagnostics', toolCallId, async () => {
+        const client = ctx.lspClients?.get(lang);
+        if (!client)
+            return unavailable(lang);
+        const result = await client.diagnostics(file, ctx.cancellation);
+        if (!result.ok)
+            return failure(result);
+        const capped = capDiagnostics(result.value);
+        return {
+            ok: true,
+            value: capped.value,
+            ...(capped.truncated ? { truncated: true } : {}),
+        };
+    });
+}
+async function guard(ctx, toolName, toolCallId, op) {
+    try {
+        gateOnCancellation(ctx, toolName);
+    }
+    catch (error) {
+        if (error instanceof OperatorAbortedError) {
+            recordToolResult(ctx.session, toolCallId, 'cancelled', error.message);
+            return { ok: false, reason: 'operator_aborted', detail: error.message };
+        }
+        throw error;
+    }
+    try {
+        const result = await op();
+        if (result.ok) {
+            recordToolResult(ctx.session, toolCallId, 'success', summarize(result.value));
+        }
+        else {
+            recordToolResult(ctx.session, toolCallId, 'error', `${result.reason ?? 'error'}: ${result.detail ?? ''}`);
+        }
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        recordToolResult(ctx.session, toolCallId, 'error', message);
+        return { ok: false, reason: 'lsp_error', detail: message };
+    }
+}
+function unavailable(lang) {
+    return {
+        ok: false,
+        reason: 'lsp_unavailable',
+        detail: `no LSP server started for ${lang}. Install the server and re-run ` +
+            `with --lsp ${lang}, or fall back to grep.`,
+    };
+}
+function failure(result) {
+    if (result.ok) {
+        // Shouldn't be hit — caller checks first.
+        return { ok: true, value: result.value };
+    }
+    return { ok: false, reason: result.reason, detail: result.detail };
+}
+function summarize(value) {
+    if (value === null || value === undefined)
+        return 'no result';
+    if (Array.isArray(value))
+        return `${value.length} items`;
+    if (typeof value === 'object')
+        return Object.keys(value).join(',');
+    return String(value);
+}
+function truncate(text) {
+    const bytes = Buffer.byteLength(text, 'utf8');
+    if (bytes <= LSP_PAYLOAD_CAP_BYTES)
+        return { text, truncated: false };
+    // Truncate to the cap byte boundary. We don't try to honor codepoint
+    // alignment — UTF-8 surrogate splits show up as a single ? at the
+    // boundary, which is acceptable for a debug surface; the dispatcher
+    // is the trust boundary for "this is what the model will see".
+    const buf = Buffer.from(text, 'utf8').subarray(0, LSP_PAYLOAD_CAP_BYTES);
+    return { text: `${buf.toString('utf8')}\n... [truncated]`, truncated: true };
+}
+function capLocations(locations) {
+    // Cap at 200 locations OR the byte cap, whichever hits first. The
+    // 200 number is the operator-facing "this is a hot symbol" threshold —
+    // a richer surface (paginated `pugi lsp references --offset N`) is
+    // open backlog.
+    const COUNT_CAP = 200;
+    if (locations.length === 0)
+        return { value: locations, truncated: false };
+    const trimmed = locations.slice(0, COUNT_CAP);
+    const serialized = JSON.stringify(trimmed);
+    if (Buffer.byteLength(serialized, 'utf8') <= LSP_PAYLOAD_CAP_BYTES && trimmed.length === locations.length) {
+        return { value: trimmed, truncated: false };
+    }
+    // Trim by halves until we fit the byte cap. Worst case ~10 iterations
+    // for the 200 max, fine for an interactive tool.
+    let upper = trimmed.length;
+    while (upper > 1) {
+        const half = Math.floor(upper / 2);
+        const sub = trimmed.slice(0, half);
+        if (Buffer.byteLength(JSON.stringify(sub), 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
+            return { value: sub, truncated: true };
+        }
+        upper = half;
+    }
+    return { value: trimmed.slice(0, 1), truncated: true };
+}
+function capDiagnostics(items) {
+    if (items.length === 0)
+        return { value: items, truncated: false };
+    const serialized = JSON.stringify(items);
+    if (Buffer.byteLength(serialized, 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
+        return { value: items, truncated: false };
+    }
+    // Diagnostics are sorted error-first in LSP convention; trim from the
+    // tail so we keep the highest-severity items.
+    let upper = items.length;
+    while (upper > 1) {
+        const half = Math.floor(upper / 2);
+        const sub = items.slice(0, half);
+        if (Buffer.byteLength(JSON.stringify(sub), 'utf8') <= LSP_PAYLOAD_CAP_BYTES) {
+            return { value: sub, truncated: true };
+        }
+        upper = half;
+    }
+    return { value: items.slice(0, 1), truncated: true };
+}
+/** Test-only surface so specs can poke truncation directly. */
+export const __test__ = { truncate, capLocations, capDiagnostics, LSP_PAYLOAD_CAP_BYTES };
+//# sourceMappingURL=lsp-tools.js.map