rootr-cli 0.2.1 → 0.4.0

package/lib/client.js

@@ -6,6 +6,22 @@
  * can render consistent, helpful messages.
  */
 
+import { currentRateLimitSink } from './context.js';
+
+/** Copy the API's X-RateLimit-* headers into the ambient per-call sink, if any. */
+function captureRateLimit(res) {
+  const sink = currentRateLimitSink();
+  if (!sink) return;
+  const limit = Number(res.headers.get('x-ratelimit-limit'));
+  const remaining = Number(res.headers.get('x-ratelimit-remaining'));
+  if (!Number.isFinite(limit) || !Number.isFinite(remaining)) return;
+  sink.limit = limit;
+  sink.remaining = remaining;
+  sink.window = res.headers.get('x-ratelimit-window') || undefined;
+  sink.resetAt = Number(res.headers.get('x-ratelimit-reset')) || undefined;
+  sink.upgradeUrl = res.headers.get('x-ratelimit-upgrade-url') || undefined;
+}
+
 export class RootrApiError extends Error {
   constructor(message, { status, body, hint } = {}) {
     super(message);
@@ -34,10 +50,13 @@ function hintFor(status, body) {
 }
 
 export class RootrClient {
-  constructor({ apiKey, workspace, baseUrl }) {
+  constructor({ apiKey, workspace, baseUrl, defaultHeaders }) {
     this.apiKey = apiKey;
     this.workspace = workspace;
     this.baseUrl = (baseUrl || '').replace(/\/+$/, '');
+    /** Sent on every request — the hosted transport forwards Accept-Language
+     * here so API error text comes back in the caller's language. */
+    this.defaultHeaders = defaultHeaders || {};
   }
 
   _requireWorkspace() {
@@ -72,6 +91,7 @@ export class RootrClient {
     const url = opts.url || `${this.baseUrl}${path}`;
     const headers = {
       'x-api-key': this.apiKey,
+      ...this.defaultHeaders,
       ...(opts.headers || {}),
     };
 
@@ -92,6 +112,8 @@ export class RootrClient {
       throw new RootrApiError(`네트워크 오류: ${err.message}`, { hint: `요청 URL: ${url}` });
     }
 
+    captureRateLimit(res);
+
     if (opts.returnResponse) {
       if (!res.ok) {
         await this._throwForResponse(res);
@@ -276,6 +298,47 @@ export class RootrClient {
     return this.request(`/nodes/${encodeURIComponent(id)}`, { method: 'DELETE' });
   }
 
+  // ---- Comments / publishing / duplication (document-level extras) --------
+
+  /** Comments carry a user identity — needs an account key (PAT) or user session; workspace keys 403. */
+  async createComment(documentId, { body, blockId, parentId } = {}) {
+    return this.request(`/documents/${encodeURIComponent(documentId)}/comments`, {
+      method: 'POST',
+      body: { body, blockId, parentId },
+    });
+  }
+
+  async listComments(documentId, { blockId } = {}) {
+    return this.request(
+      `/documents/${encodeURIComponent(documentId)}/comments${this._qs({ blockId })}`,
+    );
+  }
+
+  /** Publish to a public /p/{slug} URL. Returns { slug, ... }. Requires MANAGE on the node. */
+  async publishDocument(documentId) {
+    return this.request(`/documents/${encodeURIComponent(documentId)}/publish`, { method: 'POST' });
+  }
+
+  /** Patch public settings, e.g. { isPublic: false } to unpublish. */
+  async setDocumentPublic(documentId, settings = {}) {
+    return this.request(`/documents/${encodeURIComponent(documentId)}/public`, {
+      method: 'PATCH',
+      body: settings,
+    });
+  }
+
+  async getDocumentPublicStatus(documentId) {
+    return this.request(`/documents/${encodeURIComponent(documentId)}/public-status`);
+  }
+
+  /** Deep-copy a node (tree) — optionally into another workspace the caller can access. */
+  async duplicateNode(nodeId, { deep, targetWorkspaceId } = {}) {
+    return this.request(`/nodes/${encodeURIComponent(nodeId)}/duplicate`, {
+      method: 'POST',
+      body: { deep, targetWorkspaceId },
+    });
+  }
+
   // ---- Workspaces (account-key scoped) -------------------------------------
 
   /** List workspaces visible to the current key (account key / JWT). Defensive parsing. */
@@ -501,4 +564,471 @@ export class RootrClient {
       { method: 'DELETE' },
     );
   }
+
+  // ---- CRM ----------------------------------------------------------------
+
+  /** Create a CRM node. pipelines/fields/config optional (server fills sane defaults). */
+  async createCrm(workspace, { name, path, parentId, icon, pipelines, fields, config, createParents, autoRename } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/crms`, {
+      method: 'POST',
+      body: { name, path, parentId, icon, pipelines, fields, config, createParents, autoRename },
+    });
+  }
+
+  /** CRM detail: { id, name, pipelines[{id,name,stages[]}], fields, config, counts, myLevel }. */
+  async getCrm(crmId) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}`);
+  }
+
+  async updateCrm(crmId, { pipelines, fields, config, icon } = {}) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}`, {
+      method: 'PATCH',
+      body: { pipelines, fields, config, icon },
+    });
+  }
+
+  /** Per-pipeline stage value/forecast/win-rate + wonByMonth + open task counts. */
+  async getCrmSummary(crmId) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/summary`);
+  }
+
+  _qs(params) {
+    const usp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params || {})) {
+      if (v !== undefined && v !== null && v !== '') usp.set(k, String(v));
+    }
+    const s = usp.toString();
+    return s ? `?${s}` : '';
+  }
+
+  // -- Companies --
+
+  async listCrmCompanies(crmId, { q, ownerId, tag, sort, limit, offset } = {}) {
+    return this.request(
+      `/crms/${encodeURIComponent(crmId)}/companies${this._qs({ q, ownerId, tag, sort, limit, offset })}`,
+    );
+  }
+
+  async createCrmCompany(crmId, body) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/companies`, { method: 'POST', body });
+  }
+
+  /** Detail includes contacts/deals/activities/tasks alongside the company. */
+  async getCrmCompany(companyId) {
+    return this.request(`/crm-companies/${encodeURIComponent(companyId)}`);
+  }
+
+  async updateCrmCompany(companyId, patch) {
+    return this.request(`/crm-companies/${encodeURIComponent(companyId)}`, { method: 'PATCH', body: patch });
+  }
+
+  async deleteCrmCompany(companyId) {
+    return this.request(`/crm-companies/${encodeURIComponent(companyId)}`, { method: 'DELETE' });
+  }
+
+  // -- Contacts --
+
+  async listCrmContacts(crmId, { q, companyId, lifecycleStage, leadStatus, ownerId, tag, sort, limit, offset } = {}) {
+    return this.request(
+      `/crms/${encodeURIComponent(crmId)}/contacts${this._qs({
+        q,
+        companyId,
+        lifecycleStage,
+        leadStatus,
+        ownerId,
+        tag,
+        sort,
+        limit,
+        offset,
+      })}`,
+    );
+  }
+
+  async createCrmContact(crmId, body) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/contacts`, { method: 'POST', body });
+  }
+
+  async getCrmContact(contactId) {
+    return this.request(`/crm-contacts/${encodeURIComponent(contactId)}`);
+  }
+
+  async updateCrmContact(contactId, patch) {
+    return this.request(`/crm-contacts/${encodeURIComponent(contactId)}`, { method: 'PATCH', body: patch });
+  }
+
+  async deleteCrmContact(contactId) {
+    return this.request(`/crm-contacts/${encodeURIComponent(contactId)}`, { method: 'DELETE' });
+  }
+
+  // -- Deals --
+
+  async listCrmDeals(crmId, { q, pipelineId, stageId, status, ownerId, companyId, contactId, tag, sort, limit, offset } = {}) {
+    return this.request(
+      `/crms/${encodeURIComponent(crmId)}/deals${this._qs({
+        q,
+        pipelineId,
+        stageId,
+        status,
+        ownerId,
+        companyId,
+        contactId,
+        tag,
+        sort,
+        limit,
+        offset,
+      })}`,
+    );
+  }
+
+  async createCrmDeal(crmId, body) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/deals`, { method: 'POST', body });
+  }
+
+  async getCrmDeal(dealId) {
+    return this.request(`/crm-deals/${encodeURIComponent(dealId)}`);
+  }
+
+  async updateCrmDeal(dealId, patch) {
+    return this.request(`/crm-deals/${encodeURIComponent(dealId)}`, { method: 'PATCH', body: patch });
+  }
+
+  async deleteCrmDeal(dealId) {
+    return this.request(`/crm-deals/${encodeURIComponent(dealId)}`, { method: 'DELETE' });
+  }
+
+  /** Kanban-style stage move: { stageId, pipelineId?, position? }. */
+  async moveCrmDeal(dealId, { stageId, pipelineId, position } = {}) {
+    return this.request(`/crm-deals/${encodeURIComponent(dealId)}/move`, {
+      method: 'POST',
+      body: { stageId, pipelineId, position },
+    });
+  }
+
+  // -- Activities --
+
+  async listCrmActivities(crmId, { contactId, companyId, dealId, type, limit, offset } = {}) {
+    return this.request(
+      `/crms/${encodeURIComponent(crmId)}/activities${this._qs({ contactId, companyId, dealId, type, limit, offset })}`,
+    );
+  }
+
+  async createCrmActivity(crmId, body) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/activities`, { method: 'POST', body });
+  }
+
+  // -- Tasks --
+
+  async listCrmTasks(crmId, { status, assigneeId, due, contactId, companyId, dealId, limit, offset } = {}) {
+    return this.request(
+      `/crms/${encodeURIComponent(crmId)}/tasks${this._qs({
+        status,
+        assigneeId,
+        due,
+        contactId,
+        companyId,
+        dealId,
+        limit,
+        offset,
+      })}`,
+    );
+  }
+
+  async createCrmTask(crmId, body) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/tasks`, { method: 'POST', body });
+  }
+
+  async updateCrmTask(taskId, patch) {
+    return this.request(`/crm-tasks/${encodeURIComponent(taskId)}`, { method: 'PATCH', body: patch });
+  }
+
+  // -- Import / export --
+
+  /** Raw CSV text for entity = contact | company | deal. */
+  async exportCrm(crmId, entity) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/export${this._qs({ entity })}`, { rawText: true });
+  }
+
+  async importCrm(crmId, { entity, rows } = {}) {
+    return this.request(`/crms/${encodeURIComponent(crmId)}/import`, {
+      method: 'POST',
+      body: { entity, rows },
+    });
+  }
+
+  // ---- Presentations (slide decks) ----------------------------------------
+
+  async createPresentation(workspaceId, { name, parentId, theme, slides, config, icon } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/presentations`, {
+      method: 'POST',
+      body: { name, parentId, theme, slides, config, icon },
+    });
+  }
+
+  /** Full deck: node meta + theme + ordered slides array. */
+  async getPresentation(presentationId) {
+    return this.request(`/presentations/${encodeURIComponent(presentationId)}`);
+  }
+
+  /** REC-001 — create an empty RECORDING node (audio is uploaded separately). */
+  async createRecording(
+    workspaceId,
+    { name, parentId, path, createParents, autoRename, icon, expectedSpeakers } = {},
+  ) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/recordings`, {
+      method: 'POST',
+      body: { name, parentId, path, createParents, autoRename, icon, expectedSpeakers },
+    });
+  }
+
+  /** REC-001 — recording detail: status + diarized transcript + speaker names. */
+  async getRecording(recordingId) {
+    return this.request(`/recordings/${encodeURIComponent(recordingId)}`);
+  }
+
+  /**
+   * Downloads a recording's audio bytes. Uses the unauthenticated `/raw` route
+   * (unguessable attachment id, same tradeoff images already take) so the
+   * redirect to the storage bucket isn't sent our API key.
+   */
+  async downloadAttachmentBytes(attachmentId) {
+    const url = this.attachmentRawUrl(attachmentId);
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new RootrApiError(`오디오 다운로드 실패 (HTTP ${res.status})`, { status: res.status });
+    }
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  /** Merge-patch speakerNames ({"S1":"김대표"}) and/or icon. */
+  async updateRecording(recordingId, { speakerNames, expectedSpeakers, icon } = {}) {
+    return this.request(`/recordings/${encodeURIComponent(recordingId)}`, {
+      method: 'PATCH',
+      body: { speakerNames, expectedSpeakers, icon },
+    });
+  }
+
+  /**
+   * Uploads the raw audio bytes (max 100MB) and kicks off diarized STT —
+   * same raw-body pattern as uploadAttachment. Returns the recording with
+   * status TRANSCRIBING.
+   */
+  async uploadRecordingAudio(recordingId, { filename, mimeType, durationSec, data }) {
+    const qs = new URLSearchParams({ filename, mimeType });
+    if (durationSec != null) qs.set('durationSec', String(durationSec));
+    return this.request(`/recordings/${encodeURIComponent(recordingId)}/audio?${qs.toString()}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/octet-stream' },
+      body: data,
+    });
+  }
+
+  /** Re-runs speech-to-text on the already-uploaded audio (spends AI credits). */
+  async transcribeRecording(recordingId) {
+    return this.request(`/recordings/${encodeURIComponent(recordingId)}/transcribe`, {
+      method: 'POST',
+    });
+  }
+
+  /** Built-in summarization → creates a markdown DOCUMENT node; returns { docId }. */
+  async summarizeRecording(recordingId, { locale, format } = {}) {
+    return this.request(`/recordings/${encodeURIComponent(recordingId)}/summarize`, {
+      method: 'POST',
+      body: { locale, format },
+    });
+  }
+
+  /** Merge-patch theme/config/icon; `slides` REPLACES the whole array when present. */
+  async updatePresentation(presentationId, { theme, slides, config, icon } = {}) {
+    return this.request(`/presentations/${encodeURIComponent(presentationId)}`, {
+      method: 'PATCH',
+      body: { theme, slides, config, icon },
+    });
+  }
+
+  async appendPresentationSlides(presentationId, slides) {
+    return this.request(`/presentations/${encodeURIComponent(presentationId)}/slides`, {
+      method: 'POST',
+      body: { slides },
+    });
+  }
+
+  async updatePresentationSlide(presentationId, slideId, slide) {
+    return this.request(
+      `/presentations/${encodeURIComponent(presentationId)}/slides/${encodeURIComponent(slideId)}`,
+      { method: 'PATCH', body: { slide } },
+    );
+  }
+
+  /** `order` = slide ids in the desired order (must be a permutation of existing ids). */
+  async reorderPresentationSlides(presentationId, order) {
+    return this.request(`/presentations/${encodeURIComponent(presentationId)}/reorder`, {
+      method: 'POST',
+      body: { order },
+    });
+  }
+
+  // ---- Images (deck assets; consume AI credits) ---------------------------
+
+  async generateImage(workspaceId, { prompt, nodeId, context } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/images/generate`, {
+      method: 'POST',
+      body: { prompt, nodeId, context },
+    });
+  }
+
+  async removeImageBackground(workspaceId, { attachmentId, nodeId } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/images/remove-background`, {
+      method: 'POST',
+      body: { attachmentId, nodeId },
+    });
+  }
+
+  // ---- Attachments (upload local files/images) -----------------------------
+
+  /**
+   * Proxied upload — mirrors the editor's upload path (#13), which streams
+   * bytes through the API instead of a presigned S3 PUT (avoids S3 CORS
+   * issues from non-browser callers like the CLI/MCP).
+   */
+  async uploadAttachment(workspaceId, { filename, mimeType, nodeId, data }) {
+    const qs = new URLSearchParams({ workspaceId, filename, mimeType });
+    if (nodeId) qs.set('nodeId', nodeId);
+    return this.request(`/attachments/upload?${qs.toString()}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/octet-stream' },
+      body: data,
+    });
+  }
+
+  /** Public, unauthenticated URL an <img> tag (or a published /p/ document) can load directly. */
+  attachmentRawUrl(attachmentId) {
+    return `${this.baseUrl}/attachments/${encodeURIComponent(attachmentId)}/raw`;
+  }
+
+  // ---- Spreadsheets ---------------------------------------------------------
+
+  async listSpreadsheets(workspace) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/spreadsheets`);
+  }
+
+  async createSpreadsheet(workspace, { name, parentId, path, createParents, autoRename, icon, data, config } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/spreadsheets`, {
+      method: 'POST',
+      body: { name, parentId, path, createParents, autoRename, icon, data, config },
+    });
+  }
+
+  /** Full spreadsheet: node meta + sheets[] (each with a sparse `cells` map). */
+  async getSpreadsheet(spreadsheetId) {
+    return this.request(`/spreadsheets/${encodeURIComponent(spreadsheetId)}`);
+  }
+
+  /** Merge-patch config/icon; `sheets` REPLACES the whole sheets array when present. */
+  async updateSpreadsheet(spreadsheetId, { sheets, config, icon } = {}) {
+    return this.request(`/spreadsheets/${encodeURIComponent(spreadsheetId)}`, {
+      method: 'PATCH',
+      body: { sheets, config, icon },
+    });
+  }
+
+  async createSheet(spreadsheetId, { name, rowCount, colCount } = {}) {
+    return this.request(`/spreadsheets/${encodeURIComponent(spreadsheetId)}/sheets`, {
+      method: 'POST',
+      body: { name, rowCount, colCount },
+    });
+  }
+
+  async patchSheet(spreadsheetId, sheetId, patch) {
+    return this.request(
+      `/spreadsheets/${encodeURIComponent(spreadsheetId)}/sheets/${encodeURIComponent(sheetId)}`,
+      { method: 'PATCH', body: patch },
+    );
+  }
+
+  async deleteSheet(spreadsheetId, sheetId) {
+    return this.request(
+      `/spreadsheets/${encodeURIComponent(spreadsheetId)}/sheets/${encodeURIComponent(sheetId)}`,
+      { method: 'DELETE' },
+    );
+  }
+
+  /** Sparse cell patch: { "A1": { v, f? } | null }. null clears the cell. */
+  async patchCells(spreadsheetId, sheetId, cells) {
+    return this.request(
+      `/spreadsheets/${encodeURIComponent(spreadsheetId)}/sheets/${encodeURIComponent(sheetId)}/cells`,
+      { method: 'PATCH', body: { cells } },
+    );
+  }
+
+  // ---- Whiteboards -----------------------------------------------------------
+
+  async createWhiteboard(workspace, { name, parentId, path, createParents, autoRename, icon, scene, config } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/whiteboards`, {
+      method: 'POST',
+      body: { name, parentId, path, createParents, autoRename, icon, scene, config },
+    });
+  }
+
+  /** Full board: node meta + scene ({ shapes[], edges[] }). */
+  async getWhiteboard(whiteboardId) {
+    return this.request(`/whiteboards/${encodeURIComponent(whiteboardId)}`);
+  }
+
+  /**
+   * Merge-patch config/icon; `scene` REPLACES the whole scene when present
+   * unless `merge` is true (then shapes/edges are upserted by id).
+   */
+  async updateWhiteboard(whiteboardId, { scene, merge, config, icon } = {}) {
+    return this.request(`/whiteboards/${encodeURIComponent(whiteboardId)}`, {
+      method: 'PATCH',
+      body: { scene, merge, config, icon },
+    });
+  }
+
+  // ---- Forms -----------------------------------------------------------------
+
+  async createForm(workspace, { name, parentId, path, createParents, autoRename, icon, fields, targetDatabaseId, config } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/forms`, {
+      method: 'POST',
+      body: { name, parentId, path, createParents, autoRename, icon, fields, targetDatabaseId, config },
+    });
+  }
+
+  /** Full form: node meta + fields[] + targetDatabaseId + config. */
+  async getForm(formId) {
+    return this.request(`/forms/${encodeURIComponent(formId)}`);
+  }
+
+  /** Merge-patch fields/targetDatabaseId/config/icon. */
+  async updateForm(formId, { fields, targetDatabaseId, config, icon } = {}) {
+    return this.request(`/forms/${encodeURIComponent(formId)}`, {
+      method: 'PATCH',
+      body: { fields, targetDatabaseId, config, icon },
+    });
+  }
+
+  /** Submitted responses, most recent first. */
+  async listFormResponses(formId) {
+    const data = await this.request(`/forms/${encodeURIComponent(formId)}/responses`);
+    if (data && Array.isArray(data.responses)) return data.responses;
+    return [];
+  }
+
+  async createFormResponse(formId, values) {
+    return this.request(`/forms/${encodeURIComponent(formId)}/responses`, {
+      method: 'POST',
+      body: { values },
+    });
+  }
+
+  /** Issue a new public share link ({ token, url, ... }) for the form. */
+  async createFormShareLink(formId) {
+    return this.request(`/forms/${encodeURIComponent(formId)}/share`, { method: 'POST' });
+  }
+
+  async listFormShareLinks(formId) {
+    const data = await this.request(`/forms/${encodeURIComponent(formId)}/share`);
+    if (data && Array.isArray(data.links)) return data.links;
+    return [];
+  }
 }

package/lib/config.js

@@ -29,8 +29,37 @@ export function loadConfig() {
   const apiKey = process.env.ROOTR_API_KEY || file.apiKey || '';
   const workspace = process.env.ROOTR_WORKSPACE || file.workspace || '';
   const baseUrl = process.env.ROOTR_BASE_URL || file.baseUrl || DEFAULT_BASE_URL;
+  // Extra credentials, each optionally bound to the workspace it can reach:
+  // [{ apiKey, workspace?, label? }]. Lets one machine hold keys for several
+  // workspaces and switch between them without re-running `rootr config`.
+  const keys = Array.isArray(file.keys) ? file.keys.filter((k) => k && typeof k.apiKey === 'string') : [];
 
-  return { apiKey, workspace, baseUrl };
+  return { apiKey, workspace, baseUrl, keys };
+}
+
+/**
+ * Pick the credential that can reach `workspace`: a key explicitly bound to it
+ * wins, otherwise the default key (an account key/PAT reaches every workspace
+ * its owner belongs to, so it is the right fallback).
+ */
+export function keyForWorkspace(cfg, workspace) {
+  if (workspace) {
+    const bound = (cfg.keys || []).find((k) => k.workspace === workspace);
+    if (bound) return bound.apiKey;
+  }
+  return cfg.apiKey;
+}
+
+/** Add/replace a stored key, keyed by its secret. Returns the saved list. */
+export function upsertKey({ apiKey, workspace, label }) {
+  const file = readConfigFile();
+  const keys = Array.isArray(file.keys) ? file.keys.slice() : [];
+  const at = keys.findIndex((k) => k && k.apiKey === apiKey);
+  const entry = { apiKey, ...(workspace ? { workspace } : {}), ...(label ? { label } : {}) };
+  if (at >= 0) keys[at] = { ...keys[at], ...entry };
+  else keys.push(entry);
+  saveConfig({ keys });
+  return keys;
 }
 
 /**

package/lib/context.js

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Lets a hosted (multi-tenant) MCP transport inject a per-request RootrClient
+ * so the same tool registration functions used by the local stdio CLI server
+ * can be reused without them reading ~/.rootr/config.json or process env
+ * (which are single-tenant, CLI-only concepts). CLI usage never sets this,
+ * so `makeClient()` falls back to `loadConfig()` unchanged.
+ */
+const storage = new AsyncLocalStorage();
+
+export function withClient(client, fn) {
+  return storage.run(client, fn);
+}
+
+export function currentClientOverride() {
+  return storage.getStore();
+}
+
+/**
+ * Per-tool-call sink for the rate-limit headers the API returns. The MCP layer
+ * runs each tool handler inside `withRateLimitSink({})`; `RootrClient.request`
+ * writes whatever `X-RateLimit-*` headers it saw into that object, and the MCP
+ * layer turns a nearly-exhausted quota into a heads-up appended to the tool
+ * result — so the assistant warns the user BEFORE the wall, not after it.
+ *
+ * Async-local (not module-global) on purpose: the hosted transport serves many
+ * workspaces in one process, and one tenant must never see another's quota.
+ */
+const rateLimitStorage = new AsyncLocalStorage();
+
+export function withRateLimitSink(sink, fn) {
+  return rateLimitStorage.run(sink, fn);
+}
+
+export function currentRateLimitSink() {
+  return rateLimitStorage.getStore();
+}

package/lib/mcp-tools/ask.js

@@ -13,6 +13,7 @@ export function registerAskTools(server) {
         'root-cause-analysis style questions ("why did X happen", "what changed before Y") that need to reason ' +
         'across linked documents and LOG anomalies rather than a single document. Requires the `ask` scope. ' +
         'Returns the answer text plus citations pointing at the source documents/quotes it drew from.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         question: z.string().describe('Natural-language question to ask'),
         workspace: z