onbuzz 4.7.1 → 4.8.0

package/src/services/aiService.js

@@ -1527,6 +1527,141 @@ class AIService {
     }
   }
 
+  /**
+   * Foundry web-grounded search (Azure AI Foundry Responses API +
+   * Grounding with Bing Search).
+   *
+   * Sends a single stateless request to the backend's /llm/web-search
+   * route. The model decides whether to invoke the web_search_preview
+   * tool, Foundry runs the Bing search server-side, and we receive a
+   * synthesized answer with citation URLs. From the agent's
+   * perspective this is a single tool call — Foundry hides the inner
+   * search/read/answer loop.
+   *
+   * Returns 503 from the backend until FOUNDRY_WEB_SEARCH_ENABLED=true
+   * and the Bing Grounding resource is connected to the chat
+   * deployment via the Foundry portal — see
+   * autopilot-backend/docs/FOUNDRY_WEB_SEARCH_PROVISIONING.md.
+   *
+   * @param {string} query
+   * @param {Object} [options]
+   * @param {string} [options.model] — chat model to orchestrate the
+   *   search (defaults to 'gpt-4o'; must have Bing Grounding bound).
+   * @param {string} [options.instructions] — system-style nudge to
+   *   force tool use ("always search before answering").
+   * @param {string} [options.idempotencyKey] — per-request unique;
+   *   used by the backend's per-search billing dedup.
+   * @param {string} [options.sessionId] — for API key resolution.
+   * @returns {Promise<{ answer: string, citations: Array, model: string, usage: Object }>}
+   */
+  async foundryWebSearch(query, options = {}) {
+    const requestId = `ws-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    try {
+      if (this._isCircuitBreakerOpen()) {
+        throw new Error('Service temporarily unavailable - circuit breaker is open');
+      }
+      if (!query || typeof query !== 'string' || query.trim().length === 0) {
+        throw new Error('Web search requires a non-empty query string');
+      }
+      if (query.length > 2000) {
+        throw new Error('Web search query exceeds 2000 char limit');
+      }
+
+      const model = options.model || 'gpt-4o';
+
+      this.logger?.info(`Foundry web search: ${query.slice(0, 60)}…`, {
+        requestId, model, queryLength: query.length,
+      });
+
+      const response = await this._makeFoundryWebSearchAPIRequest(
+        {
+          query,
+          model,
+          instructions: options.instructions,
+          idempotencyKey: options.idempotencyKey,
+        },
+        requestId,
+        { sessionId: options.sessionId, platformProvided: options.platformProvided !== false },
+      );
+
+      this._resetCircuitBreaker();
+
+      return {
+        answer: response.answer,
+        citations: response.citations || [],
+        model: response.model,
+        usage: response.usage || {},
+        requestId,
+      };
+
+    } catch (error) {
+      this._recordFailure();
+      this.logger?.error(`Foundry web search failed: ${error.message}`, {
+        requestId, model: options.model, status: error.status, error: error.stack,
+      });
+      throw error;
+    }
+  }
+
+  /** @private — POST to /llm/web-search with auth + canonical error mapping. */
+  async _makeFoundryWebSearchAPIRequest(payload, requestId, options = {}) {
+    const url = `${this.baseUrl}/llm/web-search`;
+
+    // Same API-key resolution chain as the image / video paths.
+    let apiKey = null;
+    if (this.apiKeyManager) {
+      const keys = this.apiKeyManager.getKeysForRequest(options.sessionId, {
+        platformProvided: options.platformProvided !== false,
+      });
+      apiKey = keys.loxiaApiKey;
+    }
+    if (!apiKey && options.apiKey)      apiKey = options.apiKey;
+    if (!apiKey && this.config.apiKey)  apiKey = this.config.apiKey;
+    if (!apiKey && process.env.LOXIA_API_KEY) apiKey = process.env.LOXIA_API_KEY;
+    if (!apiKey) {
+      throw new Error('No API key configured. Please configure your Loxia API key in Settings.');
+    }
+
+    // Foundry round-trip is normally 2-5s; allow a generous 60s
+    // ceiling for cold deployments + multi-search runs.
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 60_000);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+          'X-Request-ID': requestId,
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        let body = '';
+        try { body = await response.text(); } catch { /* ignore */ }
+        // 503: feature flag off or no deployment — surface a
+        // user-friendly message rather than the raw upstream string.
+        if (response.status === 503) {
+          const e = new Error('Web search isn\'t enabled on this Loxia deployment. Operators: see FOUNDRY_WEB_SEARCH_PROVISIONING.md.');
+          e.status = 503;
+          throw e;
+        }
+        const e = new Error(`HTTP ${response.status}: ${response.statusText}${body ? ` - ${body.slice(0, 200)}` : ''}`);
+        e.status = response.status;
+        throw e;
+      }
+
+      return await response.json();
+
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
   /**
    * Check service health for circuit breaker
    * @returns {Promise<boolean>} Service health status
@@ -1707,7 +1842,7 @@ class AIService {
       },
 
       // Router model
-      'autopilot-model-router': {
+      'model-router': {
         provider: 'AZURE',
         contextWindow: 16384,
         maxTokens: 2048,

package/src/services/grounding/GroundingModel.js

@@ -0,0 +1,116 @@
+/**
+ * Abstract base class for visual-grounding model adapters.
+ *
+ * "Grounding" here means: given a screenshot + an intent description,
+ * return either pixel coordinates or a sequence of tool calls that
+ * accomplish the intent. Concrete subclasses (Kimi, Claude, OpenAI
+ * Computer-Use-Preview, UI-TARS) implement the actual provider call.
+ *
+ * Why an abstract base instead of duck-typed objects: this is the
+ * single seam where adapters get swapped at runtime via the registry.
+ * A typed surface lets the form-generator UI introspect knobs, the
+ * router pick adapters by capability, and tests use a deterministic
+ * MockAdapter with zero special-casing.
+ *
+ * @typedef {import('./types.js').GroundOptions}     GroundOptions
+ * @typedef {import('./types.js').GroundResult}      GroundResult
+ * @typedef {import('./types.js').KnobDef}           KnobDef
+ * @typedef {import('./types.js').Capabilities}      Capabilities
+ * @typedef {import('./types.js').ValidationResult}  ValidationResult
+ */
+
+import { ErrorCode } from './constants.js';
+
+export class GroundingModel {
+  /**
+   * Human-readable name shown in admin UI dropdowns.
+   * Subclasses override.
+   */
+  static displayName = 'GroundingModel (abstract)';
+
+  /**
+   * Stable registry key. Same value as in `ModelId`. Subclasses override.
+   */
+  static modelId = 'abstract';
+
+  // ─── Public API every adapter must implement ──────────────────────
+
+  /**
+   * Capability descriptor consumed by:
+   *  - the router (picks best adapter for a given op)
+   *  - admin UI (renders icons / disables incompatible features)
+   *  - the agent's tool description (model self-knows what it can do)
+   *
+   * @returns {Capabilities}
+   */
+  capabilities() {
+    return {
+      pixelGrounding:   false,
+      toolCalling:      false,
+      multiTurnLoop:    false,
+      visionInput:      false,
+      maxImagePixels:   0,
+      typicalLatencyMs: 0,
+      typicalCostPerCallUSD: 0,
+    };
+  }
+
+  /**
+   * Knobs the operator may tune from the admin UI. Drives the
+   * dynamic-form generator: each entry becomes a labelled field with
+   * type-appropriate widget + inline doc.
+   *
+   * @returns {KnobDef[]}
+   */
+  supportedKnobs() {
+    return [];
+  }
+
+  /**
+   * Validate caller-supplied knob values against the schema above.
+   * Default impl: any subset of supportedKnobs() is allowed; type
+   * coercion is the caller's job. Subclasses override for tighter
+   * constraints (e.g. Kimi-specific `reasoning_effort` enum).
+   *
+   * @param {Object} knobs
+   * @returns {ValidationResult}
+   */
+  validateKnobs(knobs) {
+    const errors = {};
+    const supported = new Set(this.supportedKnobs().map(k => k.id));
+    for (const id of Object.keys(knobs || {})) {
+      if (!supported.has(id)) {
+        errors[id] = `unknown knob "${id}" (supported: ${[...supported].join(', ')})`;
+      }
+    }
+    return { valid: Object.keys(errors).length === 0, errors };
+  }
+
+  /**
+   * The main entry point. Subclasses MUST implement.
+   *
+   * @param {GroundOptions} opts
+   * @returns {Promise<GroundResult>}
+   */
+  async ground(_opts) {
+    throw makeError(ErrorCode.INVALID_REQUEST,
+      `${this.constructor.name}.ground() not implemented`);
+  }
+}
+
+/**
+ * Construct a typed error the adapters and callers can branch on
+ * without parsing message strings. All adapter rejections should
+ * route through this so we get a uniform error surface.
+ *
+ * @param {keyof typeof ErrorCode} code
+ * @param {string} message
+ * @param {object} [extra]   - additional context attached to .details
+ * @returns {Error & { code: string, details?: object }}
+ */
+export function makeError(code, message, extra = undefined) {
+  const err = new Error(message);
+  err.code = code;
+  if (extra !== undefined) err.details = extra;
+  return err;
+}

package/src/services/grounding/KimiAdapter.js

@@ -0,0 +1,427 @@
+/**
+ * Kimi K2.6 grounding adapter (Azure AI Foundry).
+ *
+ * Sends a vision+text request to Foundry's Azure AI inference endpoint
+ * for the `Kimi-K2.6` deployment. Translates the OpenAI-flavoured
+ * `reasoning_effort` knob (which Moonshot's Foundry wrapper accepts as
+ * 'none'|'low'|'medium'|'high') and Moonshot's `extra_body.thinking`
+ * shape into a single wire request. Parses both `content` and
+ * `reasoning_content` from the response.
+ *
+ * Why this is a thin wrapper and not "the smart layer": grounding
+ * intelligence (caching, region cropping, retry-on-miss) belongs
+ * one level up in the DesktopTool. This file's job is "the wire is
+ * boring" — every Kimi-specific concern stays here.
+ *
+ * @typedef {import('./types.js').GroundOptions} GroundOptions
+ * @typedef {import('./types.js').GroundResult}  GroundResult
+ * @typedef {import('./types.js').KnobDef}       KnobDef
+ * @typedef {import('./types.js').Capabilities}  Capabilities
+ */
+
+import { GroundingModel, makeError } from './GroundingModel.js';
+import { parseCoords } from './groundingMetrics.js';
+import {
+  ReasoningEffort,
+  REASONING_EFFORT_VALUES,
+  DEFAULT_REASONING_EFFORT,
+  SamplingDefaults,
+  TokenBudget,
+  Timeouts,
+  ImageDetail,
+  DEFAULT_IMAGE_DETAIL,
+  Foundry,
+  ModelId,
+  KnobType,
+  ErrorCode,
+} from './constants.js';
+
+/**
+ * Effort levels for which the thinking-off sampling defaults apply.
+ * Kept here (not in constants.js) because it's an internal detail
+ * of Kimi: 'none' is the only setting that disables the reasoning
+ * trace.
+ */
+const EFFORTS_WITHOUT_THINKING = new Set([ReasoningEffort.NONE]);
+
+export class KimiAdapter extends GroundingModel {
+  static displayName = 'Kimi K2.6 (Foundry)';
+  static modelId     = ModelId.KIMI_K2_6;
+
+  /**
+   * Two transport modes:
+   *
+   *   - 'direct' (default): hit Foundry directly. Requires `endpoint`
+   *     + `apiKey` (Foundry account key). Useful for the bench harness
+   *     and headless integration tests.
+   *
+   *   - 'proxy': hit the Loxia backend's POST /llm/grounding route,
+   *     which centralises billing + audit. Requires `backendUrl` +
+   *     `userApiKey` (Loxia per-user token, NOT the Foundry key). This
+   *     is the mode every production agent uses.
+   *
+   * @param {Object} cfg
+   * @param {'direct'|'proxy'} [cfg.mode='direct']
+   * @param {string} [cfg.endpoint]    - direct mode: Foundry base URL
+   * @param {string} [cfg.apiKey]      - direct mode: Foundry account key
+   * @param {string} [cfg.deployment]  - deployment name (defaults to kimi-k2.6)
+   * @param {string} [cfg.backendUrl]  - proxy mode: e.g. https://api.loxia.ai
+   * @param {string} [cfg.userApiKey]  - proxy mode: per-user Loxia token
+   * @param {typeof fetch} [cfg.fetchImpl] - dependency injection for tests
+   * @param {object} [cfg.logger]
+   */
+  constructor(cfg) {
+    super();
+    if (!cfg || typeof cfg !== 'object') {
+      throw makeError(ErrorCode.INVALID_REQUEST,
+        'KimiAdapter requires a config object');
+    }
+    this.mode = cfg.mode || 'direct';
+    if (this.mode === 'direct') {
+      if (!cfg.endpoint) throw makeError(ErrorCode.INVALID_REQUEST, 'endpoint is required in direct mode');
+      if (!cfg.apiKey)   throw makeError(ErrorCode.AUTH_FAILED, 'apiKey is required in direct mode');
+      this.endpoint = cfg.endpoint.endsWith('/') ? cfg.endpoint : cfg.endpoint + '/';
+      this.apiKey   = cfg.apiKey;
+    } else if (this.mode === 'proxy') {
+      if (!cfg.backendUrl) throw makeError(ErrorCode.INVALID_REQUEST, 'backendUrl is required in proxy mode');
+      if (!cfg.userApiKey) throw makeError(ErrorCode.AUTH_FAILED,    'userApiKey is required in proxy mode');
+      this.backendUrl = cfg.backendUrl.replace(/\/+$/, '');
+      this.userApiKey = cfg.userApiKey;
+    } else {
+      throw makeError(ErrorCode.INVALID_REQUEST,
+        `unknown mode "${cfg.mode}" — must be 'direct' or 'proxy'`);
+    }
+    this.deployment = cfg.deployment || ModelId.KIMI_K2_6;
+    this.fetchImpl  = cfg.fetchImpl  || globalThis.fetch;
+    this.logger     = cfg.logger     || null;
+  }
+
+  capabilities() {
+    return {
+      pixelGrounding:        true,
+      toolCalling:           true,
+      multiTurnLoop:         false,
+      visionInput:           true,
+      maxImagePixels:        4_000_000,
+      typicalLatencyMs:      80_000,
+      typicalCostPerCallUSD: 0.02,
+    };
+  }
+
+  supportedKnobs() {
+    return [
+      {
+        id: 'reasoning_effort',
+        label: 'Reasoning effort',
+        type: KnobType.ENUM,
+        default: DEFAULT_REASONING_EFFORT,
+        options: REASONING_EFFORT_VALUES.map(v => ({ value: v })),
+        doc:
+          "Higher = more accurate but slower. 'low' is the empirical sweet " +
+          "spot (~3px error / ~80s). 'none' is fast but unreliable on dense UIs.",
+      },
+      {
+        id: 'temperature',
+        label: 'Temperature',
+        type: KnobType.NUMBER,
+        default: SamplingDefaults.THINKING_ON.temperature,
+        range: [0, 2],
+        doc: "Moonshot recommends 1.0 with thinking, 0.6 without.",
+        advanced: true,
+      },
+      {
+        id: 'top_p',
+        label: 'Top-p',
+        type: KnobType.NUMBER,
+        default: SamplingDefaults.THINKING_ON.top_p,
+        range: [0, 1],
+        advanced: true,
+      },
+      {
+        id: 'image_detail',
+        label: 'Image detail',
+        type: KnobType.ENUM,
+        default: DEFAULT_IMAGE_DETAIL,
+        options: Object.values(ImageDetail).map(v => ({ value: v })),
+      },
+      {
+        id: 'max_tokens',
+        label: 'Max output tokens',
+        type: KnobType.NUMBER,
+        default: TokenBudget.THINKING_DEFAULT_MAX_TOKENS,
+        range: [TokenBudget.INSTANT_DEFAULT_MAX_TOKENS, 32_000],
+        advanced: true,
+      },
+      {
+        id: 'seed',
+        label: 'Seed (for reproducibility)',
+        type: KnobType.NUMBER,
+        default: null,
+        advanced: true,
+      },
+    ];
+  }
+
+  validateKnobs(knobs) {
+    // Start with the base check (rejects unknown keys).
+    const base = super.validateKnobs(knobs);
+    const errors = { ...base.errors };
+
+    const k = knobs || {};
+    if (k.reasoning_effort !== undefined
+        && !REASONING_EFFORT_VALUES.includes(k.reasoning_effort)) {
+      errors.reasoning_effort = `must be one of ${REASONING_EFFORT_VALUES.join(', ')}`;
+    }
+    if (k.temperature !== undefined && !inRange(k.temperature, 0, 2)) {
+      errors.temperature = 'must be a number in [0, 2]';
+    }
+    if (k.top_p !== undefined && !inRange(k.top_p, 0, 1)) {
+      errors.top_p = 'must be a number in [0, 1]';
+    }
+    if (k.image_detail !== undefined && !Object.values(ImageDetail).includes(k.image_detail)) {
+      errors.image_detail = `must be one of ${Object.values(ImageDetail).join(', ')}`;
+    }
+    if (k.max_tokens !== undefined && (!Number.isInteger(k.max_tokens) || k.max_tokens < 1)) {
+      errors.max_tokens = 'must be a positive integer';
+    }
+    return { valid: Object.keys(errors).length === 0, errors };
+  }
+
+  /**
+   * @param {GroundOptions} opts
+   * @returns {Promise<GroundResult>}
+   */
+  async ground(opts) {
+    if (!opts || !Buffer.isBuffer(opts.screenshot)) {
+      throw makeError(ErrorCode.INVALID_REQUEST, 'screenshot (Buffer) is required');
+    }
+    if (typeof opts.intent !== 'string' || !opts.intent.trim()) {
+      throw makeError(ErrorCode.INVALID_REQUEST, 'intent (non-empty string) is required');
+    }
+    const knobs = opts.knobs || {};
+    const validation = this.validateKnobs(knobs);
+    if (!validation.valid) {
+      throw makeError(ErrorCode.UNSUPPORTED_KNOB,
+        `invalid knobs: ${JSON.stringify(validation.errors)}`,
+        validation.errors);
+    }
+
+    const effort = knobs.reasoning_effort ?? DEFAULT_REASONING_EFFORT;
+    const reasoningOn = !EFFORTS_WITHOUT_THINKING.has(effort);
+    const sampling = reasoningOn ? SamplingDefaults.THINKING_ON : SamplingDefaults.THINKING_OFF;
+
+    const timeoutMs = opts.timeoutMs
+      || (reasoningOn ? Timeouts.GROUNDING_REQUEST_MS : Timeouts.GROUNDING_REQUEST_FAST_MS);
+
+    const startedAt = Date.now();
+    let data;
+    if (this.mode === 'direct') {
+      const body = this._buildRequestBody({ opts, knobs, effort, sampling });
+      const url  = `${this.endpoint}${Foundry.CHAT_COMPLETIONS_PATH}?api-version=${Foundry.API_VERSION}`;
+      data = await this._postDirect(url, body, timeoutMs);
+    } else {
+      const body = this._buildProxyBody({ opts, knobs, effort, sampling });
+      data = await this._postProxy(body, timeoutMs);
+    }
+    const elapsed_ms = Date.now() - startedAt;
+    return this._parseResponse(data, elapsed_ms);
+  }
+
+  // ─── private helpers ──────────────────────────────────────────────
+
+  /** Build the OpenAI-shaped chat-completions body Foundry expects. */
+  _buildRequestBody({ opts, knobs, effort, sampling }) {
+    const detail   = knobs.image_detail ?? DEFAULT_IMAGE_DETAIL;
+    const temperature = knobs.temperature ?? sampling.temperature;
+    const top_p   = knobs.top_p ?? sampling.top_p;
+    const max_tokens = knobs.max_tokens ?? TokenBudget.THINKING_DEFAULT_MAX_TOKENS;
+    const b64 = opts.screenshot.toString('base64');
+
+    const body = {
+      model: this.deployment,
+      reasoning_effort: effort,
+      temperature,
+      top_p,
+      max_tokens,
+      messages: [{
+        role: 'user',
+        content: [
+          { type: 'text', text: this._formatIntent(opts) },
+          { type: 'image_url', image_url: { url: `data:image/png;base64,${b64}`, detail } },
+        ],
+      }],
+    };
+    if (Array.isArray(opts.tools) && opts.tools.length > 0) {
+      body.tools = opts.tools;
+      body.tool_choice = 'auto';
+    }
+    if (Number.isFinite(knobs.seed)) {
+      body.seed = knobs.seed;
+    }
+    return body;
+  }
+
+  /**
+   * Add an optional image-dimension hint to the prompt. From the
+   * Phase-0 bench: telling Kimi the resolution cuts mean error from
+   * 666px → 41px on a single shot. Cheap, always include.
+   */
+  _formatIntent(opts) {
+    const { intent, imageSize } = opts;
+    if (imageSize?.width && imageSize?.height) {
+      return `This is a ${imageSize.width}x${imageSize.height} screenshot. ${intent}`;
+    }
+    return intent;
+  }
+
+  /**
+   * Build the request body the proxy expects (matches POST /llm/grounding).
+   * Same messages shape as direct mode — the proxy doesn't transform.
+   */
+  _buildProxyBody({ opts, knobs, effort, sampling }) {
+    const direct = this._buildRequestBody({ opts, knobs, effort, sampling });
+    // The proxy uses its own deployment routing; strip the model
+    // field we'd send to Foundry directly and surface the logical
+    // model id instead. All knobs pass through.
+    return {
+      model:            this.deployment,
+      messages:         direct.messages,
+      reasoning_effort: direct.reasoning_effort,
+      temperature:      direct.temperature,
+      top_p:            direct.top_p,
+      max_tokens:       direct.max_tokens,
+      ...(direct.seed !== undefined        ? { seed:        direct.seed }        : {}),
+      ...(direct.tools !== undefined       ? { tools:       direct.tools }       : {}),
+      ...(direct.tool_choice !== undefined ? { tool_choice: direct.tool_choice } : {}),
+    };
+  }
+
+  /** Post to Foundry directly (mode: 'direct'). */
+  async _postDirect(url, body, timeoutMs) {
+    return this._postJson(url, body, timeoutMs, {
+      'Authorization': `Bearer ${this.apiKey}`,
+    });
+  }
+
+  /**
+   * Post via the Loxia backend (mode: 'proxy'). The backend signs the
+   * request with the tenant-shared Foundry key and records billing,
+   * then returns a normalised shape we coerce back to the Foundry
+   * chat-completion contract for `_parseResponse`.
+   */
+  async _postProxy(body, timeoutMs) {
+    const url = `${this.backendUrl}/llm/grounding`;
+    const proxied = await this._postJson(url, body, timeoutMs, {
+      'Authorization': `Bearer ${this.userApiKey}`,
+    });
+    // Re-coerce to chat-completion shape so _parseResponse stays
+    // ignorant of the transport.
+    return {
+      choices: [{
+        message: {
+          content:           proxied.answer ?? '',
+          reasoning_content: proxied.reasoning ?? undefined,
+          tool_calls:        proxied.tool_calls ?? undefined,
+        },
+      }],
+      usage: {
+        prompt_tokens:     proxied.usage?.inputTokens  ?? 0,
+        completion_tokens: proxied.usage?.outputTokens ?? 0,
+      },
+    };
+  }
+
+  async _postJson(url, body, timeoutMs, extraHeaders) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type':  'application/json',
+          ...extraHeaders,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      const text = await res.text();
+      let parsed;
+      try { parsed = JSON.parse(text); }
+      catch {
+        throw makeError(ErrorCode.PROVIDER_ERROR,
+          `non-JSON response (status ${res.status}): ${text.slice(0, 300)}`);
+      }
+      if (!res.ok) {
+        const code = res.status === 401 || res.status === 403
+          ? ErrorCode.AUTH_FAILED
+          : ErrorCode.PROVIDER_ERROR;
+        // Identify the upstream accurately so a 404 from "the backend
+        // route isn't deployed" doesn't read as "Foundry 404" (it isn't
+        // Foundry — it's the proxy). The error text shapes the agent's
+        // recovery + ours.
+        const upstream = this.mode === 'proxy' ? 'Backend' : 'Foundry';
+        const hint = (this.mode === 'proxy' && res.status === 404)
+          ? ' — the /llm/grounding route appears to be undeployed on this backend. ' +
+            'Set FOUNDRY_ENDPOINT + FOUNDRY_KEY env vars to fall back to direct mode.'
+          : '';
+        throw makeError(code,
+          `${upstream} ${res.status}: ${parsed?.error?.message || parsed?.error?.code || text.slice(0, 200)}${hint}`,
+          { status: res.status, body: parsed, mode: this.mode });
+      }
+      return parsed;
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw makeError(ErrorCode.TIMEOUT, `request exceeded ${timeoutMs}ms`);
+      }
+      // Re-throw typed errors as-is; wrap unknowns.
+      if (err.code && Object.values(ErrorCode).includes(err.code)) throw err;
+      throw makeError(ErrorCode.PROVIDER_ERROR, err.message || String(err));
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  _parseResponse(data, elapsed_ms) {
+    const choice = data?.choices?.[0];
+    if (!choice) {
+      throw makeError(ErrorCode.UNPARSEABLE_RESPONSE,
+        'response has no choices[0]', { data });
+    }
+    const msg   = choice.message || {};
+    const answer = (msg.content || '').trim();
+    const reasoning_content = msg.reasoning_content || undefined;
+    const tool_calls = Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0
+      ? msg.tool_calls
+      : undefined;
+    const usage = {
+      input_tokens:     numberOrZero(data.usage?.prompt_tokens),
+      output_tokens:    numberOrZero(data.usage?.completion_tokens),
+      reasoning_tokens: numberOrZero(data.usage?.reasoning_tokens
+                                  ?? data.usage?.completion_tokens_details?.reasoning_tokens),
+    };
+    /** @type {import('./types.js').GroundResult} */
+    const result = {
+      answer,
+      reasoning_content,
+      tool_calls,
+      usage,
+      elapsed_ms,
+      modelId: KimiAdapter.modelId,
+      raw: data,
+    };
+    const coords = parseCoords(answer);
+    if (coords) result.coords = coords;
+    return result;
+  }
+}
+
+// ── module-scoped helpers ────────────────────────────────────────────
+
+function inRange(v, lo, hi) {
+  return typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi;
+}
+function numberOrZero(v) {
+  return Number.isFinite(v) ? v : 0;
+}
+
+export default KimiAdapter;