@zhixuan92/multi-model-agent-core 3.11.0 → 3.12.0

package/dist/research/adapters/semantic-scholar.js

@@ -0,0 +1,54 @@
+import { request } from 'undici';
+function normalizeRecord(r) {
+    const paperId = typeof r.paperId === 'string' && r.paperId.length > 0 ? r.paperId : null;
+    const title = typeof r.title === 'string' ? r.title.trim() : '';
+    if (!paperId || !title)
+        return null;
+    const abstract = typeof r.abstract === 'string' ? r.abstract : '';
+    const apiUrl = typeof r.url === 'string' && r.url.length > 0 ? r.url : null;
+    const year = typeof r.year === 'number' && Number.isFinite(r.year) && r.year > 1900 ? r.year : null;
+    return {
+        adapterId: 'semantic_scholar',
+        recordId: paperId,
+        title,
+        url: apiUrl ?? `https://www.semanticscholar.org/paper/${paperId}`,
+        snippet: abstract.slice(0, 500),
+        publishedAt: year ? `${year}-01-01` : undefined,
+        raw: r,
+    };
+}
+export async function semanticScholarSearch(query, opts = {}) {
+    const max = Math.min(25, Math.max(1, opts.maxResults ?? 10));
+    const url = new URL('https://api.semanticscholar.org/graph/v1/paper/search');
+    url.searchParams.set('query', query);
+    url.searchParams.set('limit', String(max));
+    url.searchParams.set('fields', 'paperId,title,abstract,year,authors,url');
+    let res;
+    try {
+        res = await request(url.toString(), { method: 'GET' });
+    }
+    catch (err) {
+        throw new Error(`semantic_scholar_request_failed: ${err.message}`);
+    }
+    if (res.statusCode === 429)
+        throw new Error('semantic_scholar_rate_limited');
+    if (res.statusCode >= 300 && res.statusCode < 400)
+        throw new Error('adapter_unexpected_redirect: semantic_scholar');
+    if (res.statusCode !== 200)
+        throw new Error(`semantic_scholar_http_${res.statusCode}`);
+    let body;
+    try {
+        body = await res.body.json();
+    }
+    catch (err) {
+        throw new Error(`semantic_scholar_parse_error: ${err.message}`);
+    }
+    const data = Array.isArray(body?.data)
+        ? body.data
+        : [];
+    return data
+        .slice(0, max)
+        .map(normalizeRecord)
+        .filter((r) => r !== null);
+}
+//# sourceMappingURL=semantic-scholar.js.map

package/dist/research/adapters/semantic-scholar.js.map

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

package/dist/research/adapters/types.d.ts

@@ -0,0 +1,15 @@
+export type AdapterId = 'arxiv' | 'semantic_scholar' | 'github_search' | 'rss';
+export interface AdapterResult {
+    adapterId: AdapterId;
+    recordId: string;
+    title: string;
+    url: string;
+    snippet: string;
+    publishedAt?: string;
+    raw: unknown;
+}
+export interface AdapterCallContext {
+    abortSignal: AbortSignal;
+    hostAllowlist?: ReadonlySet<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/research/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/research/adapters/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,kBAAkB,GAAG,eAAe,GAAG,KAAK,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IAEzB,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACrC"}

package/dist/research/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/research/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/research/adapters/types.ts"],"names":[],"mappings":""}

package/dist/research/allowlist.d.ts

@@ -0,0 +1,25 @@
+export declare function extractURLHosts(strings: readonly string[]): string[];
+export interface AllowlistInput {
+    fetchAllowlistExtra: readonly string[];
+    userSources: readonly string[];
+}
+export type AllowlistProvenance = 'extra' | 'user_source';
+export type HostAllowlist = ReadonlyMap<string, AllowlistProvenance>;
+/**
+ * Build the per-task fetch allowlist as a provenance-aware map. Per spec
+ * §6.2 / §7.1 step 8, the private-network opt-in is gated on
+ * `provenance === 'extra'` — only operator-declared hosts in
+ * `fetchAllowlistExtra` are eligible, never hosts harvested from
+ * `userSources`. Build order: userSources first (lower precedence), then
+ * fetchAllowlistExtra overwrites — so collisions resolve to the operator's
+ * deliberate intent.
+ *
+ * Both sources are validated through canonicalizeHostname; invalid entries
+ * (IP literals, single-label names, malformed hostnames, overlong hosts)
+ * are silently skipped. This mirrors ResearchConfigSchema's HostString
+ * canonicalization as defense-in-depth for callers that have not parsed
+ * configuration first; silent skipping preserves URL-extraction behavior
+ * for untrusted userSources while keeping this builder non-throwing.
+ */
+export declare function buildHostAllowlist(input: AllowlistInput): HostAllowlist;
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/research/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../src/research/allowlist.ts"],"names":[],"mappings":"AAyCA,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAsBpE;AAED,MAAM,WAAW,cAAc;IAC7B,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,aAAa,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAErE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,CAYvE"}

package/dist/research/allowlist.js

@@ -0,0 +1,102 @@
+import { isIP } from 'node:net';
+const URL_REGEX = /\bhttps?:\/\/[^\s'"<>()]+/gi;
+const FORBIDDEN_HOST_CHARS = /[\/:@?#]|:\/\//;
+const MAX_HOSTNAME_LENGTH = 253;
+const TRAILING_URL_PUNCTUATION = /[.,;:!?]+$/;
+/**
+ * Validate and canonicalize a hostname string. Returns the canonical
+ * (lowercase, IDNA-encoded) form or null if the input is not a valid
+ * DNS FQDN. Mirrors the HostString rules in config/schema.ts as a
+ * defense-in-depth layer: even though ResearchConfigSchema already
+ * validates fetchAllowlistExtra via HostString, this function ensures
+ * that any caller of buildHostAllowlist — including callers that bypass
+ * schema parsing — cannot inject non-FQDN entries with "extra" provenance.
+ */
+function canonicalizeHostname(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 || trimmed.length > MAX_HOSTNAME_LENGTH)
+        return null;
+    if (FORBIDDEN_HOST_CHARS.test(trimmed))
+        return null;
+    // Strip trailing dot (DNS root label) — example.com. ≡ example.com
+    const stripped = trimmed.endsWith('.') ? trimmed.slice(0, -1) : trimmed;
+    if (stripped.length === 0 || stripped.length > MAX_HOSTNAME_LENGTH)
+        return null;
+    let canonical;
+    try {
+        canonical = new URL(`https://${stripped}`).hostname;
+    }
+    catch {
+        return null;
+    }
+    if (canonical.length === 0 || canonical.length > MAX_HOSTNAME_LENGTH)
+        return null;
+    if (isIP(canonical) !== 0)
+        return null;
+    const labels = canonical.split('.');
+    if (labels.length < 2)
+        return null;
+    for (const label of labels) {
+        if (label.length === 0 || label.length > 63)
+            return null;
+        if (label.startsWith('-') || label.endsWith('-'))
+            return null;
+    }
+    return canonical;
+}
+export function extractURLHosts(strings) {
+    const out = [];
+    const seen = new Set();
+    for (const s of strings) {
+        const matches = s.match(URL_REGEX) ?? [];
+        for (const m of matches) {
+            try {
+                const candidate = m.replace(TRAILING_URL_PUNCTUATION, '');
+                const u = new URL(candidate);
+                if (!u.hostname)
+                    continue;
+                const canonical = canonicalizeHostname(u.hostname);
+                if (canonical === null)
+                    continue;
+                if (!seen.has(canonical)) {
+                    seen.add(canonical);
+                    out.push(canonical);
+                }
+            }
+            catch {
+                // malformed URL — silently skip
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Build the per-task fetch allowlist as a provenance-aware map. Per spec
+ * §6.2 / §7.1 step 8, the private-network opt-in is gated on
+ * `provenance === 'extra'` — only operator-declared hosts in
+ * `fetchAllowlistExtra` are eligible, never hosts harvested from
+ * `userSources`. Build order: userSources first (lower precedence), then
+ * fetchAllowlistExtra overwrites — so collisions resolve to the operator's
+ * deliberate intent.
+ *
+ * Both sources are validated through canonicalizeHostname; invalid entries
+ * (IP literals, single-label names, malformed hostnames, overlong hosts)
+ * are silently skipped. This mirrors ResearchConfigSchema's HostString
+ * canonicalization as defense-in-depth for callers that have not parsed
+ * configuration first; silent skipping preserves URL-extraction behavior
+ * for untrusted userSources while keeping this builder non-throwing.
+ */
+export function buildHostAllowlist(input) {
+    const map = new Map();
+    for (const h of extractURLHosts(input.userSources)) {
+        map.set(h, 'user_source');
+    }
+    for (const h of input.fetchAllowlistExtra) {
+        const canonical = canonicalizeHostname(h);
+        if (canonical !== null) {
+            map.set(canonical, 'extra');
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/research/allowlist.js.map

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

package/dist/research/ssrf-guard.d.ts

@@ -0,0 +1,12 @@
+export type IPClass = 'public' | 'loopback' | 'private' | 'link-local-or-metadata' | 'unspecified' | 'multicast' | 'broadcast-or-reserved';
+export declare class SsrfBlocked extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function classifyIP(ip: string): IPClass;
+export interface ResolveOptions {
+    resolve?: (host: string) => Promise<string[]>;
+    allowPrivateForHost: boolean;
+}
+export declare function resolveAndPin(host: string, options: ResolveOptions): Promise<string>;
+//# sourceMappingURL=ssrf-guard.d.ts.map

package/dist/research/ssrf-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssrf-guard.d.ts","sourceRoot":"","sources":["../../src/research/ssrf-guard.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,UAAU,GACV,SAAS,GACT,wBAAwB,GACxB,aAAa,GACb,WAAW,GACX,uBAAuB,CAAC;AAE5B,qBAAa,WAAY,SAAQ,KAAK;aACR,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI1D;AA8DD,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAyD9C;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AA+CD,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC,CAyCjB"}

package/dist/research/ssrf-guard.js

@@ -0,0 +1,209 @@
+import { isIP } from 'node:net';
+import { promises as dns } from 'node:dns';
+export class SsrfBlocked extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SsrfBlocked';
+    }
+}
+function ipv4ToInt(ip) {
+    const parts = ip.split('.').map(Number);
+    if (parts.length !== 4 || parts.some(p => Number.isNaN(p) || p < 0 || p > 255))
+        return null;
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+const inRange = (n, base, mask) => {
+    const b = ipv4ToInt(base);
+    if (b === null)
+        return false;
+    const m = mask === 0 ? 0 : (~0 << (32 - mask)) >>> 0;
+    return (n & m) === (b & m);
+};
+const IPV4_SPECIAL_RANGES = [
+    ['0.0.0.0', 8, 'unspecified'],
+    ['127.0.0.0', 8, 'loopback'],
+    ['10.0.0.0', 8, 'private'],
+    ['172.16.0.0', 12, 'private'],
+    ['192.168.0.0', 16, 'private'],
+    ['100.64.0.0', 10, 'private'], // RFC 6598 CGNAT; opt-in allowable with private hosts.
+    ['169.254.0.0', 16, 'link-local-or-metadata'],
+    // IANA IPv4 special-purpose ranges that are not normal public internet destinations.
+    ['192.0.0.0', 24, 'broadcast-or-reserved'],
+    ['192.0.2.0', 24, 'broadcast-or-reserved'], // TEST-NET-1
+    ['198.18.0.0', 15, 'broadcast-or-reserved'], // benchmarking
+    ['198.51.100.0', 24, 'broadcast-or-reserved'], // TEST-NET-2
+    ['203.0.113.0', 24, 'broadcast-or-reserved'], // TEST-NET-3
+    ['224.0.0.0', 4, 'multicast'],
+    ['240.0.0.0', 4, 'broadcast-or-reserved'],
+];
+/**
+ * Extract a 32-bit unsigned int from a 4-hex-group region of an expanded IPv6
+ * address (used for IPv4-mapped and 6to4 embedded-IPv4 extraction).
+ *
+ * Returns null on malformed input. The caller stringifies back to dotted-quad
+ * via classifyIP, so we don't need pretty formatting here.
+ */
+function expandIPv6Groups(addr) {
+    // Split on '::' (at most once); pad missing groups with '0'.
+    const halves = addr.split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] ? halves[0].split(':') : [];
+    const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const fill = 8 - (left.length + right.length);
+    if (fill < 0)
+        return null;
+    if (halves.length === 1 && left.length !== 8)
+        return null;
+    return [...left, ...Array(fill).fill('0'), ...right]
+        .map((g) => g.padStart(4, '0').toLowerCase());
+}
+function groupsToIPv4(g, startGroup) {
+    if (g.length < startGroup + 2)
+        return null;
+    const hi = parseInt(g[startGroup], 16);
+    const lo = parseInt(g[startGroup + 1], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo))
+        return null;
+    const a = (hi >> 8) & 0xff, b = hi & 0xff, c = (lo >> 8) & 0xff, d = lo & 0xff;
+    return `${a}.${b}.${c}.${d}`;
+}
+export function classifyIP(ip) {
+    const lower = ip.toLowerCase();
+    // Cloud-metadata ULAs (informal cloud-provider conventions; not IANA-registered)
+    // Checked before isIP because these patterns may use non-hex tokens like 'gcp'/'az'.
+    if (/^fd00:(ec2|gcp|az):/.test(lower))
+        return 'link-local-or-metadata';
+    const v = isIP(ip);
+    if (v === 4) {
+        const n = ipv4ToInt(ip);
+        if (n === null)
+            return 'broadcast-or-reserved';
+        if (n === 0xffffffff)
+            return 'broadcast-or-reserved';
+        for (const [base, mask, klass] of IPV4_SPECIAL_RANGES) {
+            if (inRange(n, base, mask))
+                return klass;
+        }
+        return 'public';
+    }
+    if (v === 6) {
+        if (lower === '::')
+            return 'unspecified';
+        if (lower === '::1')
+            return 'loopback';
+        // IPv4-mapped IPv6 (::ffff:a.b.c.d or ::ffff:HEXHEX:HEXHEX) — recurse on embedded IPv4
+        const v4mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+        if (v4mapped)
+            return classifyIP(v4mapped[1]);
+        const groups = expandIPv6Groups(lower);
+        if (groups && groups[0] === '0000' && groups[1] === '0000' && groups[2] === '0000'
+            && groups[3] === '0000' && groups[4] === '0000' && groups[5] === 'ffff') {
+            const embedded = groupsToIPv4(groups, 6);
+            if (embedded)
+                return classifyIP(embedded);
+        }
+        // 6to4 (2002::/16) — embeds IPv4 at bits 16–47 (groups 1 + 2). Recurse.
+        if (groups && groups[0] === '2002') {
+            const embedded = groupsToIPv4(groups, 1);
+            if (embedded)
+                return classifyIP(embedded);
+        }
+        // fe80::/10 link-local (covers fe80–febf when interpreted strictly).
+        if (groups && /^fe[89ab]/.test(groups[0]))
+            return 'link-local-or-metadata';
+        // Locally-assigned ULA (fc00::/8) and randomly-assigned ULA (fd00::/8) → 'private'.
+        // The opt-in policy in spec §7.1 step 8 distinguishes these two halves;
+        // classifyIP only reports membership in the conditional-reject set.
+        if (groups && (groups[0].startsWith('fc') || groups[0].startsWith('fd'))) {
+            return 'private';
+        }
+        if (lower.startsWith('ff'))
+            return 'multicast';
+        // IANA IPv6 special-purpose ranges that are not normal public internet destinations.
+        if (groups && groups[0] === '2001' && groups[1] === '0db8')
+            return 'broadcast-or-reserved';
+        if (groups && groups[0] === '2001' && /^0[0-1]/.test(groups[1] ?? ''))
+            return 'broadcast-or-reserved';
+        // Note: `fec0::/10` was a deprecated site-local block (RFC 3879). Modern
+        // unicast addresses outside fc00::/7 (e.g. `fec1::1`) are **routable**
+        // under current IANA allocations — classify as public, NOT link-local.
+        return 'public';
+    }
+    return 'broadcast-or-reserved';
+}
+const isNoRecordsError = (error) => {
+    const code = error?.code;
+    return code === 'ENODATA' || code === 'ENOTFOUND' || code === 'ESERVFAIL';
+};
+const defaultResolve = async (host) => {
+    const [v4, v6] = await Promise.allSettled([
+        dns.resolve4(host),
+        dns.resolve6(host),
+    ]);
+    const results = [];
+    if (v4.status === 'fulfilled')
+        results.push(...v4.value);
+    if (v6.status === 'fulfilled')
+        results.push(...v6.value);
+    if (results.length > 0)
+        return results;
+    const failures = [v4, v6].filter((r) => r.status === 'rejected');
+    if (failures.length > 0 && failures.some((r) => !isNoRecordsError(r.reason))) {
+        throw new Error('DNS resolution failed');
+    }
+    return results;
+};
+const BLOCKED_CLASSES_STRICT = new Set([
+    'loopback',
+    'private',
+    'link-local-or-metadata',
+    'unspecified',
+    'multicast',
+    'broadcast-or-reserved',
+]);
+const BLOCKED_CLASSES_PERMISSIVE = new Set([
+    'loopback',
+    'link-local-or-metadata',
+    'unspecified',
+    'multicast',
+    'broadcast-or-reserved',
+]);
+function isLocallyAssignedULA(ip) {
+    if (isIP(ip) !== 6)
+        return false;
+    const groups = expandIPv6Groups(ip.toLowerCase());
+    if (!groups)
+        return false;
+    return groups[0].startsWith('fc');
+}
+export async function resolveAndPin(host, options) {
+    const resolve = options.resolve ?? defaultResolve;
+    let ips;
+    try {
+        ips = await resolve(host);
+    }
+    catch {
+        throw new SsrfBlocked('web_fetch_dns_resolution_failed', `web_fetch_dns_resolution_failed: DNS resolution failed for host '${host}'`);
+    }
+    if (ips.length === 0) {
+        throw new SsrfBlocked('web_fetch_no_addresses', `web_fetch_no_addresses: no addresses resolved for host '${host}'`);
+    }
+    const blocked = options.allowPrivateForHost
+        ? BLOCKED_CLASSES_PERMISSIVE
+        : BLOCKED_CLASSES_STRICT;
+    for (const ip of ips) {
+        const klass = classifyIP(ip);
+        if (blocked.has(klass)) {
+            throw new SsrfBlocked('web_fetch_private_ip_blocked', `web_fetch_private_ip_blocked: resolved IP class '${klass}' is not allowed for host '${host}'`);
+        }
+        // fc00::/8 locally-assigned ULA is always-reject, even in permissive mode
+        if (isLocallyAssignedULA(ip)) {
+            throw new SsrfBlocked('web_fetch_private_ip_blocked', `web_fetch_private_ip_blocked: resolved IP is locally-assigned ULA (fc00::/8), which is never allowed for host '${host}'`);
+        }
+    }
+    return ips[0];
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/research/ssrf-guard.js.map

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

package/dist/research/types.d.ts

@@ -0,0 +1,14 @@
+export type { AdapterId, AdapterResult, AdapterCallContext } from './adapters/types.js';
+/**
+ * Tool definition shape that runner adapters consume. The explore executor
+ * builds an array of these for the external worker (taskIndex=1) and sets
+ * them on `TaskSpec.customToolset`. Runner adapters merge with the standard
+ * surface when present.
+ */
+export interface ResearchToolDefinition {
+    name: 'web_search' | 'web_fetch' | 'arxiv' | 'semantic_scholar' | 'github_search' | 'rss';
+    description: string;
+    inputSchema: unknown;
+    invoke(input: unknown): Promise<unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/research/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/research/types.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAExF;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,OAAO,GAAG,kBAAkB,GAAG,eAAe,GAAG,KAAK,CAAC;IAC1F,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C"}

package/dist/research/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/research/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/research/types.ts"],"names":[],"mappings":""}

package/dist/research/untrusted-content.d.ts

@@ -0,0 +1,13 @@
+export interface FetchedContent {
+    url: string;
+    host: string;
+    content: string;
+}
+export declare function wrapFetchedContent(c: FetchedContent): string;
+export interface SearchHit {
+    title: string;
+    url: string;
+    snippet: string;
+}
+export declare function wrapSearchResults(hits: readonly SearchHit[]): string;
+//# sourceMappingURL=untrusted-content.d.ts.map

package/dist/research/untrusted-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted-content.d.ts","sourceRoot":"","sources":["../../src/research/untrusted-content.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAE5D;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAEpE"}

package/dist/research/untrusted-content.js

@@ -0,0 +1,9 @@
+const escapeAttr = (s) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeBody = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export function wrapFetchedContent(c) {
+    return `<external-content url="${escapeAttr(c.url)}" host="${escapeAttr(c.host)}" trustLevel="untrusted">${escapeBody(c.content)}</external-content>`;
+}
+export function wrapSearchResults(hits) {
+    return `<external-search-results trustLevel="untrusted">${escapeBody(JSON.stringify(hits))}</external-search-results>`;
+}
+//# sourceMappingURL=untrusted-content.js.map

package/dist/research/untrusted-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted-content.js","sourceRoot":"","sources":["../../src/research/untrusted-content.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,EAAE,CAC/B,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAE/F,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,EAAE,CAC/B,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAQvE,MAAM,UAAU,kBAAkB,CAAC,CAAiB;IAClD,OAAO,0BAA0B,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,4BAA4B,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;AACxJ,CAAC;AAQD,MAAM,UAAU,iBAAiB,CAAC,IAA0B;IAC1D,OAAO,mDAAmD,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,4BAA4B,CAAC;AACzH,CAAC"}

package/dist/research/web-fetch.d.ts

@@ -0,0 +1,50 @@
+import { Agent } from 'undici';
+import type { ResearchConfig } from '../config/schema.js';
+export interface WebFetchInput {
+    url: string;
+    cfg: ResearchConfig['fetch'];
+    hostAllowlist: ReadonlySet<string>;
+    /** Hosts in this set may resolve to RFC1918 private addresses (still rejects loopback/metadata). */
+    privateNetworkHosts?: ReadonlySet<string>;
+    /** Test seam — replaces DNS resolution. */
+    resolveIP?: (host: string) => Promise<string>;
+    /**
+     * Test seam — return undefined to let undici use the global dispatcher (so
+     * MockAgent intercepts in tests). Default in prod builds an IP-pinning Agent
+     * per spec §7.1.10 with TLS SNI on the original hostname.
+     *
+     * Ownership: dispatchers returned by this hook are caller-owned/shared and
+     * will not be closed or destroyed by webFetch. The default dispatcher created
+     * by webFetch is one-shot and is disposed after its request completes.
+     */
+    createDispatcher?: (host: string, pinnedIP: string, cfg: ResearchConfig['fetch']) => import('undici').Dispatcher | undefined;
+}
+export declare const defaultIPPinningDispatcher: (host: string, pinnedIP: string, cfg: ResearchConfig["fetch"]) => Agent;
+export type WebFetchOk = {
+    status: 'ok';
+    /** Worker-facing string: <external-content …>extracted-text</external-content> */
+    body: string;
+    /** Adapter-facing raw text (HTML stripped to main-text for HTML; raw bytes for XML/JSON). NOT wrapped. */
+    rawText: string;
+    host: string;
+    bytesReturned: number;
+    /** True if the wire-level read was capped by cfg.maxBodyBytes (raw response truncated). */
+    truncated: boolean;
+    /**
+     * True if the post-extraction text was capped by RETURNED_TEXT_CAP (default 64 KiB).
+     * Adapters that parse rawText (e.g. rss) MUST inspect this flag — a true value
+     * means the XML/JSON body may be syntactically incomplete and parsing should be skipped.
+     * This is independent of truncated; both can be true if both caps tripped.
+     */
+    textTruncated: boolean;
+    credentialsStripped: boolean;
+};
+export type WebFetchErr = {
+    status: 'error';
+    reasonCode: string;
+    host?: string;
+    credentialsStripped: boolean;
+};
+export type WebFetchResult = WebFetchOk | WebFetchErr;
+export declare function webFetch(input: WebFetchInput): Promise<WebFetchResult>;
+//# sourceMappingURL=web-fetch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch.d.ts","sourceRoot":"","sources":["../../src/research/web-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,EAAE,MAAM,QAAQ,CAAC;AAIxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC;IAC7B,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,oGAAoG;IACpG,mBAAmB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,2CAA2C;IAC3C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,OAAO,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9H;AAED,eAAO,MAAM,0BAA0B,GAAI,MAAM,MAAM,EAAE,UAAU,MAAM,EAAE,KAAK,cAAc,CAAC,OAAO,CAAC,UAQnG,CAAC;AAEL,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,IAAI,CAAC;IACb,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AA4QtD,wBAAsB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA+K5E"}