@eightstate/escli 0.5.0

package/dist/services/research.js

@@ -0,0 +1,504 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../lib/escli-error.js';
+import { resolveCliToken } from './credentials.js';
+const API_BASE = 'https://api.parallel.ai';
+const DEFAULT_MAX_POLL_MS = 7_200_000;
+const DEFAULT_POLL_INTERVAL_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const STICKY_VEND_ATTEMPTS = 6;
+export const PROCESSORS = [
+    'lite', 'base', 'core', 'core2x', 'pro', 'ultra', 'ultra2x', 'ultra4x', 'ultra8x',
+    'lite-fast', 'base-fast', 'core-fast', 'core2x-fast', 'pro-fast', 'ultra-fast', 'ultra2x-fast', 'ultra4x-fast', 'ultra8x-fast',
+];
+export function listResearchProcessors() {
+    const processors = PROCESSORS.map((name) => ({ name }));
+    return { processors, count: processors.length };
+}
+export async function runResearch(options) {
+    const body = await buildTaskRequest(options);
+    const captured = {};
+    const task = await submitTask(body, captured, options.timeoutSeconds);
+    const runId = task.run_id;
+    if (!runId)
+        throw new EscliError('task creation response missing run_id', { code: ErrorCode.GateInvalidResponse });
+    if (captured.key)
+        await rememberRunOwner(runId, captured.key.fingerprint);
+    const apiKey = captured.key?.apiKey ?? await getResearchApiKeyForRun(runId);
+    const output = await pollUntilComplete(apiKey, runId, options.timeoutSeconds);
+    const data = { run_id: runId, processor: options.processor, output };
+    if (options.output) {
+        data.path = resolve(options.output);
+        await writeResearchOutput(data.path, options.query, data.processor, runId, output, task.created_at ?? '', options.noBasis);
+    }
+    return data;
+}
+export async function getResearchStatus(options) {
+    const apiKey = await getResearchApiKeyForRun(options.runId);
+    const result = await apiRequest('GET', `/v1/tasks/runs/${options.runId}`, apiKey, undefined, undefined, options.timeoutSeconds);
+    return {
+        run_id: stringValue(result.run_id) ?? options.runId,
+        status: stringValue(result.status) ?? 'unknown',
+        error: result.error,
+        warnings: Array.isArray(result.warnings) ? result.warnings : undefined,
+    };
+}
+export async function getResearchResult(options) {
+    const apiKey = await getResearchApiKeyForRun(options.runId);
+    const run = await apiRequest('GET', `/v1/tasks/runs/${options.runId}`, apiKey, undefined, undefined, options.timeoutSeconds);
+    if (run.status !== 'completed') {
+        throw new EscliError(`task not complete: ${String(run.status ?? 'unknown')}`, {
+            code: ErrorCode.ResearchTaskFailed,
+            details: { status: run.status, error: run.error },
+        });
+    }
+    const result = await apiRequest('GET', `/v1/tasks/runs/${options.runId}/result`, apiKey, undefined, undefined, options.timeoutSeconds);
+    const output = normalizeOutput(result.output);
+    const data = { run_id: options.runId, output };
+    if (options.output) {
+        data.path = resolve(options.output);
+        await writeResearchOutput(data.path, '(retrieved)', stringValue(run.processor) ?? '', options.runId, output, stringValue(run.created_at) ?? '', options.noBasis);
+    }
+    return data;
+}
+async function buildTaskRequest(options) {
+    const body = {
+        processor: options.processor,
+        input: options.query,
+    };
+    if (options.inputJson)
+        body.input = parseJsonInput(options.inputJson, '--input-json must be valid JSON');
+    if (options.inputFile)
+        body.input = await readJsonFile(options.inputFile, 'input file not found');
+    if (options.schema) {
+        body.task_spec = { output_schema: { type: 'json', json_schema: await readJsonFile(options.schema, 'schema file not found') } };
+    }
+    else if (options.outputSchema) {
+        body.task_spec = { output_schema: options.outputSchema };
+    }
+    else if (options.text) {
+        body.task_spec = { output_schema: { type: 'text' } };
+    }
+    const sourcePolicy = {};
+    if (options.includeDomains)
+        sourcePolicy.include_domains = splitCsv(options.includeDomains);
+    if (options.excludeDomains)
+        sourcePolicy.exclude_domains = splitCsv(options.excludeDomains);
+    if (options.afterDate)
+        sourcePolicy.after_date = options.afterDate;
+    if (Object.keys(sourcePolicy).length > 0)
+        body.source_policy = sourcePolicy;
+    if (options.location)
+        body.advanced_settings = { location: options.location };
+    if (options.metadata)
+        body.metadata = parseMetadata(options.metadata);
+    if (options.followUp)
+        body.previous_interaction_id = options.followUp;
+    return body;
+}
+async function submitTask(body, captured, timeoutSeconds) {
+    const explicitKey = process.env.PARALLEL_API_KEY;
+    if (explicitKey) {
+        captured.key = { apiKey: explicitKey, fingerprint: 'env' };
+        return apiRequest('POST', '/v1/tasks/runs', explicitKey, body, undefined, timeoutSeconds);
+    }
+    let lastRetryableError;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const key = await vendParallelKey();
+        if (!key)
+            break;
+        captured.key = key;
+        try {
+            return await apiRequest('POST', '/v1/tasks/runs', key.apiKey, body, undefined, timeoutSeconds);
+        }
+        catch (error) {
+            if (error instanceof EscliError && (error.code === ErrorCode.ApiRateLimited || error.code === ErrorCode.ServiceUnavailable)) {
+                await reportParallelKey(key.fingerprint, error.code === ErrorCode.ApiRateLimited ? 429 : 402);
+                lastRetryableError = error;
+                continue;
+            }
+            throw error;
+        }
+    }
+    if (lastRetryableError)
+        throw lastRetryableError;
+    throw new EscliError('no Parallel API key. Set PARALLEL_API_KEY or add one via the dashboard.', { code: ErrorCode.ResearchApiKeyMissing });
+}
+async function getResearchApiKeyForRun(runId) {
+    if (process.env.PARALLEL_API_KEY)
+        return process.env.PARALLEL_API_KEY;
+    const target = recallRunOwner(runId);
+    let lastKey;
+    for (let attempt = 0; attempt < STICKY_VEND_ATTEMPTS; attempt += 1) {
+        const key = await vendParallelKey();
+        if (!key)
+            break;
+        lastKey = key.apiKey;
+        if (!target || key.fingerprint === target)
+            return lastKey;
+    }
+    if (lastKey)
+        return lastKey;
+    throw new EscliError('no Parallel API key. Set PARALLEL_API_KEY or add one via the dashboard.', { code: ErrorCode.ResearchApiKeyMissing });
+}
+async function reportParallelKey(fingerprint, status) {
+    const token = resolveCliToken();
+    if (!token)
+        return;
+    try {
+        await fetch(`${gateUrl()}/api/keys/report`, {
+            method: 'POST',
+            headers: { 'authorization': `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ service: 'parallel', fingerprint, status }),
+        });
+    }
+    catch {
+        // Gate reporting is best-effort.
+    }
+}
+async function vendParallelKey() {
+    const token = resolveCliToken();
+    if (!token)
+        return null;
+    try {
+        const response = await fetch(`${gateUrl()}/api/keys/vend`, {
+            method: 'POST',
+            headers: { 'authorization': `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ service: 'parallel' }),
+        });
+        if (response.status !== 200)
+            return null;
+        const data = recordValue(await response.json());
+        if (data?.success !== true)
+            return null;
+        const apiKey = stringValue(data.api_key);
+        const fingerprint = stringValue(data.fingerprint);
+        if (!apiKey || !fingerprint)
+            return null;
+        return { apiKey, fingerprint, baseUrl: stringValue(data.base_url) };
+    }
+    catch {
+        return null;
+    }
+}
+async function apiRequest(method, path, apiKey, body, extraHeaders, timeoutSeconds) {
+    const responseText = await requestText(`${parallelBaseUrl()}${path}`, {
+        method,
+        headers: { 'content-type': 'application/json', 'x-api-key': apiKey, ...(extraHeaders ?? {}) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        timeoutMs: timeoutMs(timeoutSeconds),
+    });
+    return parseJsonResponse(responseText);
+}
+async function requestText(url, options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: options.method,
+            headers: options.headers,
+            body: options.body,
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw httpStatusError(response.status, formatHttpError(response.status, text), text);
+        return text;
+    }
+    catch (error) {
+        if (isHttpStatusError(error))
+            throw mapHttpStatusError(error);
+        throw mapNetworkError(error);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function pollUntilComplete(apiKey, runId, timeoutSeconds) {
+    const started = Date.now();
+    const maxMs = pollMaxMs(timeoutSeconds);
+    while (Date.now() - started < maxMs) {
+        const result = await apiRequest('GET', `/v1/tasks/runs/${runId}`, apiKey, undefined, undefined, timeoutSeconds);
+        const status = result.status;
+        if (status === 'completed') {
+            const output = await apiRequest('GET', `/v1/tasks/runs/${runId}/result`, apiKey, undefined, undefined, timeoutSeconds);
+            return normalizeOutput(output.output);
+        }
+        if (status === 'failed' || status === 'cancelled') {
+            throw new EscliError(`task ${String(status)}: ${String(result.error ?? '')}`, { code: ErrorCode.ResearchTaskFailed, details: result.error });
+        }
+        await sleep(pollIntervalMs());
+    }
+    throw new EscliError('research task timed out', { code: ErrorCode.ResearchTimeout });
+}
+async function writeResearchOutput(path, query, processor, runId, output, createdAt, noBasis) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, formatMarkdown(query, processor, runId, output, createdAt, !noBasis), 'utf8');
+    }
+    catch (error) {
+        throw new EscliError(`failed to write output file: ${error instanceof Error ? error.message : String(error)}`, { code: ErrorCode.FileWriteFailed });
+    }
+}
+export function formatMarkdown(query, processor, runId, output, createdAt, includeBasis = true) {
+    const now = new Date().toISOString().replace(/\.\d{3}Z$/u, 'Z');
+    const lines = [
+        '---', `query: "${query}"`, `processor: ${processor}`, `run_id: ${runId}`, `created_at: ${createdAt}`, `retrieved_at: ${now}`, '---', '', `# Research: ${query}`, '',
+    ];
+    if (output === null) {
+        lines.push('*No output returned.*');
+        return lines.join('\n');
+    }
+    const content = output.content;
+    const basis = Array.isArray(output.basis) ? output.basis : [];
+    if (typeof content === 'string') {
+        const parsed = parseMaybeJson(content);
+        if (recordValue(parsed))
+            renderDict(lines, parsed);
+        else
+            lines.push(content);
+    }
+    else if (recordValue(content)) {
+        renderDict(lines, content);
+    }
+    else if (content !== undefined && content !== null) {
+        lines.push(String(content));
+    }
+    if (includeBasis && basis.length > 0) {
+        lines.push('', '## Research Basis', '');
+        for (const item of basis) {
+            const entry = recordValue(item) ?? {};
+            const field = stringValue(entry.field) ?? 'unknown';
+            const reasoning = stringValue(entry.reasoning) ?? '';
+            const confidence = stringValue(entry.confidence) ?? '';
+            const citations = Array.isArray(entry.citations) ? entry.citations : [];
+            lines.push(`### ${field}`);
+            if (confidence)
+                lines.push(`**Confidence:** ${confidence}`);
+            if (reasoning)
+                lines.push('', reasoning);
+            if (citations.length > 0)
+                lines.push('');
+            for (const citation of citations) {
+                const cite = recordValue(citation) ?? {};
+                const url = stringValue(cite.url) ?? '';
+                const title = stringValue(cite.title) ?? url;
+                lines.push(`- [${title}](${url})`);
+                const excerpts = Array.isArray(cite.excerpts) ? cite.excerpts : [];
+                for (const excerpt of excerpts)
+                    lines.push(`  > ${String(excerpt)}`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+function renderDict(lines, data) {
+    for (const [key, value] of Object.entries(data)) {
+        lines.push(`## ${titleCase(key)}`, '');
+        if (typeof value === 'string')
+            lines.push(value);
+        else if (Array.isArray(value)) {
+            if (value.length > 0 && value.every((item) => Boolean(recordValue(item))))
+                renderTable(lines, value);
+            else
+                for (const item of value)
+                    lines.push(`- ${String(item)}`);
+        }
+        else if (recordValue(value)) {
+            for (const [nestedKey, nestedValue] of Object.entries(value))
+                lines.push(`**${titleCase(nestedKey)}:** ${String(nestedValue)}`);
+        }
+        else {
+            lines.push(String(value));
+        }
+        lines.push('');
+    }
+}
+function renderTable(lines, items) {
+    const keys = [...new Set(items.flatMap((item) => Object.keys(item)))];
+    lines.push(`| ${keys.map(titleCase).join(' | ')} |`);
+    lines.push(`| ${keys.map(() => '---').join(' | ')} |`);
+    for (const item of items)
+        lines.push(`| ${keys.map((key) => String(item[key] ?? '').replace(/\n/gu, ' ').replace(/\|/gu, '\\|')).join(' | ')} |`);
+}
+function titleCase(value) {
+    return value.replaceAll('_', ' ').replace(/\b\w/gu, (char) => char.toUpperCase());
+}
+function parseMetadata(value) {
+    const parsed = parseMaybeJson(value);
+    if (recordValue(parsed))
+        return parsed;
+    const metadata = {};
+    for (const pair of value.split(',')) {
+        const index = pair.indexOf('=');
+        if (index > 0)
+            metadata[pair.slice(0, index).trim()] = pair.slice(index + 1).trim();
+    }
+    return metadata;
+}
+function parseJsonInput(value, message) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw new EscliError(message, { code: ErrorCode.ResearchInputInvalid, details: error instanceof Error ? error.message : String(error) });
+    }
+}
+async function readJsonFile(path, missingMessage) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        const code = error.code === 'ENOENT' ? ErrorCode.FileNotFound : ErrorCode.FileReadFailed;
+        const exitCode = code === ErrorCode.FileNotFound ? ExitCodes.Usage : undefined;
+        throw new EscliError(`${missingMessage}: ${path}`, { code, exitCode, details: error instanceof Error ? error.message : String(error) });
+    }
+    return parseJsonInput(text, `${path} must contain valid JSON`);
+}
+function parseJsonResponse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`invalid JSON response: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.GateInvalidResponse,
+            exitCode: ExitCodes.Error,
+            details: text,
+        });
+    }
+}
+function normalizeOutput(value) {
+    if (value === null)
+        return null;
+    const record = recordValue(value);
+    if (!record)
+        return { content: value };
+    return { content: record.content, basis: Array.isArray(record.basis) ? record.basis : undefined };
+}
+function splitCsv(value) {
+    return value.split(',').map((item) => item.trim()).filter(Boolean);
+}
+function parallelBaseUrl() {
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_PARALLEL_URL)
+        return process.env.ESCLI_TEST_PARALLEL_URL;
+    return API_BASE;
+}
+function gateUrl() {
+    return process.env.ESCLI_GATE_URL ?? 'https://internal.eightstate.co';
+}
+function configDir() {
+    return process.env.ESCLI_CONFIG_DIR ?? join(homedir(), '.escli');
+}
+function ownersPath() {
+    return join(configDir(), 'parallel-run-owners.json');
+}
+function recallRunOwner(runId) {
+    try {
+        const owners = recordValue(JSON.parse(readFileSync(ownersPath(), 'utf8')));
+        return stringValue(owners?.[runId]);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function rememberRunOwner(runId, fingerprint) {
+    if (!runId || !fingerprint || fingerprint === 'env')
+        return;
+    try {
+        await mkdir(configDir(), { recursive: true });
+        let owners = {};
+        try {
+            owners = recordValue(JSON.parse(readFileSync(ownersPath(), 'utf8'))) ?? {};
+        }
+        catch {
+            owners = {};
+        }
+        owners[runId] = fingerprint;
+        const entries = Object.entries(owners).slice(-500);
+        await writeFile(ownersPath(), JSON.stringify(Object.fromEntries(entries)), 'utf8');
+    }
+    catch {
+        // Owner cache is a best-effort parity affordance; task success must not depend on it.
+    }
+}
+function pollIntervalMs() {
+    return Math.max(1, Number(process.env.ESCLI_RESEARCH_POLL_INTERVAL_MS ?? DEFAULT_POLL_INTERVAL_MS));
+}
+function pollMaxMs(timeoutSeconds) {
+    if (typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) {
+        const value = Number(process.env.ESCLI_RESEARCH_MAX_POLL_MS);
+        if (Number.isFinite(value) && value > 0)
+            return Math.max(1, value);
+    }
+    return timeoutSeconds ? Math.max(1, timeoutSeconds * 1000) : DEFAULT_MAX_POLL_MS;
+}
+function timeoutMs(timeoutSeconds, defaultMs = DEFAULT_TIMEOUT_MS) {
+    return Math.max(1, timeoutSeconds ? timeoutSeconds * 1000 : defaultMs);
+}
+function sleep(ms) {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+function httpStatusError(status, message, details) {
+    const error = new Error(message);
+    error.status = status;
+    error.details = details;
+    return error;
+}
+function isHttpStatusError(error) {
+    return error instanceof Error && typeof error.status === 'number';
+}
+function mapHttpStatusError(error) {
+    const status = error.status;
+    if (status === 401)
+        return new EscliError(error.message, { code: ErrorCode.ApiUnauthorized, details: error.details });
+    if (status === 403)
+        return new EscliError(error.message, { code: ErrorCode.ApiForbidden, details: error.details });
+    if (status === 404)
+        return new EscliError(error.message, { code: ErrorCode.ResearchRunNotFound, details: error.details });
+    if (status === 429)
+        return new EscliError(error.message, { code: ErrorCode.ApiRateLimited, details: error.details });
+    if (status >= 500)
+        return new EscliError(error.message, { code: ErrorCode.ServiceUnavailable, details: error.details });
+    return new EscliError(error.message, { code: ErrorCode.ResearchTaskFailed, details: error.details });
+}
+function mapNetworkError(error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError';
+    return new EscliError(isAbort ? 'network error: request timed out' : `network error: ${error instanceof Error ? error.message : String(error)}`, {
+        code: isAbort ? ErrorCode.NetworkTimeout : ErrorCode.NetworkError,
+        details: error instanceof Error ? error.message : error,
+    });
+}
+function formatHttpError(status, body) {
+    const parsed = parseMaybeJson(body);
+    const extracted = extractErrorMessage(parsed) ?? (typeof parsed === 'string' ? parsed : undefined);
+    return extracted ? `API error (${status}): ${extracted}` : `API error (${status})`;
+}
+function parseMaybeJson(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function extractErrorMessage(body) {
+    const root = recordValue(body);
+    const error = recordValue(root?.error);
+    return stringValue(root?.error) ?? stringValue(root?.message) ?? stringValue(error?.message) ?? stringValue(error?.detail);
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=research.js.map

package/dist/services/search.js

@@ -0,0 +1,195 @@
+import { randomUUID } from 'node:crypto';
+import { ErrorCode } from '@eightstate/contracts/errors';
+import { ExitCodes } from '@eightstate/contracts/exit-codes';
+import { EscliError } from '../lib/escli-error.js';
+import { callWithRetry } from './credentials.js';
+const REST_ENDPOINT = 'https://api.parallel.ai/v1';
+const MCP_ENDPOINT = 'https://search.parallel.ai/mcp';
+const DEFAULT_TIMEOUT_MS = 60_000;
+export async function searchWeb(options) {
+    const started = Date.now();
+    const queries = options.queries && options.queries.length > 0 ? options.queries : [options.objective];
+    const payload = await searchPayload({ ...options, queries });
+    const results = normalizeResults(recordValue(payload)?.results);
+    return {
+        elapsed_seconds: roundElapsed((Date.now() - started) / 1000),
+        results,
+        count: results.length,
+    };
+}
+async function searchPayload(options) {
+    const explicitKey = process.env.PARALLEL_API_KEY;
+    if (explicitKey)
+        return restSearch(options, { apiKey: explicitKey, fingerprint: 'env' });
+    try {
+        const response = await callWithRetry('parallel', (key) => restSearch(options, key));
+        if (response !== null)
+            return response;
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.name === 'ServiceCallError'))
+            throw error;
+    }
+    return mcpSearch(options);
+}
+async function restSearch(options, key) {
+    const response = await requestText(`${parallelBaseUrl()}/v1/search`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-api-key': key.apiKey },
+        body: JSON.stringify({ objective: options.objective, search_queries: options.queries }),
+        timeoutMs: timeoutMs(options.timeoutSeconds),
+    });
+    return parseJsonResponse(response);
+}
+async function mcpSearch(options) {
+    const args = { objective: options.objective, search_queries: options.queries, session_id: randomUUID().replaceAll('-', '') };
+    const response = await requestText(parallelMcpUrl(), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'web_search', arguments: args } }),
+        timeoutMs: timeoutMs(options.timeoutSeconds),
+    });
+    const data = recordValue(parseJsonResponse(response));
+    const error = recordValue(data?.error);
+    if (error)
+        throw new EscliError(stringValue(error.message) ?? 'MCP error', { code: ErrorCode.SearchFailed });
+    const result = recordValue(data?.result);
+    const content = arrayValue(result?.content);
+    for (const item of content) {
+        const record = recordValue(item);
+        if (record?.type === 'text' && typeof record.text === 'string')
+            return parseMcpTextContent(record.text);
+    }
+    return result ?? data;
+}
+async function requestText(url, options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: options.method,
+            headers: options.headers,
+            body: options.body,
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok)
+            throw httpStatusError(response.status, formatHttpError(response.status, text), text);
+        return text;
+    }
+    catch (error) {
+        if (isHttpStatusError(error))
+            throw mapHttpStatusError(error);
+        throw mapNetworkError(error);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function parseJsonResponse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new EscliError(`invalid JSON response: ${error instanceof Error ? error.message : String(error)}`, {
+            code: ErrorCode.GateInvalidResponse,
+            exitCode: ExitCodes.Error,
+            details: text,
+        });
+    }
+}
+function parseMcpTextContent(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
+function normalizeResults(results) {
+    if (!Array.isArray(results))
+        return [];
+    return results
+        .map((item) => recordValue(item))
+        .filter((item) => Boolean(item))
+        .map((item) => ({
+        title: String(item.title ?? ''),
+        url: String(item.url ?? ''),
+        excerpts: Array.isArray(item.excerpts) ? item.excerpts.map(String) : [],
+    }));
+}
+function parallelBaseUrl() {
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_PARALLEL_URL)
+        return process.env.ESCLI_TEST_PARALLEL_URL;
+    return REST_ENDPOINT.replace(/\/v1$/u, '');
+}
+function parallelMcpUrl() {
+    if ((typeof __ESCLI_TEST__ === 'undefined' || __ESCLI_TEST__) && process.env.ESCLI_TEST_PARALLEL_URL)
+        return `${process.env.ESCLI_TEST_PARALLEL_URL}/mcp`;
+    return MCP_ENDPOINT;
+}
+function timeoutMs(timeoutSeconds) {
+    const seconds = timeoutSeconds ?? DEFAULT_TIMEOUT_MS / 1000;
+    return Math.max(1, seconds) * 1000;
+}
+function roundElapsed(seconds) {
+    return Math.round(seconds * 10) / 10;
+}
+function httpStatusError(status, message, details) {
+    const error = new Error(message);
+    error.status = status;
+    error.details = details;
+    return error;
+}
+function isHttpStatusError(error) {
+    return error instanceof Error && typeof error.status === 'number';
+}
+function mapHttpStatusError(error) {
+    const status = error.status;
+    if (status === 401)
+        return new EscliError(error.message, { code: ErrorCode.ApiUnauthorized, details: error.details });
+    if (status === 403)
+        return new EscliError(error.message, { code: ErrorCode.ApiForbidden, details: error.details });
+    if (status === 404)
+        return new EscliError(error.message, { code: ErrorCode.ApiError, exitCode: ExitCodes.NotFound, details: error.details });
+    if (status === 429)
+        return new EscliError(error.message, { code: ErrorCode.ApiRateLimited, details: error.details });
+    if (status >= 500)
+        return new EscliError(error.message, { code: ErrorCode.ServiceUnavailable, details: error.details });
+    return new EscliError(error.message, { code: ErrorCode.SearchFailed, details: error.details });
+}
+function mapNetworkError(error) {
+    const isAbort = error instanceof Error && error.name === 'AbortError';
+    return new EscliError(isAbort ? 'network error: request timed out' : `network error: ${error instanceof Error ? error.message : String(error)}`, {
+        code: isAbort ? ErrorCode.NetworkTimeout : ErrorCode.NetworkError,
+        details: error instanceof Error ? error.message : error,
+    });
+}
+function formatHttpError(status, body) {
+    const parsed = parseMaybeJson(body);
+    const extracted = extractErrorMessage(parsed) ?? (typeof parsed === 'string' ? parsed : undefined);
+    return extracted ? `API error (${status}): ${extracted}` : `API error (${status})`;
+}
+function parseMaybeJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function extractErrorMessage(body) {
+    const root = recordValue(body);
+    return stringValue(root?.error) ?? stringValue(root?.message) ?? stringValue(recordValue(root?.error)?.message);
+}
+function arrayValue(value) {
+    return Array.isArray(value) ? value : [];
+}
+function recordValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=search.js.map