@ouro.bot/cli 0.1.0-alpha.5 → 0.1.0-alpha.500

package/dist/repertoire/tools.js

@@ -1,29 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.teamsTools = exports.finalAnswerTool = exports.tools = void 0;
+exports.surfaceToolDef = exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
+exports.resetMcpDefinitions = resetMcpDefinitions;
 exports.getToolsForChannel = getToolsForChannel;
-exports.isConfirmationRequired = isConfirmationRequired;
 exports.execTool = execTool;
 exports.summarizeArgs = summarizeArgs;
+exports.buildToolResultSummary = buildToolResultSummary;
 const tools_base_1 = require("./tools-base");
 const tools_teams_1 = require("./tools-teams");
+const tools_bluebubbles_1 = require("./tools-bluebubbles");
 const ado_semantic_1 = require("./ado-semantic");
 const tools_github_1 = require("./tools-github");
+const tools_bundle_1 = require("./tools-bundle");
 const runtime_1 = require("../nerves/runtime");
+const guardrails_1 = require("./guardrails");
+const identity_1 = require("../heart/identity");
+const tools_surface_1 = require("./tools-surface");
+const mcp_tools_1 = require("./mcp-tools");
+function safeGetAgentRoot() {
+    try {
+        return (0, identity_1.getAgentRoot)();
+    }
+    catch {
+        return undefined;
+    }
+}
 // Re-export types and constants used by the rest of the codebase
 var tools_base_2 = require("./tools-base");
 Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_base_2.tools; } });
-Object.defineProperty(exports, "finalAnswerTool", { enumerable: true, get: function () { return tools_base_2.finalAnswerTool; } });
-var tools_teams_2 = require("./tools-teams");
-Object.defineProperty(exports, "teamsTools", { enumerable: true, get: function () { return tools_teams_2.teamsTools; } });
+Object.defineProperty(exports, "settleTool", { enumerable: true, get: function () { return tools_base_2.settleTool; } });
+Object.defineProperty(exports, "observeTool", { enumerable: true, get: function () { return tools_base_2.observeTool; } });
+Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_base_2.ponderTool; } });
+Object.defineProperty(exports, "restTool", { enumerable: true, get: function () { return tools_base_2.restTool; } });
+// Re-export surface tool schema for consumers (e.g. heart/core.ts)
+var tools_surface_2 = require("./tools-surface");
+Object.defineProperty(exports, "surfaceToolDef", { enumerable: true, get: function () { return tools_surface_2.surfaceToolDef; } });
 // All tool definitions in a single registry
-const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions];
-const REMOTE_BLOCKED_LOCAL_TOOLS = new Set(["shell", "read_file", "write_file", "git_commit", "gh_cli"]);
-function baseToolsForCapabilities(capabilities) {
-    const isRemoteChannel = capabilities?.channel === "teams";
-    if (!isRemoteChannel)
-        return tools_base_1.tools;
-    return tools_base_1.tools.filter((tool) => !REMOTE_BLOCKED_LOCAL_TOOLS.has(tool.function.name));
+const allDefinitions = [...tools_base_1.baseToolDefinitions, ...tools_bluebubbles_1.bluebubblesToolDefinitions, ...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions, ...tools_bundle_1.bundleToolDefinitions, tools_surface_1.surfaceToolDefinition];
+// MCP tool definitions — populated each time getToolsForChannel() is called with an mcpManager.
+// Kept separate from allDefinitions so execTool can find them.
+let mcpDefinitions = [];
+/** Exported for testing — reset the MCP definitions cache. */
+function resetMcpDefinitions() {
+    mcpDefinitions = [];
+}
+function baseToolsForCapabilities() {
+    // Use baseToolDefinitions at call time so dynamically-added tools are included
+    return tools_base_1.baseToolDefinitions.map((d) => d.tool);
 }
 // Apply a single tool preference to a tool schema, returning a new object.
 function applyPreference(tool, pref) {
@@ -35,48 +58,79 @@ function applyPreference(tool, pref) {
         },
     };
 }
+// Filter out tools whose requiredCapability is not in the provider's capability set.
+// Uses baseToolDefinitions at call time so dynamically-added tools are included.
+// Only base tools can have requiredCapability (integration tools do not).
+function filterByCapability(toolList, providerCapabilities) {
+    return toolList.filter((tool) => {
+        const def = tools_base_1.baseToolDefinitions.find((d) => d.tool.function.name === tool.function.name);
+        if (!def?.requiredCapability)
+            return true;
+        return providerCapabilities?.has(def.requiredCapability) === true;
+    });
+}
 // Return the appropriate tools list based on channel capabilities.
 // Base tools (no integration) are always included.
 // Teams/integration tools are included only if their integration is in availableIntegrations.
 // When toolPreferences is provided, matching preferences are appended to tool descriptions.
-function getToolsForChannel(capabilities, toolPreferences) {
-    const baseTools = baseToolsForCapabilities(capabilities);
+// When providerCapabilities is provided, tools with requiredCapability are filtered.
+function getToolsForChannel(capabilities, toolPreferences, _context, providerCapabilities, mcpManager, _chatModel) {
+    const baseTools = baseToolsForCapabilities();
+    const bluebubblesTools = capabilities?.channel === "bluebubbles"
+        ? tools_bluebubbles_1.bluebubblesToolDefinitions.map((d) => d.tool)
+        : [];
+    let result;
     if (!capabilities || capabilities.availableIntegrations.length === 0) {
-        return baseTools;
+        result = [...baseTools, ...bluebubblesTools];
     }
-    const available = new Set(capabilities.availableIntegrations);
-    const integrationDefs = [...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions].filter((d) => d.integration && available.has(d.integration));
-    if (!toolPreferences || Object.keys(toolPreferences).length === 0) {
-        return [...baseTools, ...integrationDefs.map((d) => d.tool)];
+    else {
+        const available = new Set(capabilities.availableIntegrations);
+        const channelDefs = [...tools_teams_1.teamsToolDefinitions, ...ado_semantic_1.adoSemanticToolDefinitions, ...tools_github_1.githubToolDefinitions];
+        // Include tools whose integration is available, plus channel tools with no integration gate (e.g. teams_send_message)
+        const integrationDefs = channelDefs.filter((d) => d.integration ? available.has(d.integration) : capabilities.channel === "teams");
+        if (!toolPreferences || Object.keys(toolPreferences).length === 0) {
+            result = [...baseTools, ...bluebubblesTools, ...integrationDefs.map((d) => d.tool)];
+        }
+        else {
+            // Build a map of integration -> preference text for fast lookup
+            const prefMap = new Map();
+            for (const [key, value] of Object.entries(toolPreferences)) {
+                prefMap.set(key, value);
+            }
+            // Apply preferences to matching integration tools (new objects, no mutation)
+            // d.integration is guaranteed truthy -- integrationDefs are pre-filtered above
+            const enrichedIntegrationTools = integrationDefs.map((d) => {
+                const pref = prefMap.get(d.integration);
+                return pref ? applyPreference(d.tool, pref) : d.tool;
+            });
+            result = [...baseTools, ...bluebubblesTools, ...enrichedIntegrationTools];
+        }
     }
-    // Build a map of integration -> preference text for fast lookup
-    const prefMap = new Map();
-    for (const [key, value] of Object.entries(toolPreferences)) {
-        prefMap.set(key, value);
+    // Append first-class MCP tools when mcpManager is provided
+    if (mcpManager) {
+        mcpDefinitions = (0, mcp_tools_1.mcpToolsAsDefinitions)(mcpManager);
+        const mcpSchemas = mcpDefinitions.map((d) => d.tool);
+        result = [...result, ...mcpSchemas];
     }
-    // Apply preferences to matching integration tools (new objects, no mutation)
-    // d.integration is guaranteed truthy -- integrationDefs are pre-filtered above
-    const enrichedIntegrationTools = integrationDefs.map((d) => {
-        const pref = prefMap.get(d.integration);
-        return pref ? applyPreference(d.tool, pref) : d.tool;
-    });
-    return [...baseTools, ...enrichedIntegrationTools];
+    return filterByCapability(result, providerCapabilities);
+}
+// Look up a tool definition from the combined registry (native + MCP).
+function findDefinition(toolName) {
+    return allDefinitions.find((d) => d.tool.function.name === toolName)
+        ?? mcpDefinitions.find((d) => d.tool.function.name === toolName);
 }
-// Check whether a tool requires user confirmation before execution.
-// Reads from ToolDefinition.confirmationRequired instead of a separate Set.
-function isConfirmationRequired(toolName) {
-    const def = allDefinitions.find((d) => d.tool.function.name === toolName);
-    return def?.confirmationRequired === true;
+function normalizeGuardArgs(_name, args) {
+    return args;
 }
 async function execTool(name, args, ctx) {
     (0, runtime_1.emitNervesEvent)({
         event: "tool.start",
         component: "tools",
         message: "tool execution started",
-        meta: { name },
+        meta: { name, ...(name === "shell" && args.command ? { command: args.command } : {}) },
     });
-    // Look up from combined registry
-    const def = allDefinitions.find((d) => d.tool.function.name === name);
+    // Look up from combined registry (native + MCP)
+    const def = findDefinition(name);
     if (!def) {
         (0, runtime_1.emitNervesEvent)({
             level: "error",
@@ -87,17 +141,26 @@ async function execTool(name, args, ctx) {
         });
         return `unknown: ${name}`;
     }
-    const isRemoteChannel = ctx?.context?.channel?.channel === "teams";
-    if (isRemoteChannel && REMOTE_BLOCKED_LOCAL_TOOLS.has(name)) {
-        const message = "I can't do that from here because I'm talking to multiple people in a shared remote channel, and local shell/file/git/gh operations could let conversations interfere with each other. Ask me for a remote-safe alternative (Graph/ADO/web), or run that operation from CLI.";
+    // Guardrail check: structural + trust-level
+    const mcpDef = mcpDefinitions.find((d) => d.tool.function.name === name);
+    const guardContext = {
+        readPaths: tools_base_1.editFileReadTracker,
+        trustLevel: ctx?.context?.friend?.trustLevel,
+        agentRoot: safeGetAgentRoot(),
+        ...(mcpDef?.mcpServer ? { mcpServerName: mcpDef.mcpServer } : {}),
+        ...(ctx?.context?.isGroupChat !== undefined ? { isGroupChat: (ctx?.context).isGroupChat } : {}),
+    };
+    const guardArgs = normalizeGuardArgs(name, args);
+    const guardResult = (0, guardrails_1.guardInvocation)(name, guardArgs, guardContext);
+    if (!guardResult.allowed) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
-            event: "tool.error",
+            event: "tool.guardrail_block",
             component: "tools",
-            message: "blocked local tool in remote channel",
-            meta: { name, channel: "teams" },
+            message: "guardrail blocked tool execution",
+            meta: { name, reason: guardResult.reason },
         });
-        return message;
+        return guardResult.reason;
     }
     try {
         const result = await def.handler(args, ctx);
@@ -141,59 +204,47 @@ function summarizeUnknownArgs(args) {
     return summarizeKeyValues(args, keys);
 }
 function summarizeArgs(name, args) {
-    // Check teams tools first
-    const teamsSummary = (0, tools_teams_1.summarizeTeamsArgs)(name, args);
-    if (teamsSummary !== undefined)
-        return teamsSummary;
-    // Check github tools
-    const githubSummary = (0, tools_github_1.summarizeGithubArgs)(name, args);
-    if (githubSummary !== undefined)
-        return githubSummary;
-    // Base tools
-    if (name === "read_file" || name === "write_file")
-        return summarizeKeyValues(args, ["path"]);
-    if (name === "shell")
-        return summarizeKeyValues(args, ["command"]);
-    if (name === "list_directory")
-        return summarizeKeyValues(args, ["path"]);
-    if (name === "git_commit")
-        return summarizeKeyValues(args, ["message"]);
-    if (name === "gh_cli")
-        return summarizeKeyValues(args, ["command"]);
-    if (name === "load_skill")
-        return summarizeKeyValues(args, ["name"]);
-    if (name === "task_create")
-        return summarizeKeyValues(args, ["title", "type", "category"]);
-    if (name === "task_update_status")
-        return summarizeKeyValues(args, ["name", "status"]);
-    if (name === "task_board_status")
-        return summarizeKeyValues(args, ["status"]);
-    if (name === "task_board_action")
-        return summarizeKeyValues(args, ["scope"]);
-    if (name === "task_board" || name === "task_board_deps" || name === "task_board_sessions")
-        return "";
-    if (name === "coding_spawn")
-        return summarizeKeyValues(args, ["runner", "workdir", "taskRef"]);
-    if (name === "coding_status")
-        return summarizeKeyValues(args, ["sessionId"]);
-    if (name === "coding_send_input")
-        return summarizeKeyValues(args, ["sessionId", "input"]);
-    if (name === "coding_kill")
-        return summarizeKeyValues(args, ["sessionId"]);
-    if (name === "claude")
-        return summarizeKeyValues(args, ["prompt"]);
-    if (name === "web_search")
-        return summarizeKeyValues(args, ["query"]);
-    if (name === "memory_search")
-        return summarizeKeyValues(args, ["query"]);
-    if (name === "memory_save")
-        return summarizeKeyValues(args, ["text", "about"]);
-    if (name === "get_friend_note")
-        return summarizeKeyValues(args, ["friendId"]);
-    if (name === "save_friend_note") {
-        return summarizeKeyValues(args, ["type", "key", "content"]);
+    const def = findDefinition(name);
+    if (def && def.summaryKeys !== undefined) {
+        return summarizeKeyValues(args, def.summaryKeys);
     }
-    if (name === "ado_backlog_list")
-        return summarizeKeyValues(args, ["organization", "project"]);
     return summarizeUnknownArgs(args);
 }
+/**
+ * Build an enriched tool result summary for display on remote channels.
+ * For recognized tools, includes result-derived info (diff stats, exit codes, etc.).
+ * Falls back to arg-based summary for unrecognized tools.
+ */
+function buildToolResultSummary(name, args, _result, success) {
+    /* v8 ignore start -- branches: ?? fallbacks and ternaries in tool summary formatting @preserve */
+    switch (name) {
+        case "edit_file": {
+            if (!success)
+                return summarizeArgs(name, args);
+            const addedLines = (args.new_string ?? "").split("\n").length;
+            const removedLines = (args.old_string ?? "").split("\n").length;
+            return `+${addedLines} -${removedLines} lines in ${args.path ?? "unknown"}`;
+        }
+        case "shell": {
+            const cmd = args.command ?? "?";
+            const exitCode = success ? 0 : 1;
+            return `$ ${cmd} (exit ${exitCode})`;
+        }
+        case "read_file":
+            return `path=${args.path ?? "unknown"}`;
+        case "write_file":
+            return `path=${args.path ?? "unknown"}`;
+        case "glob":
+            return `pattern=${args.pattern ?? "?"} ${args.cwd ? `cwd=${args.cwd}` : ""}`.trim();
+        case "grep":
+            return `pattern=${args.pattern ?? "?"} ${args.path ? `path=${args.path}` : ""}`.trim();
+        case "coding_spawn": {
+            const taskRef = args.taskRef ?? "unknown";
+            const status = success ? "spawned" : "failed";
+            return `${taskRef} -> ${status}`;
+        }
+        default:
+            return summarizeArgs(name, args);
+    }
+    /* v8 ignore stop */
+}

package/dist/repertoire/travel-api-client.js

@@ -0,0 +1,360 @@
+"use strict";
+/**
+ * Travel API client module.
+ *
+ * Provides HTTP clients for:
+ * - Open-Meteo weather forecast (no auth, WMO weather codes)
+ * - US State Dept Travel Advisories (no auth)
+ * - Nominatim Geocoding (no auth, requires User-Agent)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRAVEL_ADVISORY_RSS_URL = exports.WMO_WEATHER_CODES = void 0;
+exports.wmoWeatherDescription = wmoWeatherDescription;
+exports.getWeather = getWeather;
+exports.getWeatherByCity = getWeatherByCity;
+exports.isoToCountryName = isoToCountryName;
+exports.parseAdvisoryLevel = parseAdvisoryLevel;
+exports.parseCountryName = parseCountryName;
+exports.parseAdvisoryText = parseAdvisoryText;
+exports.getTravelAdvisory = getTravelAdvisory;
+exports.geocode = geocode;
+exports.reverseGeocode = reverseGeocode;
+exports.searchPOI = searchPOI;
+const runtime_1 = require("../nerves/runtime");
+// --- Open-Meteo Weather (zero auth) ---
+const OPEN_METEO_FORECAST = "https://api.open-meteo.com/v1/forecast";
+const OPEN_METEO_GEOCODING = "https://geocoding-api.open-meteo.com/v1/search";
+const OPEN_METEO_HEADERS = {
+    "User-Agent": "Ouroboros/1.0 (https://github.com/ouroborosbot/ouroboros)",
+    Accept: "application/json",
+};
+/**
+ * WMO weather interpretation codes (WW) to human-readable descriptions.
+ * Spec: https://www.nodc.noaa.gov/archive/arc0021/0002199/1.1/data/0-data/HTML/WMO-CODE/WMO4677.HTM
+ */
+exports.WMO_WEATHER_CODES = {
+    0: "clear sky",
+    1: "mainly clear",
+    2: "partly cloudy",
+    3: "overcast",
+    45: "fog",
+    48: "depositing rime fog",
+    51: "light drizzle",
+    53: "moderate drizzle",
+    55: "dense drizzle",
+    56: "light freezing drizzle",
+    57: "dense freezing drizzle",
+    61: "slight rain",
+    63: "moderate rain",
+    65: "heavy rain",
+    66: "light freezing rain",
+    67: "heavy freezing rain",
+    71: "slight snowfall",
+    73: "moderate snowfall",
+    75: "heavy snowfall",
+    77: "snow grains",
+    80: "slight rain showers",
+    81: "moderate rain showers",
+    82: "violent rain showers",
+    85: "slight snow showers",
+    86: "heavy snow showers",
+    95: "thunderstorm",
+    96: "thunderstorm with slight hail",
+    99: "thunderstorm with heavy hail",
+};
+/** Convert a WMO weather code to a human-readable description. */
+function wmoWeatherDescription(code) {
+    return exports.WMO_WEATHER_CODES[code] ?? "unknown";
+}
+async function getWeather(lat, lon) {
+    return withNervesEvents("getWeather", { lat, lon }, async () => {
+        const url = `${OPEN_METEO_FORECAST}?latitude=${lat}&longitude=${lon}` +
+            `&current=temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,weather_code` +
+            `&daily=temperature_2m_max,temperature_2m_min,weather_code` +
+            `&timezone=auto`;
+        const res = await fetch(url, { headers: OPEN_METEO_HEADERS });
+        if (!res.ok) {
+            throw new Error(`Open-Meteo API error: ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        return parseOpenMeteoResponse(data, lat, lon);
+    });
+}
+async function getWeatherByCity(city) {
+    return withNervesEvents("getWeatherByCity", { city }, async () => {
+        // Step 1: geocode the city name via Open-Meteo geocoding
+        const geoUrl = `${OPEN_METEO_GEOCODING}?name=${encodeURIComponent(city)}&count=1&language=en`;
+        const geoRes = await fetch(geoUrl, { headers: OPEN_METEO_HEADERS });
+        if (!geoRes.ok) {
+            throw new Error(`Open-Meteo geocoding error: ${geoRes.status} ${geoRes.statusText}`);
+        }
+        const geoData = await geoRes.json();
+        const results = geoData.results;
+        if (!results || results.length === 0) {
+            throw new Error(`No location found for city "${city}"`);
+        }
+        const loc = results[0];
+        // Step 2: fetch forecast for the resolved coordinates
+        const url = `${OPEN_METEO_FORECAST}?latitude=${loc.latitude}&longitude=${loc.longitude}` +
+            `&current=temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,weather_code` +
+            `&daily=temperature_2m_max,temperature_2m_min,weather_code` +
+            `&timezone=auto`;
+        const res = await fetch(url, { headers: OPEN_METEO_HEADERS });
+        if (!res.ok) {
+            throw new Error(`Open-Meteo API error: ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        return parseOpenMeteoResponse(data, loc.latitude, loc.longitude, loc.name, loc.country_code);
+    });
+}
+function parseOpenMeteoResponse(data, lat, lon, cityName, countryCode) {
+    const current = data.current ?? {};
+    const daily = data.daily ?? {};
+    return {
+        temperature: current.temperature_2m ?? 0,
+        feelsLike: current.apparent_temperature ?? 0,
+        description: wmoWeatherDescription(current.weather_code ?? -1),
+        humidity: current.relative_humidity_2m ?? 0,
+        windSpeed: current.wind_speed_10m ?? 0,
+        city: cityName ?? `${lat},${lon}`,
+        country: countryCode ?? "",
+        dailyHigh: daily.temperature_2m_max?.[0],
+        dailyLow: daily.temperature_2m_min?.[0],
+    };
+}
+// --- US State Dept Travel Advisories ---
+/**
+ * Official US State Department travel advisories RSS feed.
+ * This is the canonical public feed maintained by travel.state.gov.
+ * Returns XML/RSS with per-country advisory items.
+ */
+exports.TRAVEL_ADVISORY_RSS_URL = "https://travel.state.gov/_res/rss/TAsTWs.xml";
+/**
+ * Mapping of ISO 3166-1 alpha-2 codes to country names, ONLY for codes
+ * where ISO differs from FIPS 10-4 (which the State Dept RSS feed uses).
+ *
+ * The RSS feed Country-Tag uses FIPS codes. Callers typically pass ISO codes.
+ * When the codes match (e.g. AF for Afghanistan), no lookup is needed.
+ * This table handles the ~30 codes where they diverge.
+ */
+const ISO_FIPS_DIVERGENCE = {
+    AG: "Antigua and Barbuda", // FIPS: AC
+    AT: "Austria", // FIPS: AU
+    AU: "Australia", // FIPS: AS
+    BD: "Bangladesh", // FIPS: BG
+    BH: "Bahrain", // FIPS: BA
+    BN: "Brunei", // FIPS: BX
+    BO: "Bolivia", // FIPS: BL
+    BS: "Bahamas", // FIPS: BF
+    BW: "Botswana", // FIPS: BC
+    CD: "Congo (Kinshasa)", // FIPS: CG
+    CH: "Switzerland", // FIPS: SZ
+    CI: "Cote d'Ivoire", // FIPS: IV
+    CL: "Chile", // FIPS: CI
+    CN: "China", // FIPS: CH
+    CZ: "Czechia", // FIPS: EZ
+    DE: "Germany", // FIPS: GM
+    DK: "Denmark", // FIPS: DA
+    DO: "Dominican Republic", // FIPS: DR
+    DZ: "Algeria", // FIPS: AG
+    ES: "Spain", // FIPS: SP
+    FI: "Finland", // FIPS: FI → same, but title might say "Finland"
+    GQ: "Equatorial Guinea", // FIPS: EK
+    HR: "Croatia", // FIPS: HR → same
+    IE: "Ireland", // FIPS: EI
+    IL: "Israel", // FIPS: IS
+    JP: "Japan", // FIPS: JA
+    KP: "North Korea", // FIPS: KN
+    KR: "South Korea", // FIPS: KS
+    LT: "Lithuania", // FIPS: LH
+    MA: "Morocco", // FIPS: MO
+    MM: "Burma", // FIPS: BM (State Dept uses "Burma (Myanmar)")
+    NG: "Nigeria", // FIPS: NI
+    NO: "Norway", // FIPS: NO → same
+    PH: "Philippines", // FIPS: RP
+    PT: "Portugal", // FIPS: PO
+    RO: "Romania", // FIPS: RO → same
+    SE: "Sweden", // FIPS: SW
+    SG: "Singapore", // FIPS: SN
+    TL: "Timor-Leste", // FIPS: TT
+    TR: "Turkey", // FIPS: TU
+    TW: "Taiwan", // FIPS: TW → same
+    UA: "Ukraine", // FIPS: UP
+    VA: "Holy See", // FIPS: VT
+    VN: "Vietnam", // FIPS: VM
+    YE: "Yemen", // FIPS: YM
+    ZA: "South Africa", // FIPS: SF
+};
+/**
+ * Look up the expected country name for an ISO alpha-2 code,
+ * but ONLY when that code diverges from the FIPS code used in the RSS feed.
+ * Returns undefined for codes where ISO == FIPS (no title fallback needed).
+ */
+function isoToCountryName(isoCode) {
+    return ISO_FIPS_DIVERGENCE[isoCode.toUpperCase()];
+}
+/**
+ * Parse advisory level (1-4) from an RSS item title like
+ * "Afghanistan - Level 4: Do Not Travel"
+ */
+function parseAdvisoryLevel(title) {
+    const match = title.match(/Level\s+(\d)/);
+    return match ? parseInt(match[1], 10) : 0;
+}
+/**
+ * Parse country name from an RSS item title like
+ * "Afghanistan - Level 4: Do Not Travel"
+ */
+function parseCountryName(title) {
+    const dashIdx = title.indexOf(" - ");
+    return dashIdx > 0 ? title.slice(0, dashIdx).trim() : title.trim();
+}
+/**
+ * Extract advisory text from title (the part after "Level N: ").
+ */
+function parseAdvisoryText(title) {
+    const match = title.match(/Level\s+\d:\s*(.+)/);
+    return match ? match[1].trim() : title.trim();
+}
+async function getTravelAdvisory(countryCode) {
+    return withNervesEvents("getTravelAdvisory", { countryCode }, async () => {
+        const res = await fetch(exports.TRAVEL_ADVISORY_RSS_URL, {
+            headers: {
+                Accept: "application/xml, text/xml",
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`Travel advisory API error: ${res.status} ${res.statusText}`);
+        }
+        const xml = await res.text();
+        const upperCode = countryCode.toUpperCase();
+        // When the caller's ISO code diverges from FIPS, we need a title-based fallback.
+        const expectedCountryName = isoToCountryName(upperCode);
+        // Parse RSS items via regex (no XML parser dependency needed).
+        // Each <item> contains <title>, <pubDate>, and <category domain="Country-Tag">.
+        const itemPattern = /<item>([\s\S]*?)<\/item>/g;
+        let titleFallbackMatch = null;
+        let match;
+        while ((match = itemPattern.exec(xml)) !== null) {
+            const block = match[1];
+            const titleMatch = block.match(/<title>(.*?)<\/title>/);
+            const title = titleMatch?.[1] ?? "";
+            const pubDateMatch = block.match(/<pubDate>(.*?)<\/pubDate>/);
+            const pubDate = pubDateMatch?.[1]?.trim() ?? "";
+            // Extract country tag from <category domain="Country-Tag">XX</category>
+            const tagMatch = block.match(/<category\s+domain="Country-Tag">(.*?)<\/category>/);
+            const tag = tagMatch?.[1]?.trim().toUpperCase();
+            // Primary match: FIPS tag matches the requested code directly.
+            // Skip this path when the caller's ISO code is known to diverge from FIPS —
+            // e.g. ISO "ES" = Spain, but FIPS "ES" = El Salvador. In that case, only
+            // the title-based fallback should match.
+            if (tag === upperCode && !expectedCountryName) {
+                return {
+                    countryCode,
+                    countryName: parseCountryName(title),
+                    advisoryLevel: parseAdvisoryLevel(title),
+                    advisoryText: parseAdvisoryText(title),
+                    lastUpdated: pubDate,
+                };
+            }
+            // Title-based match: when ISO differs from FIPS, match by country name.
+            // Uses startsWith to handle names like "Burma (Myanmar)" matching "Burma".
+            if (expectedCountryName && !titleFallbackMatch) {
+                const titleCountry = parseCountryName(title);
+                if (titleCountry.toLowerCase().startsWith(expectedCountryName.toLowerCase())) {
+                    titleFallbackMatch = {
+                        countryCode,
+                        countryName: titleCountry,
+                        advisoryLevel: parseAdvisoryLevel(title),
+                        advisoryText: parseAdvisoryText(title),
+                        lastUpdated: pubDate,
+                    };
+                }
+            }
+        }
+        if (titleFallbackMatch)
+            return titleFallbackMatch;
+        throw new Error(`No travel advisory found for country code "${countryCode}"`);
+    });
+}
+// --- Nominatim Geocoding ---
+const NOMINATIM_BASE = "https://nominatim.openstreetmap.org";
+const NOMINATIM_HEADERS = {
+    "User-Agent": "Ouroboros/1.0 (https://github.com/ouroborosbot/ouroboros)",
+    Accept: "application/json",
+};
+async function geocode(query) {
+    return withNervesEvents("geocode", { query }, async () => {
+        const url = `${NOMINATIM_BASE}/search?q=${encodeURIComponent(query)}&format=json`;
+        const res = await fetch(url, { headers: NOMINATIM_HEADERS });
+        if (!res.ok) {
+            throw new Error(`Nominatim geocode error: ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        return data.map(parseGeoLocation);
+    });
+}
+async function reverseGeocode(lat, lon) {
+    return withNervesEvents("reverseGeocode", { lat, lon }, async () => {
+        const url = `${NOMINATIM_BASE}/reverse?lat=${lat}&lon=${lon}&format=json`;
+        const res = await fetch(url, { headers: NOMINATIM_HEADERS });
+        if (!res.ok) {
+            throw new Error(`Nominatim reverse geocode error: ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        return parseGeoLocation(data);
+    });
+}
+async function searchPOI(query, lat, lon, radiusKm) {
+    return withNervesEvents("searchPOI", { query, lat, lon, radiusKm }, async () => {
+        const radius = radiusKm ?? 10;
+        // Nominatim uses viewbox for bounded search (approximate degrees from km)
+        const degOffset = radius / 111; // ~111 km per degree
+        const viewbox = `${lon - degOffset},${lat + degOffset},${lon + degOffset},${lat - degOffset}`;
+        const url = `${NOMINATIM_BASE}/search?q=${encodeURIComponent(query)}&format=json&viewbox=${viewbox}&bounded=1`;
+        const res = await fetch(url, { headers: NOMINATIM_HEADERS });
+        if (!res.ok) {
+            throw new Error(`Nominatim POI search error: ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        return data.map(parseGeoLocation);
+    });
+}
+function parseGeoLocation(item) {
+    return {
+        lat: parseFloat(item.lat),
+        lon: parseFloat(item.lon),
+        displayName: item.display_name,
+        type: item.type ?? "unknown",
+    };
+}
+// --- Shared nerves event wrapper ---
+async function withNervesEvents(operation, meta, fn) {
+    (0, runtime_1.emitNervesEvent)({
+        event: "client.request_start",
+        component: "clients",
+        message: `travel API ${operation} starting`,
+        meta: { operation, ...meta },
+    });
+    try {
+        const result = await fn();
+        (0, runtime_1.emitNervesEvent)({
+            event: "client.request_end",
+            component: "clients",
+            message: `travel API ${operation} complete`,
+            meta: { operation, ...meta },
+        });
+        return result;
+    }
+    catch (err) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            event: "client.error",
+            component: "clients",
+            message: `travel API ${operation} failed`,
+            /* v8 ignore next -- defensive: callers throw Error instances @preserve */
+            meta: { operation, reason: err instanceof Error ? err.message : String(err), ...meta },
+        });
+        throw err;
+    }
+}