@hoangsonw/forge 0.1.0

package/dist/web/browse.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBrowseSteps = exports.openSession = void 0;
+/**
+ * Agentic browser via Playwright (optional peer dep). Deliberately a thin
+ * high-level abstraction: `open`, `click`, `type`, `extract`, `screenshot`.
+ * We avoid exposing the raw Page API so the LLM can't accidentally execute
+ * arbitrary page JS.
+ *
+ * Playwright is loaded lazily so users who don't need browsing don't pay for
+ * it. If it's not installed, every browse call returns a helpful error.
+ */
+const errors_1 = require("../types/errors");
+const logger_1 = require("../logging/logger");
+const sanitize_1 = require("./sanitize");
+const redact_1 = require("../security/redact");
+let cachedPlaywright = null;
+const loadPlaywright = async () => {
+    if (cachedPlaywright)
+        return cachedPlaywright;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        cachedPlaywright = require('playwright');
+        return cachedPlaywright;
+    }
+    catch {
+        throw new errors_1.ForgeRuntimeError({
+            class: 'not_found',
+            message: 'Playwright is not installed. Run `npm install -g playwright && npx playwright install chromium` to enable browsing.',
+            retryable: false,
+        });
+    }
+};
+const openSession = async (opts = {}) => {
+    const playwright = await loadPlaywright();
+    const browser = await playwright.chromium.launch({ headless: opts.headless ?? true });
+    const context = await browser.newContext({
+        javaScriptEnabled: true,
+        bypassCSP: false,
+        userAgent: 'Forge/0.1 (+https://github.com/forge/forge)',
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(opts.timeoutMs ?? 20_000);
+    return {
+        browser,
+        context,
+        page,
+        close: async () => {
+            try {
+                await context.close();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                await browser.close();
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+};
+exports.openSession = openSession;
+const runBrowseSteps = async (steps, opts = {}) => {
+    const session = await (0, exports.openSession)(opts);
+    const logs = [];
+    try {
+        for (const step of steps) {
+            switch (step.op) {
+                case 'goto': {
+                    if (!step.url)
+                        throw new errors_1.ForgeRuntimeError({
+                            class: 'user_input',
+                            message: 'goto requires url',
+                            retryable: false,
+                        });
+                    await session.page.goto(step.url, {
+                        timeout: step.timeoutMs ?? 20_000,
+                        waitUntil: 'domcontentloaded',
+                    });
+                    logs.push(`goto ${step.url}`);
+                    break;
+                }
+                case 'click': {
+                    if (!step.selector)
+                        throw new errors_1.ForgeRuntimeError({
+                            class: 'user_input',
+                            message: 'click requires selector',
+                            retryable: false,
+                        });
+                    await session.page.click(step.selector, { timeout: step.timeoutMs ?? 10_000 });
+                    logs.push(`click ${step.selector}`);
+                    break;
+                }
+                case 'type': {
+                    if (!step.selector || step.text == null)
+                        throw new errors_1.ForgeRuntimeError({
+                            class: 'user_input',
+                            message: 'type requires selector+text',
+                            retryable: false,
+                        });
+                    await session.page.fill(step.selector, step.text, { timeout: step.timeoutMs ?? 10_000 });
+                    logs.push(`type ${step.selector} (${step.text.length} chars)`);
+                    break;
+                }
+                case 'press': {
+                    if (!step.key)
+                        throw new errors_1.ForgeRuntimeError({
+                            class: 'user_input',
+                            message: 'press requires key',
+                            retryable: false,
+                        });
+                    await session.page.keyboard.press(step.key);
+                    logs.push(`press ${step.key}`);
+                    break;
+                }
+                case 'waitFor': {
+                    if (!step.selector)
+                        throw new errors_1.ForgeRuntimeError({
+                            class: 'user_input',
+                            message: 'waitFor requires selector',
+                            retryable: false,
+                        });
+                    await session.page.waitForSelector(step.selector, { timeout: step.timeoutMs ?? 10_000 });
+                    logs.push(`waitFor ${step.selector}`);
+                    break;
+                }
+                case 'extract': {
+                    const content = (await session.page.content());
+                    const txt = (0, sanitize_1.htmlToText)(content);
+                    const title = await session.page.title();
+                    const url = session.page.url();
+                    return {
+                        logs,
+                        text: (0, redact_1.redactString)((0, sanitize_1.truncateText)(txt.text, step.maxChars ?? 10_000)),
+                        title: title || txt.title,
+                        url,
+                        flaggedInjection: txt.flaggedInjection,
+                    };
+                }
+            }
+        }
+        const content = (await session.page.content());
+        const txt = (0, sanitize_1.htmlToText)(content);
+        const title = await session.page.title();
+        return {
+            logs,
+            text: (0, redact_1.redactString)((0, sanitize_1.truncateText)(txt.text, 10_000)),
+            title: title || txt.title,
+            url: session.page.url(),
+            flaggedInjection: txt.flaggedInjection,
+        };
+    }
+    catch (err) {
+        logger_1.log.warn('browser step failed', { err: String(err) });
+        throw err instanceof errors_1.ForgeRuntimeError
+            ? err
+            : new errors_1.ForgeRuntimeError({ class: 'tool_error', message: String(err), retryable: true });
+    }
+    finally {
+        await session.close();
+    }
+};
+exports.runBrowseSteps = runBrowseSteps;
+//# sourceMappingURL=browse.js.map

package/dist/web/browse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.js","sourceRoot":"","sources":["../../src/web/browse.ts"],"names":[],"mappings":"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"}

package/dist/web/fetch.d.ts

@@ -0,0 +1,18 @@
+export interface FetchResult {
+    url: string;
+    finalUrl: string;
+    status: number;
+    contentType: string;
+    title: string | null;
+    text: string;
+    bytesReceived: number;
+    flaggedInjection: boolean;
+}
+export interface FetchOptions {
+    url: string;
+    maxBytes?: number;
+    timeoutMs?: number;
+    maxChars?: number;
+}
+export declare const webFetch: (opts: FetchOptions) => Promise<FetchResult>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/web/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/web/fetch.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA8CD,eAAO,MAAM,QAAQ,GAAU,MAAM,YAAY,KAAG,OAAO,CAAC,WAAW,CAmDtE,CAAC"}

package/dist/web/fetch.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webFetch = void 0;
+/**
+ * URL fetch with size caps, content-type guard, and markdown-ish extraction.
+ */
+const undici_1 = require("undici");
+const errors_1 = require("../types/errors");
+const sanitize_1 = require("./sanitize");
+const redact_1 = require("../security/redact");
+const PRIVATE_HOSTS = [
+    /^localhost$/i,
+    /^127\./,
+    /^0\.0\.0\.0$/,
+    /^10\./,
+    /^192\.168\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^169\.254\./,
+    /^::1$/,
+    /^fc[0-9a-f]{2}:/i,
+    /^fe80:/i,
+];
+const guardUrl = (raw) => {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new errors_1.ForgeRuntimeError({
+            class: 'user_input',
+            message: `Invalid URL: ${raw}`,
+            retryable: false,
+        });
+    }
+    if (!/^https?:$/.test(u.protocol)) {
+        throw new errors_1.ForgeRuntimeError({
+            class: 'sandbox_violation',
+            message: `Protocol ${u.protocol} is not allowed (http/https only).`,
+            retryable: false,
+        });
+    }
+    const host = u.hostname;
+    for (const re of PRIVATE_HOSTS) {
+        if (re.test(host)) {
+            throw new errors_1.ForgeRuntimeError({
+                class: 'sandbox_violation',
+                message: `SSRF guard: ${host} is a private/loopback address.`,
+                retryable: false,
+            });
+        }
+    }
+    return u;
+};
+const webFetch = async (opts) => {
+    const u = guardUrl(opts.url);
+    const maxBytes = opts.maxBytes ?? 2 * 1024 * 1024;
+    const res = await (0, undici_1.request)(u.toString(), {
+        method: 'GET',
+        headers: {
+            accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+            'user-agent': 'Forge/0.1 (+https://github.com/forge/forge)',
+        },
+        maxRedirections: 5,
+        bodyTimeout: opts.timeoutMs ?? 15_000,
+        headersTimeout: opts.timeoutMs ?? 15_000,
+    });
+    const contentType = String(res.headers['content-type'] ?? '').toLowerCase();
+    if (!contentType.includes('text/') &&
+        !contentType.includes('application/json') &&
+        !contentType.includes('xml')) {
+        throw new errors_1.ForgeRuntimeError({
+            class: 'tool_error',
+            message: `Refusing to fetch non-text content-type: ${contentType}`,
+            retryable: false,
+        });
+    }
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of res.body) {
+        const buf = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+        chunks.push(buf);
+        bytes += buf.length;
+        if (bytes > maxBytes)
+            break;
+    }
+    const raw = Buffer.concat(chunks, Math.min(bytes, maxBytes)).toString('utf8');
+    let body;
+    if (contentType.includes('html') || contentType.includes('xml')) {
+        body = (0, sanitize_1.htmlToText)(raw);
+    }
+    else {
+        body = { text: raw, title: null, flaggedInjection: false };
+    }
+    const text = (0, redact_1.redactString)((0, sanitize_1.truncateText)(body.text, opts.maxChars ?? 20_000));
+    return {
+        url: opts.url,
+        finalUrl: u.toString(),
+        status: res.statusCode ?? 0,
+        contentType,
+        title: body.title,
+        text,
+        bytesReceived: bytes,
+        flaggedInjection: body.flaggedInjection,
+    };
+};
+exports.webFetch = webFetch;
+//# sourceMappingURL=fetch.js.map

package/dist/web/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/web/fetch.ts"],"names":[],"mappings":"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"}

package/dist/web/sanitize.d.ts

@@ -0,0 +1,8 @@
+export interface SanitizeResult {
+    text: string;
+    title: string | null;
+    flaggedInjection: boolean;
+}
+export declare const htmlToText: (html: string) => SanitizeResult;
+export declare const truncateText: (text: string, maxChars: number) => string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/web/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/web/sanitize.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,cAsBzC,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,UAAU,MAAM,KAAG,MAG7D,CAAC"}

package/dist/web/sanitize.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncateText = exports.htmlToText = void 0;
+/**
+ * HTML → markdown-ish plain text + injection-aware scrubbing.
+ *
+ * We deliberately avoid heavy HTML parsers; a sequence of regex passes gets
+ * us 95% of the signal for LLM context at a fraction of the size. For JS-
+ * rendered pages we rely on the Playwright-backed `web.browse` tool that
+ * already returns rendered text.
+ */
+const injection_1 = require("../security/injection");
+const removeBetween = (html, tag) => html.replace(new RegExp(`<${tag}\\b[\\s\\S]*?<\\/${tag}>`, 'gi'), ' ');
+const stripTags = (html) => html
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|section|article|li|h[1-6])>/gi, '\n')
+    .replace(/<li[^>]*>/gi, '- ')
+    .replace(/<[^>]+>/g, ' ');
+const decodeEntities = (s) => s
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&#x2F;/g, '/');
+const htmlToText = (html) => {
+    let cleaned = html;
+    cleaned = removeBetween(cleaned, 'script');
+    cleaned = removeBetween(cleaned, 'style');
+    cleaned = removeBetween(cleaned, 'noscript');
+    cleaned = removeBetween(cleaned, 'template');
+    const titleMatch = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(cleaned);
+    const title = titleMatch ? decodeEntities(titleMatch[1]).trim() : null;
+    cleaned = cleaned.replace(/<head\b[\s\S]*?<\/head>/gi, ' ');
+    cleaned = stripTags(cleaned);
+    cleaned = decodeEntities(cleaned);
+    cleaned = cleaned
+        .replace(/\r\n?/g, '\n')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n');
+    cleaned = cleaned.replace(/[ \t]{2,}/g, ' ').trim();
+    const injection = (0, injection_1.scanForInjection)(cleaned);
+    return {
+        text: injection.cleanContent,
+        title,
+        flaggedInjection: injection.flagged,
+    };
+};
+exports.htmlToText = htmlToText;
+const truncateText = (text, maxChars) => {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars) + '\n…[truncated]';
+};
+exports.truncateText = truncateText;
+//# sourceMappingURL=sanitize.js.map

package/dist/web/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../src/web/sanitize.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACH,qDAAyD;AAEzD,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,GAAW,EAAU,EAAE,CAC1D,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,oBAAoB,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;AAEzE,MAAM,SAAS,GAAG,CAAC,IAAY,EAAU,EAAE,CACzC,IAAI;KACD,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC;KAC7B,OAAO,CAAC,yCAAyC,EAAE,IAAI,CAAC;KACxD,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC;KAC5B,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;AAE9B,MAAM,cAAc,GAAG,CAAC,CAAS,EAAU,EAAE,CAC3C,CAAC;KACE,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;KACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;KACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;KACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;KACrB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;KACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;KACtB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;KACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AAQtB,MAAM,UAAU,GAAG,CAAC,IAAY,EAAkB,EAAE;IACzD,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3C,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC7C,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC7C,MAAM,UAAU,GAAG,kCAAkC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpE,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACvE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC;IAC5D,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAC7B,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,GAAG,OAAO;SACd,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC;SACvB,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC;SAC1B,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,IAAA,4BAAgB,EAAC,OAAO,CAAC,CAAC;IAC5C,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,YAAY;QAC5B,KAAK;QACL,gBAAgB,EAAE,SAAS,CAAC,OAAO;KACpC,CAAC;AACJ,CAAC,CAAC;AAtBW,QAAA,UAAU,cAsBrB;AAEK,MAAM,YAAY,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAU,EAAE;IACrE,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,gBAAgB,CAAC;AACpD,CAAC,CAAC;AAHW,QAAA,YAAY,gBAGvB"}

package/dist/web/search.d.ts

@@ -0,0 +1,12 @@
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export interface SearchOptions {
+    query: string;
+    limit?: number;
+    timeoutMs?: number;
+}
+export declare const webSearch: (opts: SearchOptions) => Promise<SearchResult[]>;
+//# sourceMappingURL=search.d.ts.map

package/dist/web/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/web/search.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyFD,eAAO,MAAM,SAAS,GAAU,MAAM,aAAa,KAAG,OAAO,CAAC,YAAY,EAAE,CAc3E,CAAC"}

package/dist/web/search.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webSearch = void 0;
+/**
+ * Pluggable web search. Supports:
+ *   - tavily (if TAVILY_API_KEY is set)
+ *   - brave (if BRAVE_SEARCH_API_KEY is set)
+ *   - duckduckgo HTML fallback (no key, best-effort)
+ *
+ * Provider precedence follows the env vars above. Results are normalized to a
+ * common shape and always traverse the injection/redaction pipeline before
+ * being returned to a caller.
+ */
+const undici_1 = require("undici");
+const redact_1 = require("../security/redact");
+const sanitize_1 = require("./sanitize");
+const logger_1 = require("../logging/logger");
+const tavily = async (opts) => {
+    const key = process.env.TAVILY_API_KEY;
+    if (!key)
+        return null;
+    const res = await (0, undici_1.request)('https://api.tavily.com/search', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            api_key: key,
+            query: opts.query,
+            max_results: opts.limit ?? 5,
+            search_depth: 'basic',
+        }),
+        bodyTimeout: opts.timeoutMs ?? 10_000,
+        headersTimeout: opts.timeoutMs ?? 10_000,
+    });
+    if (res.statusCode !== 200)
+        return null;
+    const body = (await res.body.json());
+    return (body.results ?? []).map((r) => ({
+        title: (0, redact_1.redactString)(r.title ?? ''),
+        url: r.url,
+        snippet: (0, redact_1.redactString)(r.content ?? '').slice(0, 500),
+    }));
+};
+const brave = async (opts) => {
+    const key = process.env.BRAVE_SEARCH_API_KEY;
+    if (!key)
+        return null;
+    const url = new URL('https://api.search.brave.com/res/v1/web/search');
+    url.searchParams.set('q', opts.query);
+    url.searchParams.set('count', String(opts.limit ?? 5));
+    const res = await (0, undici_1.request)(url.toString(), {
+        headers: { 'X-Subscription-Token': key, accept: 'application/json' },
+        bodyTimeout: opts.timeoutMs ?? 10_000,
+        headersTimeout: opts.timeoutMs ?? 10_000,
+    });
+    if (res.statusCode !== 200)
+        return null;
+    const body = (await res.body.json());
+    return (body.web?.results ?? []).map((r) => ({
+        title: (0, redact_1.redactString)(r.title ?? ''),
+        url: r.url,
+        snippet: (0, redact_1.redactString)(r.description ?? '').slice(0, 500),
+    }));
+};
+const duckduckgo = async (opts) => {
+    const url = new URL('https://duckduckgo.com/html/');
+    url.searchParams.set('q', opts.query);
+    try {
+        const res = await (0, undici_1.request)(url.toString(), {
+            headers: {
+                'user-agent': 'Mozilla/5.0 (X11; Linux x86_64; rv:125.0) Gecko/20100101 Firefox/125.0',
+                accept: 'text/html',
+            },
+            bodyTimeout: opts.timeoutMs ?? 10_000,
+            headersTimeout: opts.timeoutMs ?? 10_000,
+        });
+        if (res.statusCode !== 200)
+            return [];
+        const html = await res.body.text();
+        const results = [];
+        // DDG html results live in <a class="result__a" href="..."> ... </a>
+        const re = /<a[^>]+class="result__a"[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+        let m;
+        while ((m = re.exec(html)) && results.length < (opts.limit ?? 5)) {
+            const url = m[1];
+            const titleHtml = m[2];
+            const title = (0, sanitize_1.htmlToText)(titleHtml).text;
+            results.push({ title, url, snippet: '' });
+        }
+        // Fetch snippets from result__snippet
+        const snippetRe = /<a[^>]+class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+        let i = 0;
+        let sm;
+        while ((sm = snippetRe.exec(html)) && i < results.length) {
+            results[i].snippet = (0, sanitize_1.truncateText)((0, sanitize_1.htmlToText)(sm[1]).text, 400);
+            i++;
+        }
+        return results;
+    }
+    catch (err) {
+        logger_1.log.debug('duckduckgo search failed', { err: String(err) });
+        return [];
+    }
+};
+const webSearch = async (opts) => {
+    try {
+        const t = await tavily(opts);
+        if (t && t.length)
+            return t;
+    }
+    catch (err) {
+        logger_1.log.debug('tavily failed, trying next', { err: String(err) });
+    }
+    try {
+        const b = await brave(opts);
+        if (b && b.length)
+            return b;
+    }
+    catch (err) {
+        logger_1.log.debug('brave failed, trying next', { err: String(err) });
+    }
+    return (await duckduckgo(opts)) ?? [];
+};
+exports.webSearch = webSearch;
+//# sourceMappingURL=search.js.map

package/dist/web/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/web/search.ts"],"names":[],"mappings":"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"}

package/install/install.ps1

@@ -0,0 +1,46 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  Install Forge CLI on Windows via npm. Falls back to downloading a signed
+  portable binary from GitHub Releases when npm is unavailable.
+#>
+[CmdletBinding()]
+param(
+  [string]$Version = 'latest',
+  [string]$Package = '@forge/cli',
+  [switch]$SkipDownload
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Test-Command($name) {
+  try { Get-Command $name -ErrorAction Stop | Out-Null; return $true } catch { return $false }
+}
+
+if (Test-Command npm) {
+  Write-Host "Installing $Package@$Version via npm -g..."
+  npm install -g "$Package@$Version"
+  Write-Host ""
+  Write-Host "Run: forge init"
+  Write-Host "Then: forge run 'your first task'"
+  exit 0
+}
+
+if ($SkipDownload) {
+  Write-Error "npm not found and --SkipDownload passed. Install Node.js 20+ first."
+  exit 1
+}
+
+$home = if ($env:FORGE_HOME) { $env:FORGE_HOME } else { Join-Path $env:USERPROFILE '.forge' }
+New-Item -ItemType Directory -Force -Path (Join-Path $home 'bin') | Out-Null
+
+$arch = if ([Environment]::Is64BitOperatingSystem) { 'x64' } else { 'x86' }
+$artifact = "forge-windows-$arch.exe"
+$url = "https://github.com/forge/forge/releases/latest/download/$artifact"
+$dst = Join-Path $home 'bin\forge.exe'
+
+Write-Host "Downloading $url..."
+Invoke-WebRequest -Uri $url -OutFile $dst
+Write-Host "Installed to $dst"
+Write-Host ""
+Write-Host "Add $home\bin to your PATH, then run: forge init"

package/install/install.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Forge installer.
+#
+#   curl -fsSL https://get.forge.dev | bash      # end users (from registry)
+#   ./install/install.sh                         # inside a clone: dev-link
+#   FORGE_MODE=global ./install/install.sh       # force registry path
+#
+# End result (either path): `forge` on your PATH.
+
+FORGE_PKG="${FORGE_PKG:-@forge/cli}"
+FORGE_VERSION="${FORGE_VERSION:-latest}"
+FORGE_MODE="${FORGE_MODE:-auto}"
+
+say()  { printf '\033[1;36m[forge]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[forge]\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[1;31m[forge]\033[0m %s\n' "$*" >&2; exit 1; }
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || fail "Missing: $1. Install it first, then re-run."
+}
+
+need node
+need npm
+
+NODE_VERSION="$(node -v)"
+NODE_MAJOR="${NODE_VERSION#v}"
+NODE_MAJOR="${NODE_MAJOR%%.*}"
+if [ "${NODE_MAJOR:-0}" -lt 20 ]; then
+  fail "Forge needs Node 20+. You have ${NODE_VERSION}."
+fi
+
+# Detect dev-mode: are we running from inside the forge repo?
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+IN_REPO=0
+if [ -f "${REPO_ROOT}/package.json" ] && grep -q '"name": "@forge/cli"' "${REPO_ROOT}/package.json"; then
+  IN_REPO=1
+fi
+
+if [ "${FORGE_MODE}" = "auto" ] && [ "${IN_REPO}" -eq 1 ]; then
+  FORGE_MODE="dev"
+elif [ "${FORGE_MODE}" = "auto" ]; then
+  FORGE_MODE="global"
+fi
+
+case "${FORGE_MODE}" in
+  dev)
+    say "Detected checkout at ${REPO_ROOT} — installing via \`npm link\`."
+    cd "${REPO_ROOT}"
+    exec "${REPO_ROOT}/scripts/link.sh"
+    ;;
+  global)
+    say "Installing ${FORGE_PKG}@${FORGE_VERSION} via npm -g ..."
+    npm install -g "${FORGE_PKG}@${FORGE_VERSION}"
+    ;;
+  *)
+    fail "Unknown FORGE_MODE='${FORGE_MODE}'. Use 'auto', 'dev', or 'global'."
+    ;;
+esac
+
+GLOBAL_BIN="$(npm prefix -g)/bin"
+case ":${PATH}:" in
+  *":${GLOBAL_BIN}:"*) ;;
+  *) warn "\`${GLOBAL_BIN}\` is not on your PATH. Add: export PATH=\"${GLOBAL_BIN}:\$PATH\"" ;;
+esac
+
+say "Done. Try:"
+echo "    forge init"
+echo "    forge run \"your first task\""
+echo "    forge ui"