@tiangong-ai/cli 0.0.20 → 0.0.21

package/dist/research/workspace/broker.js

@@ -1,13 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { readFile, writeFile } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { dirname } from "node:path";
 import { CliError } from "../../errors.js";
 import { loadCapabilityDeclarations, verifyCapabilities } from "./capabilities.js";
+import { loadBrokerEvidenceCache, persistBrokerEvidence, storeBrokerEvidenceCache, } from "./evidence.js";
 import { appendJournalEvent } from "./journal.js";
-import { ensureDirectory, isObject, pathExists, sha256Bytes, sha256Text, workspacePaths, } from "./storage.js";
+import { sanitizeResearchRecord, sanitizeResearchText } from "./sanitization.js";
+import { canonicalJson, ensureDirectory, isObject, pathExists, resolveContained, sha256Text, workspacePaths, } from "./storage.js";
+import { loadWorkspaceConfig } from "./workspace.js";
 const MAX_REQUEST_BYTES = 1024 * 1024;
-const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+const MAX_ERROR_RESPONSE_BYTES = 16 * 1024;
+const BROKER_CONTEXT_BYTES_PER_TOKEN = 3;
 export async function startCapabilityBroker(root, projectId, capsuleProject) {
     const declarations = await loadCapabilityDeclarations(root);
     const networkCapabilities = declarations.capabilities.filter((capability) => capability.permissions.includes("brokered-network"));
@@ -22,6 +26,7 @@ export async function startCapabilityBroker(root, projectId, capsuleProject) {
         });
     }
     const credentialMap = await loadCredentialMap(root, declarations.capabilities);
+    const config = await loadWorkspaceConfig(root);
     const routeToken = randomUUID().replaceAll("-", "");
     const route = `/mcp/${routeToken}`;
     const server = createServer((request, response) => {
@@ -34,6 +39,9 @@ export async function startCapabilityBroker(root, projectId, capsuleProject) {
             capsuleProject,
             capabilities: networkCapabilities,
             credentialMap,
+            workspaceResponseBytes: config.budget.maxBrokerResponseBytes,
+            workspaceContextTokens: config.budget.maxBrokerContextTokens,
+            workspaceMaxItems: config.budget.maxBrokerItems,
         });
     });
     await new Promise((resolvePromise, reject) => {
@@ -80,7 +88,7 @@ async function handleMcpRequest(input) {
                 tools: [
                     {
                         name: "fetch_candidate_source",
-                        description: "Fetch one HTTPS candidate source through a locked capability and record a value-free receipt.",
+                        description: "Fetch one bounded HTTPS candidate source through a locked capability, persist the raw response, and return content-addressed provenance plus a bounded context view.",
                         inputSchema: {
                             type: "object",
                             additionalProperties: false,
@@ -89,6 +97,10 @@ async function handleMcpRequest(input) {
                                 capability_id: { type: "string" },
                                 credential_id: { type: "string" },
                                 url: { type: "string" },
+                                json_pointer: { type: "string" },
+                                item_offset: { type: "integer", minimum: 0 },
+                                max_items: { type: "integer", minimum: 1 },
+                                cache_mode: { enum: ["prefer", "bypass"] },
                             },
                         },
                     },
@@ -111,6 +123,9 @@ async function handleMcpRequest(input) {
                     capsuleProject: input.capsuleProject,
                     capabilities: input.capabilities,
                     credentialMap: input.credentialMap,
+                    workspaceResponseBytes: input.workspaceResponseBytes,
+                    workspaceContextTokens: input.workspaceContextTokens,
+                    workspaceMaxItems: input.workspaceMaxItems,
                     arguments: params.arguments,
                 });
                 sendRpcResult(input.response, body, {
@@ -118,7 +133,12 @@ async function handleMcpRequest(input) {
                 });
             }
             catch (error) {
-                sendToolError(input.response, body, error instanceof Error ? error.message : String(error));
+                const detail = error instanceof CliError
+                    ? JSON.stringify({ code: error.code, message: error.message, details: error.details })
+                    : error instanceof Error
+                        ? error.message
+                        : String(error);
+                sendToolError(input.response, body, sanitizeResearchText(detail, [...input.credentialMap.values()]));
             }
             return;
         }
@@ -126,7 +146,9 @@ async function handleMcpRequest(input) {
     }
     catch (error) {
         sendJson(input.response, 500, {
-            error: error instanceof Error ? error.message : String(error),
+            error: sanitizeResearchText(error instanceof Error ? error.message : String(error), [
+                ...input.credentialMap.values(),
+            ]),
         });
     }
 }
@@ -134,37 +156,96 @@ async function fetchCandidateSource(input) {
     const capabilityId = input.arguments.capability_id;
     const credentialId = input.arguments.credential_id;
     const rawUrl = input.arguments.url;
+    const jsonPointer = input.arguments.json_pointer;
+    const requestedItemOffset = input.arguments.item_offset ?? 0;
+    const requestedMaxItems = input.arguments.max_items;
+    const cacheMode = input.arguments.cache_mode ?? "prefer";
     if (typeof capabilityId !== "string" || typeof rawUrl !== "string") {
         throw new Error("capability_id and url are required strings");
     }
     if (credentialId !== undefined && typeof credentialId !== "string") {
         throw new Error("credential_id must be a string when provided");
     }
+    if (jsonPointer !== undefined &&
+        (typeof jsonPointer !== "string" || !validJsonPointer(jsonPointer))) {
+        throw new Error("json_pointer must be an RFC 6901 JSON Pointer when provided");
+    }
+    if (typeof requestedItemOffset !== "number" ||
+        !Number.isInteger(requestedItemOffset) ||
+        requestedItemOffset < 0) {
+        throw new Error("item_offset must be a non-negative integer when provided");
+    }
+    if (requestedMaxItems !== undefined &&
+        (typeof requestedMaxItems !== "number" ||
+            !Number.isInteger(requestedMaxItems) ||
+            requestedMaxItems < 1)) {
+        throw new Error("max_items must be a positive integer when provided");
+    }
+    if (cacheMode !== "prefer" && cacheMode !== "bypass") {
+        throw new Error('cache_mode must be "prefer" or "bypass"');
+    }
     const capability = input.capabilities.find((candidate) => candidate.id === capabilityId);
     if (!capability)
         throw new Error(`capability is not admitted for brokered network: ${capabilityId}`);
     const target = validateHttpsUrl(rawUrl);
+    if (!capability.http)
+        throw new Error(`capability has no broker HTTP policy: ${capabilityId}`);
     const credential = credentialId
         ? capability.credentials.find((candidate) => candidate.id === credentialId)
         : undefined;
     if (credentialId && !credential) {
         throw new Error(`credential is not declared by capability ${capabilityId}: ${credentialId}`);
     }
+    if (credential && cacheMode === "prefer") {
+        throw new Error("credentialed broker requests require cache_mode=bypass");
+    }
     assertAllowedHost(target, capability.allowedHosts, "capability");
     if (credential)
         assertAllowedHost(target, credential.allowedHosts, "credential");
     const attemptId = randomUUID();
+    const maxItems = Math.min(requestedMaxItems ?? capability.http.maxItems, capability.http.maxItems, input.workspaceMaxItems);
+    const cacheKeySha256 = sha256Text(canonicalJson({
+        capabilityId,
+        targetSha256: sha256Text(target.toString()),
+        accept: capability.http.accept,
+    }));
     await appendJournalEvent(workspacePaths(input.root).journal, "capability.fetch.attempted", input.projectId, {
         attemptId,
         projectId: input.projectId,
         capabilityId,
         credentialId: credentialId ?? null,
         targetSha256: sha256Text(target.toString()),
+        cacheMode,
+        cacheKeySha256,
     });
     try {
-        const headers = new Headers({
-            Accept: "text/plain, application/json, text/html;q=0.9, */*;q=0.1",
-        });
+        if (cacheMode === "prefer") {
+            const cached = await loadBrokerEvidenceCache(input.root, cacheKeySha256);
+            if (cached) {
+                const raw = await readFile(resolveContained(workspacePaths(input.root).control, cached.locator));
+                const context = buildContextView(raw, cached.contentType, jsonPointer, requestedItemOffset, maxItems, input.workspaceContextTokens * BROKER_CONTEXT_BYTES_PER_TOKEN);
+                const receipt = await persistBrokerEvidence(input.root, {
+                    attemptId,
+                    projectId: input.projectId,
+                    capabilityId,
+                    credentialId: null,
+                    status: cached.status,
+                    contentType: cached.contentType,
+                    sourceSha256: cached.sourceSha256,
+                    contextItems: context.items,
+                    contextOffset: context.offset,
+                    contextTotalItems: context.totalItems,
+                    contextNextOffset: context.nextOffset,
+                    contextTruncated: context.truncated,
+                    retrievedAt: cached.retrievedAt,
+                    cacheHit: true,
+                }, raw, context.bytes);
+                await stageContextObject(input.capsuleProject, receipt.contextLocator, context.bytes);
+                await appendCompletedReceipt(input.root, input.projectId, receipt, cacheKeySha256);
+                return { ...receipt };
+            }
+        }
+        const headers = new Headers({ Accept: capability.http.accept });
         if (credential) {
             const value = input.credentialMap.get(credential.id);
             if (!value)
@@ -172,50 +253,151 @@ async function fetchCandidateSource(input) {
             headers.set(credential.headerName, `${credential.prefix}${value}`);
         }
         const { response, finalUrl } = await fetchWithRedirectPolicy(target, headers, capability.allowedHosts, credential?.allowedHosts);
+        const responseLimit = Math.min(capability.http.maxResponseBytes, input.workspaceResponseBytes);
         const announcedLength = Number(response.headers.get("content-length") ?? "0");
-        if (announcedLength > MAX_RESPONSE_BYTES)
+        if (response.ok && announcedLength > responseLimit)
             throw new Error("response exceeds the broker size limit");
-        const bytes = await readBoundedResponseBody(response);
+        const bytes = await readBoundedResponseBody(response, response.ok ? responseLimit : Math.min(responseLimit, MAX_ERROR_RESPONSE_BYTES), !response.ok);
         for (const secret of input.credentialMap.values()) {
             if (bytes.includes(Buffer.from(secret, "utf8"))) {
                 throw new Error("response failed credential disclosure screening");
             }
         }
-        if (!response.ok)
-            throw new Error(`HTTPS source returned status ${response.status}`);
         const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim() ?? "application/octet-stream";
-        const extension = contentType.includes("json")
-            ? "json"
-            : contentType.startsWith("text/")
-                ? "txt"
-                : "bin";
-        const destination = join(input.capsuleProject, "inputs", "broker", `${attemptId}.${extension}`);
-        await ensureDirectory(join(input.capsuleProject, "inputs", "broker"));
-        await writeFile(destination, bytes, { mode: 0o600 });
-        const receipt = {
+        if (!response.ok) {
+            const retryAfterSeconds = parseRetryAfter(response.headers.get("retry-after"));
+            const excerpt = safeResponseExcerpt(bytes, contentType, [...input.credentialMap.values()]);
+            throw new CliError(`HTTPS source returned status ${response.status}.`, {
+                code: "RESEARCH_BROKER_HTTP_ERROR",
+                exitCode: 3,
+                details: {
+                    status: response.status,
+                    retryAfterSeconds,
+                    responseExcerpt: excerpt,
+                    requestId: safeResponseId(response.headers),
+                },
+            });
+        }
+        if (!contentTypeAllowed(contentType, capability.http.allowedContentTypes)) {
+            throw new CliError(`HTTPS source returned unsupported content type ${contentType}.`, {
+                code: "RESEARCH_BROKER_CONTENT_TYPE_INVALID",
+                exitCode: 3,
+                details: { contentType, allowedContentTypes: capability.http.allowedContentTypes },
+            });
+        }
+        assertNoSensitiveResponseMaterial(bytes, contentType);
+        const context = buildContextView(bytes, contentType, jsonPointer, requestedItemOffset, maxItems, input.workspaceContextTokens * BROKER_CONTEXT_BYTES_PER_TOKEN);
+        const receipt = await persistBrokerEvidence(input.root, {
             attemptId,
+            projectId: input.projectId,
             capabilityId,
             credentialId: credentialId ?? null,
             status: response.status,
             contentType,
-            bytes: bytes.length,
-            sha256: sha256Bytes(bytes),
             sourceSha256: sha256Text(finalUrl.toString()),
-            path: relative(input.capsuleProject, destination).replaceAll("\\", "/"),
-        };
-        await appendJournalEvent(workspacePaths(input.root).journal, "capability.fetch.completed", input.projectId, receipt);
-        return receipt;
+            contextItems: context.items,
+            contextOffset: context.offset,
+            contextTotalItems: context.totalItems,
+            contextNextOffset: context.nextOffset,
+            contextTruncated: context.truncated,
+            retrievedAt: new Date().toISOString(),
+            cacheHit: false,
+        }, bytes, context.bytes);
+        await stageContextObject(input.capsuleProject, receipt.contextLocator, context.bytes);
+        if (!credential)
+            await storeBrokerEvidenceCache(input.root, cacheKeySha256, receipt);
+        await appendCompletedReceipt(input.root, input.projectId, receipt, cacheKeySha256);
+        return { ...receipt };
     }
     catch (error) {
+        const safeDetails = error instanceof CliError && isObject(error.details)
+            ? sanitizeResearchRecord(error.details, [...input.credentialMap.values()])
+            : {};
         await appendJournalEvent(workspacePaths(input.root).journal, "capability.fetch.failed", input.projectId, {
             attemptId,
             capabilityId,
             credentialId: credentialId ?? null,
-            error: bounded(error instanceof Error ? error.message : String(error), 500),
+            error: bounded(sanitizeResearchText(error instanceof Error ? error.message : String(error), [
+                ...input.credentialMap.values(),
+            ]), 500),
+            failureKind: brokerFailureKind(error),
+            ...safeDetails,
         });
         throw error;
     }
 }
+function assertNoSensitiveResponseMaterial(bytes, contentType) {
+    if (!contentType.includes("json") && !contentType.startsWith("text/"))
+        return;
+    const text = bytes.toString("utf8");
+    if (/\b(Bearer|Basic)\s+[A-Za-z0-9._~+\/-]+=*/i.test(text) ||
+        /\b(authorization|cookie|set-cookie|x-api-key|api-key)\s*:/i.test(text) ||
+        /\b(access_token|api[_-]?key|apikey|password|secret|session|token)\s*=/i.test(text)) {
+        throw new Error("response contains credential-like material and was not persisted");
+    }
+    if (!contentType.includes("json"))
+        return;
+    try {
+        const value = JSON.parse(text);
+        if (containsSensitiveJsonField(value)) {
+            throw new Error("response contains credential-like material and was not persisted");
+        }
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return;
+        throw error;
+    }
+}
+function containsSensitiveJsonField(value) {
+    if (Array.isArray(value))
+        return value.some(containsSensitiveJsonField);
+    if (!isObject(value))
+        return false;
+    const sensitive = /^(access_token|api[_-]?key|apikey|authorization|cookie|password|secret|session|token)$/i;
+    return Object.entries(value).some(([key, item]) => (sensitive.test(key) && item !== null && item !== "") || containsSensitiveJsonField(item));
+}
+async function stageContextObject(capsuleProject, locator, bytes) {
+    const destination = resolveContained(capsuleProject, locator);
+    await ensureDirectory(dirname(destination));
+    try {
+        await writeFile(destination, bytes, { mode: 0o600, flag: "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        if (!Buffer.from(await readFile(destination)).equals(Buffer.from(bytes))) {
+            throw new Error("staged broker context object failed its integrity check");
+        }
+    }
+}
+async function appendCompletedReceipt(root, projectId, receipt, cacheKeySha256) {
+    await appendJournalEvent(workspacePaths(root).journal, "capability.fetch.completed", projectId, {
+        attemptId: receipt.attemptId,
+        projectId: receipt.projectId,
+        capabilityId: receipt.capabilityId,
+        credentialId: receipt.credentialId,
+        status: receipt.status,
+        contentType: receipt.contentType,
+        bytes: receipt.bytes,
+        sha256: receipt.sha256,
+        sourceSha256: receipt.sourceSha256,
+        locator: receipt.locator,
+        contextLocator: receipt.contextLocator,
+        contextSha256: receipt.contextSha256,
+        contextBytes: receipt.contextBytes,
+        contextEstimatedTokens: receipt.contextEstimatedTokens,
+        contextItems: receipt.contextItems,
+        contextOffset: receipt.contextOffset ?? 0,
+        contextTotalItems: receipt.contextTotalItems ?? null,
+        contextNextOffset: receipt.contextNextOffset ?? null,
+        contextTruncated: receipt.contextTruncated,
+        retrievedAt: receipt.retrievedAt,
+        servedAt: receipt.servedAt,
+        cacheHit: receipt.cacheHit,
+        cacheKeySha256,
+    });
+}
 async function loadCredentialMap(root, capabilities) {
     const path = workspacePaths(root).env;
     if (!(await pathExists(path)))
@@ -280,7 +462,7 @@ function assertAllowedHost(url, allowedHosts, scope) {
         throw new Error(`target host is outside ${scope} scope: ${url.host}`);
     }
 }
-async function readBoundedResponseBody(response) {
+async function readBoundedResponseBody(response, maxBytes, truncate = false) {
     if (!response.body)
         return Buffer.alloc(0);
     const reader = response.body.getReader();
@@ -293,8 +475,14 @@ async function readBoundedResponseBody(response) {
                 break;
             const chunk = Buffer.from(result.value);
             bytes += chunk.length;
-            if (bytes > MAX_RESPONSE_BYTES) {
+            if (bytes > maxBytes) {
                 await reader.cancel();
+                if (truncate) {
+                    const remaining = maxBytes - chunks.reduce((sum, item) => sum + item.length, 0);
+                    if (remaining > 0)
+                        chunks.push(chunk.subarray(0, remaining));
+                    break;
+                }
                 throw new Error("response exceeds the broker size limit");
             }
             chunks.push(chunk);
@@ -305,6 +493,194 @@ async function readBoundedResponseBody(response) {
     }
     return Buffer.concat(chunks);
 }
+function buildContextView(bytes, contentType, jsonPointer, itemOffset, maxItems, maxContextBytes) {
+    if (!Number.isInteger(maxContextBytes) || maxContextBytes < 1) {
+        throw new Error("broker context byte limit is invalid");
+    }
+    if (!contentType.includes("json")) {
+        if (itemOffset !== 0)
+            throw new Error("item_offset is supported only for JSON collections");
+        const boundedBytes = contentType.startsWith("text/")
+            ? truncateUtf8(bytes, maxContextBytes)
+            : bytes.subarray(0, maxContextBytes);
+        return {
+            bytes: boundedBytes,
+            items: null,
+            offset: 0,
+            totalItems: null,
+            nextOffset: null,
+            truncated: boundedBytes.byteLength < bytes.byteLength,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("JSON response body is not valid JSON");
+    }
+    const selected = jsonPointer === undefined ? parsed : resolveJsonPointer(parsed, jsonPointer);
+    if (Array.isArray(selected)) {
+        const limited = [];
+        for (const item of selected.slice(itemOffset, itemOffset + maxItems)) {
+            const candidate = [...limited, item];
+            if (jsonBytes(candidate).byteLength > maxContextBytes)
+                break;
+            limited.push(item);
+        }
+        const nextOffset = itemOffset + limited.length < selected.length ? itemOffset + limited.length : null;
+        return {
+            bytes: jsonBytes(limited),
+            items: limited.length,
+            offset: itemOffset,
+            totalItems: selected.length,
+            nextOffset,
+            truncated: itemOffset > 0 || nextOffset !== null,
+        };
+    }
+    if (isObject(selected)) {
+        const entries = Object.entries(selected);
+        const limited = [];
+        for (const entry of entries.slice(itemOffset, itemOffset + maxItems)) {
+            const candidate = [...limited, entry];
+            if (jsonBytes(Object.fromEntries(candidate)).byteLength > maxContextBytes)
+                break;
+            limited.push(entry);
+        }
+        const nextOffset = itemOffset + limited.length < entries.length ? itemOffset + limited.length : null;
+        return {
+            bytes: jsonBytes(Object.fromEntries(limited)),
+            items: limited.length,
+            offset: itemOffset,
+            totalItems: entries.length,
+            nextOffset,
+            truncated: itemOffset > 0 || nextOffset !== null,
+        };
+    }
+    if (itemOffset !== 0)
+        throw new Error("item_offset is supported only for JSON collections");
+    const encoded = jsonBytes(selected);
+    if (encoded.byteLength <= maxContextBytes) {
+        return {
+            bytes: encoded,
+            items: 1,
+            offset: 0,
+            totalItems: 1,
+            nextOffset: null,
+            truncated: false,
+        };
+    }
+    if (typeof selected !== "string") {
+        throw new Error("selected JSON scalar exceeds the broker context token limit");
+    }
+    const characters = [...selected];
+    let lower = 0;
+    let upper = characters.length;
+    while (lower < upper) {
+        const middle = Math.ceil((lower + upper) / 2);
+        if (jsonBytes(characters.slice(0, middle).join("")).byteLength <= maxContextBytes) {
+            lower = middle;
+        }
+        else {
+            upper = middle - 1;
+        }
+    }
+    return {
+        bytes: jsonBytes(characters.slice(0, lower).join("")),
+        items: 1,
+        offset: 0,
+        totalItems: 1,
+        nextOffset: null,
+        truncated: true,
+    };
+}
+function jsonBytes(value) {
+    return Buffer.from(`${JSON.stringify(value)}\n`, "utf8");
+}
+function truncateUtf8(bytes, maxBytes) {
+    if (bytes.byteLength <= maxBytes)
+        return bytes;
+    let end = maxBytes;
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    while (end > 0) {
+        const candidate = bytes.subarray(0, end);
+        try {
+            decoder.decode(candidate);
+            return Buffer.from(candidate);
+        }
+        catch {
+            end -= 1;
+        }
+    }
+    return Buffer.alloc(0);
+}
+function resolveJsonPointer(value, pointer) {
+    if (pointer === "")
+        return value;
+    let selected = value;
+    for (const rawPart of pointer.slice(1).split("/")) {
+        const part = rawPart.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (Array.isArray(selected) &&
+            /^(0|[1-9][0-9]*)$/.test(part) &&
+            Number(part) < selected.length) {
+            selected = selected[Number(part)];
+        }
+        else if (isObject(selected) && Object.hasOwn(selected, part)) {
+            selected = selected[part];
+        }
+        else {
+            throw new Error("json_pointer does not resolve within the response");
+        }
+    }
+    return selected;
+}
+function validJsonPointer(value) {
+    return value === "" || (value.startsWith("/") && !/~(?:[^01]|$)/.test(value));
+}
+function contentTypeAllowed(contentType, allowed) {
+    const normalized = contentType.toLowerCase();
+    return allowed.some((pattern) => {
+        const candidate = pattern.toLowerCase();
+        if (candidate === "*/*" || candidate === normalized)
+            return true;
+        const escaped = candidate.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+        return new RegExp(`^${escaped}$`).test(normalized);
+    });
+}
+function safeResponseExcerpt(bytes, contentType, secrets) {
+    if (!contentType.includes("json") && !contentType.startsWith("text/")) {
+        return `[${bytes.length} non-text byte(s)]`;
+    }
+    return bounded(sanitizeResearchText(bytes.toString("utf8"), secrets).replace(/\s+/g, " "), 1000);
+}
+function safeResponseId(headers) {
+    for (const name of ["x-request-id", "request-id", "x-amzn-requestid", "cf-ray"]) {
+        const value = headers.get(name)?.trim();
+        if (value && /^[A-Za-z0-9._:-]{1,200}$/.test(value))
+            return value;
+    }
+    return null;
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.ceil(seconds);
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, Math.ceil((date - Date.now()) / 1000)) : null;
+}
+function brokerFailureKind(error) {
+    if (error instanceof CliError && error.code === "RESEARCH_BROKER_HTTP_ERROR") {
+        const status = isObject(error.details) ? error.details.status : undefined;
+        if (status === 429)
+            return "rate-limit";
+        if (typeof status === "number" && status >= 500)
+            return "server";
+        return "deterministic";
+    }
+    return error instanceof TypeError ? "transient" : "deterministic";
+}
 function validateHttpsUrl(value) {
     const url = new URL(value);
     if (url.protocol !== "https:" || url.username || url.password || !url.hostname) {