@indemn/cli 1.5.0 → 1.7.0

package/src/sdk/eval.ts

@@ -1,4 +1,5 @@
 import type { IndemnClient } from './client.js';
+import { CliError, NeedsInputError, SessionExpiredError } from '../core/runtime.js';
 import type {
   EvaluationTriggerInput,
   EvaluationTriggerResponse,
@@ -31,6 +32,114 @@ export class EvalSDK {
     return this.client.evalsGet<BotContext>(`/api/v1/bots/${botId}/context`);
   }
 
+  /**
+   * The evaluations service checks nothing about orgs. Before acting on an
+   * agent, confirm through copilot (which refuses other orgs' agents) that it
+   * belongs to the org this command acts on.
+   */
+  async assertAgentInOrg(agentId: string): Promise<void> {
+    const { AgentsSDK } = await import('./agents.js');
+    const agent = await new AgentsSDK(this.client).getAgent(agentId).catch((err) => {
+      // "Which org?" and "log in again" are not answers about the agent.
+      if (err instanceof NeedsInputError || err instanceof SessionExpiredError) throw err;
+      return undefined;
+    });
+    if (!agent) throw new CliError(`Agent ${agentId} is not in the organization this command acts on. Nothing was run.`);
+  }
+
+  /** A run's agent must be in the org too, so results of other orgs are not read. */
+  async getRunInOrg(runId: string): Promise<EvaluationRun> {
+    const run = await this.getRunStatus(runId);
+    if (run.agent_id) await this.assertAgentInOrg(run.agent_id);
+    return run;
+  }
+
+  qualityMetrics(): Promise<Record<string, unknown>> {
+    return this.client.evalsGet('/api/v1/evaluations/quality-metrics');
+  }
+
+  trends(agentId: string, testSetId?: string, limit = 50): Promise<{ series: unknown[]; drift: unknown }> {
+    const q: Record<string, string> = { agent_id: agentId, limit: String(limit) };
+    if (testSetId) q.test_set_id = testSetId;
+    return this.client.evalsGet('/api/v1/trends', q);
+  }
+
+  compareRuns(runA: string, runB: string): Promise<unknown> {
+    return this.client.evalsGet('/api/v1/trends/compare', { run_a: runA, run_b: runB });
+  }
+
+  /** Server-rendered PDF report of a completed run; returns a link valid for 15 minutes. */
+  exportReport(runId: string, force = false): Promise<{ download_url: string; report_id: string }> {
+    return this.client.evalsPost(`/api/v1/runs/${runId}/export${force ? '?force=true' : ''}`);
+  }
+
+  downloadReport(reportId: string): Promise<{ download_url: string }> {
+    return this.client.evalsGet(`/api/v1/reports/${reportId}/download`);
+  }
+
+  prodCalls(botId: string, opts: { search?: string; limit?: number } = {}): Promise<unknown[]> {
+    const q: Record<string, string> = { bot_id: botId, limit: String(opts.limit ?? 50) };
+    if (opts.search) q.search = opts.search;
+    return this.client.evalsGet('/api/v1/prod-calls', q);
+  }
+
+  prodCall(sessionId: string): Promise<{ bot_id?: string; [k: string]: unknown }> {
+    return this.client.evalsGet(`/api/v1/prod-calls/${sessionId}`);
+  }
+
+  /** Turn an ingested voice call into a regression test item (test set "Regressions (review)"). */
+  promoteProdCall(sessionId: string): Promise<unknown> {
+    return this.client.evalsPost(`/api/v1/prod-calls/${sessionId}/promote`);
+  }
+
+  /** Grade a replayed conversation against a baseline one with the agent's stored evaluator. */
+  async evaluateTranscript(input: { agent_id: string; baseline_transcript: Array<{ sender: 'user' | 'bot'; text: string }>; replay_transcript: Array<{ sender: 'user' | 'bot'; text: string }>; conversation_id?: string }): Promise<unknown> {
+    const res = await this.client.evalsPost<{ success?: boolean; error?: string }>('/api/v1/evaluate-transcript', input);
+    // The service reports internal errors with HTTP 200.
+    if (res && res.success === false && res.error) throw new Error(`Transcript evaluation failed: ${res.error}`);
+    return res;
+  }
+
+  listDatasets(agentId?: string): Promise<unknown[]> {
+    return this.client.evalsGet('/api/v1/datasets', agentId ? { agent_id: agentId } : undefined);
+  }
+
+  getDataset(id: string): Promise<{ agent_id?: string; [k: string]: unknown }> {
+    return this.client.evalsGet(`/api/v1/datasets/${id}`);
+  }
+
+  deleteDataset(id: string): Promise<unknown> {
+    return this.client.evalsDelete(`/api/v1/datasets/${id}`);
+  }
+
+  listTestCases(datasetId: string): Promise<unknown[]> {
+    return this.client.evalsGet(`/api/v1/datasets/${datasetId}/test-cases`);
+  }
+
+  getTestCase(id: string): Promise<unknown> {
+    return this.client.evalsGet(`/api/v1/test-cases/${id}`);
+  }
+
+  deleteTestCase(id: string): Promise<unknown> {
+    return this.client.evalsDelete(`/api/v1/test-cases/${id}`);
+  }
+
+  evaluatorTypes(): Promise<unknown[]> {
+    return this.client.evalsGet('/api/v1/evaluators/types');
+  }
+
+  listEvaluatorConfigs(agentId?: string): Promise<unknown[]> {
+    return this.client.evalsGet('/api/v1/evaluator-configs', agentId ? { agent_id: agentId } : undefined);
+  }
+
+  getEvaluatorConfig(id: string): Promise<{ agent_id?: string; [k: string]: unknown }> {
+    return this.client.evalsGet(`/api/v1/evaluator-configs/${id}`);
+  }
+
+  deleteEvaluatorConfig(id: string): Promise<unknown> {
+    return this.client.evalsDelete(`/api/v1/evaluator-configs/${id}`);
+  }
+
   async pollRunUntilComplete(
     runId: string,
     intervalMs = 5000,
@@ -55,3 +164,34 @@ export class EvalSDK {
     }
   }
 }
+
+export interface GateOptions {
+  /** Fail when passed/total is below this (0..1). */
+  minPassRate?: number;
+  /** Fail when the run's p95 latency is above this. */
+  maxP95Ms?: number;
+  /** block: a failed run fails the gate (default). warn: judge on pass rate and latency only. */
+  errorPolicy?: 'block' | 'warn';
+  /** Also fail when any case had an infrastructure error. */
+  failOnError?: boolean;
+}
+
+/**
+ * The same verdict as the evaluations repo's scripts/eval_gate.py, plus an
+ * optional fail-on-error. pass rate = passed / total, so errored and
+ * unevaluated cases lower it.
+ */
+export function gateVerdict(run: EvaluationRun, opts: GateOptions): { pass: boolean; passRate: number; reasons: string[] } {
+  const reasons: string[] = [];
+  const total = run.total ?? 0;
+  const passRate = total ? (run.passed ?? 0) / total : 0;
+  if ((opts.errorPolicy ?? 'block') === 'block' && run.status === 'failed') reasons.push('run status=failed');
+  if (total === 0) reasons.push('no cases evaluated');
+  if (opts.minPassRate !== undefined && total > 0 && passRate < opts.minPassRate) {
+    reasons.push(`pass rate ${passRate.toFixed(3)} < ${opts.minPassRate}`);
+  }
+  const p95 = run.latency?.p95_ms;
+  if (opts.maxP95Ms !== undefined && typeof p95 === 'number' && p95 > opts.maxP95Ms) reasons.push(`p95 latency ${p95} > ${opts.maxP95Ms}`);
+  if (opts.failOnError && (run.errors ?? 0) > 0) reasons.push(`${run.errors} case(s) errored`);
+  return { pass: reasons.length === 0, passRate, reasons };
+}

package/src/sdk/functions.ts

@@ -1,6 +1,13 @@
 import type { IndemnClient } from './client.js';
+import { CliError } from '../core/runtime.js';
+import { assertSkillNameAllowed } from './skills.js';
 import type { BotFunction, CreateFunctionInput, UpdateFunctionInput, FunctionParameter } from './types.js';
 
+/** Allowed values as copilot stores them (quick-reply buttons); its parameter route parses them from a JSON string. */
+function choices(values: string[]): string {
+  return JSON.stringify(values.map((v) => ({ title: v, payload: v, type: 'postback' })));
+}
+
 export class FunctionsSDK {
   constructor(private client: IndemnClient) {}
 
@@ -11,6 +18,7 @@ export class FunctionsSDK {
   }
 
   async createFunction(agentId: string, input: CreateFunctionInput): Promise<BotFunction> {
+    assertSkillNameAllowed(input.name, input.type);
     return this.client.copilotPost<BotFunction>(
       `/organization/:org_id/ai-studio/bots/${agentId}/functions`,
       input,
@@ -18,6 +26,7 @@ export class FunctionsSDK {
   }
 
   async updateFunction(agentId: string, funcId: string, input: UpdateFunctionInput): Promise<BotFunction> {
+    assertSkillNameAllowed(input.name, input.type);
     return this.client.copilotPut<BotFunction>(
       `/organization/:org_id/ai-studio/bots/${agentId}/functions/${funcId}`,
       input,
@@ -56,13 +65,14 @@ export class FunctionsSDK {
     );
   }
 
-  async addParameter(agentId: string, funcId: string, param: { name: string; type: string; description?: string; required?: boolean }): Promise<FunctionParameter> {
+  async addParameter(agentId: string, funcId: string, param: { name: string; type: string; description?: string; required?: boolean; allowedValues?: string[] }): Promise<FunctionParameter> {
     // Server expects an array of parameters
     const payload = [{
       name: param.name,
       type: param.type,
       description: param.description,
       is_required: param.required ?? false,
+      ...(param.allowedValues?.length ? { enums: choices(param.allowedValues), isEnumsEnabled: true } : {}),
     }];
     return this.client.copilotPost<FunctionParameter>(
       `/organization/:org_id/ai-studio/bots/${agentId}/functions/${funcId}/parameters`,
@@ -70,12 +80,21 @@ export class FunctionsSDK {
     );
   }
 
-  async updateParameter(agentId: string, funcId: string, paramId: string, param: { name?: string; type?: string; description?: string; required?: boolean }): Promise<FunctionParameter> {
-    // Server uses POST upsert (no PUT /:id endpoint exists). Include the param id for upsert matching.
+  async updateParameter(agentId: string, funcId: string, paramId: string, param: { name?: string; type?: string; description?: string; required?: boolean; allowedValues?: string[] }): Promise<FunctionParameter> {
+    // Server uses POST upsert (no PUT /:id endpoint exists) and writes every field it is sent, clearing
+    // allowed values left out: start from the saved parameter so only the named fields change.
+    const current = (await this.listParameters(agentId, funcId)).find((p) => p._id === paramId);
+    if (!current) throw new CliError(`Parameter ${paramId} is not on this skill.`);
     const payload = [{
       id: paramId,
-      ...param,
-      is_required: param.required ?? false,
+      name: param.name ?? current.name,
+      type: param.type ?? current.type,
+      description: param.description ?? current.description,
+      ...(param.description === undefined ? { descriptionOps: current.descriptionOps } : {}),
+      question_title: current.question_title,
+      is_required: param.required ?? current.is_required ?? false,
+      enums: param.allowedValues ? choices(param.allowedValues) : JSON.stringify(current.enums ?? []),
+      isEnumsEnabled: param.allowedValues ? param.allowedValues.length > 0 : (current.isEnumsEnabled ?? false),
     }];
     return this.client.copilotPost<FunctionParameter>(
       `/organization/:org_id/ai-studio/bots/${agentId}/functions/${funcId}/parameters`,
@@ -89,12 +108,39 @@ export class FunctionsSDK {
     );
   }
 
-  async listMasterFunctions(): Promise<unknown[]> {
+  /** Skill templates; copilot filters by channel and assumes web when none is given (so voice ones are hidden). */
+  async listMasterFunctions(channels?: string[]): Promise<unknown[]> {
     return this.client.copilotGet<unknown[]>(
       '/organization/:org_id/ai-studio/master-functions',
+      channels?.length ? { channel: channels.join(',') } : undefined,
     );
   }
 
+  /**
+   * Ask copilot to propose skills from a document (file) or pasted text.
+   * Nothing is created; pass the proposal to bulkCreate after review.
+   */
+  async generateFromDoc(agentId: string, source: { filePath?: string; text?: string }): Promise<unknown> {
+    const path = `/organization/:org_id/ai-studio/bots/${agentId}/functions/generate-from-doc`;
+    if (source.filePath) {
+      const { readFileSync } = await import('node:fs');
+      const { basename } = await import('node:path');
+      const form = new FormData();
+      form.append('file', new Blob([readFileSync(source.filePath)]), basename(source.filePath));
+      return this.client.copilotPostForm(path, form);
+    }
+    return this.client.copilotPost(path, { text: source.text });
+  }
+
+  /** Create several skills at once. Names are checked first; copilot creates them without a transaction. */
+  async bulkCreate(agentId: string, functions: Array<Record<string, unknown>>): Promise<BotFunction[]> {
+    for (const f of functions) {
+      const def = (f.function_definition ?? f) as { name?: string; type?: string };
+      assertSkillNameAllowed(def.name, def.type);
+    }
+    return this.client.copilotPost<BotFunction[]>(`/organization/:org_id/ai-studio/bots/${agentId}/functions/bulk-create`, { functions });
+  }
+
   async listLLMModels(): Promise<unknown[]> {
     return this.client.copilotGet<unknown[]>(
       '/organization/:org_id/ai-studio/llm-models',

package/src/sdk/index.ts

@@ -1,4 +1,6 @@
 export { IndemnClient } from './client.js';
+export { OrgsSDK } from './orgs.js';
+export { resolveCredential, copilotAuthHeader, darwinAuthHeader, type Credential } from './credentials.js';
 export { login, logout, whoami } from './auth.js';
 export { AgentsSDK } from './agents.js';
 export { ConfigSDK } from './config.js';

package/src/sdk/jarvis-chat.ts

@@ -0,0 +1,112 @@
+import type { IndemnClient } from './client.js';
+import { darwinAuthHeader } from './credentials.js';
+import { CliError } from '../core/runtime.js';
+
+export interface JarvisToolEvent {
+  name: string;
+  status: 'running' | 'success' | 'error';
+  error?: string;
+}
+
+export interface JarvisReply {
+  conversation_id: string;
+  reply: string;
+  tools: JarvisToolEvent[];
+}
+
+/** wss://<platform host>/ws, derived from the REST base (…/api/v1), or INDEMN_PLATFORM_WS_URL. */
+export function jarvisSocketUrl(client: IndemnClient): string {
+  if (process.env.INDEMN_PLATFORM_WS_URL) return process.env.INDEMN_PLATFORM_WS_URL;
+  const base = client.getHosts().platform;
+  if (!base) throw new CliError('No V2 platform host is configured for this environment.');
+  const u = new URL(base);
+  u.protocol = u.protocol === 'http:' ? 'ws:' : 'wss:';
+  u.pathname = '/ws';
+  u.search = '';
+  return u.toString();
+}
+
+function userIdFromToken(token: string): string {
+  try {
+    const claims = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')) as { _id?: string };
+    if (claims._id) return claims._id;
+  } catch {
+    // fall through
+  }
+  throw new CliError('The session token has no user id; log in again with `indemn login`.');
+}
+
+/**
+ * One Jarvis turn over Darwin's WebSocket, as the dashboard does it: a
+ * conversation from POST /conversations gives the thread; the reply streams
+ * as jarvis_chunk messages and ends at the first one with done: true (or at an
+ * error message). The session token is sent too, so the chat keeps working
+ * once Darwin starts checking it.
+ */
+export async function jarvisChat(
+  client: IndemnClient,
+  message: string,
+  opts: { conversationId?: string; context?: Record<string, unknown>; timeoutMs?: number; onText?: (text: string) => void; onTool?: (t: JarvisToolEvent) => void } = {},
+): Promise<JarvisReply> {
+  const cred = client.getCredential();
+  if (!cred) throw new CliError('Not logged in. Run `indemn login` first.');
+  const authorization = darwinAuthHeader(cred);
+  const token = authorization.slice('Bearer '.length);
+  const orgId = await client.currentOrgId();
+  const conversationId = opts.conversationId ?? (await client.platformRequest<{ conversation_id: string }>('POST', '/conversations', {
+    body: { title: message.slice(0, 60) },
+  })).conversation_id;
+
+  const url = new URL(jarvisSocketUrl(client));
+  url.searchParams.set('client_id', `indemn-cli-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`);
+  url.searchParams.set('user_id', userIdFromToken(token));
+  url.searchParams.set('organization_id', orgId);
+
+  return new Promise<JarvisReply>((resolve, reject) => {
+    const WS = globalThis.WebSocket as unknown as new (u: string, init?: unknown) => WebSocket;
+    // Node's WebSocket (undici) accepts headers in its init object; browsers would ignore it.
+    const socket = new WS(url.toString(), { headers: { Authorization: authorization } });
+    let reply = '';
+    const tools = new Map<string, JarvisToolEvent>();
+    let settled = false;
+    const finish = (err?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearInterval(ping);
+      try { socket.close(); } catch { /* already closed */ }
+      if (err) reject(err);
+      else resolve({ conversation_id: conversationId, reply, tools: [...tools.values()] });
+    };
+    const timer = setTimeout(() => finish(new CliError(`Jarvis did not finish within ${Math.round((opts.timeoutMs ?? 180_000) / 1000)} s.`)), opts.timeoutMs ?? 180_000);
+    const ping = setInterval(() => {
+      try { socket.send(JSON.stringify({ type: 'ping', payload: {} })); } catch { /* not open yet */ }
+    }, 15_000);
+
+    socket.addEventListener('open', () => {
+      socket.send(JSON.stringify({ type: 'jarvis', payload: { content: message, thread_id: conversationId, ...(opts.context ? { context: opts.context } : {}) } }));
+    });
+    socket.addEventListener('message', (ev: MessageEvent) => {
+      let msg: { type?: string; payload?: Record<string, any> };
+      try { msg = JSON.parse(String(ev.data)); } catch { return; }
+      const p = msg.payload ?? {};
+      if (msg.type === 'jarvis_chunk') {
+        if (p.content) { reply += p.content; opts.onText?.(p.content); }
+        if (p.done) finish();
+      } else if (msg.type === 'jarvis_tool' && p.tool_call) {
+        // Darwin sends "start" twice per tool with different ids; key by name while running.
+        const name = String(p.tool_call.name ?? 'tool');
+        const status = p.tool_call.status === 'error' ? 'error' : p.tool_call.status === 'success' ? 'success' : 'running';
+        const evt: JarvisToolEvent = { name, status, ...(p.tool_call.error ? { error: String(p.tool_call.error) } : {}) };
+        const key = status === 'running' ? `${name}#running` : `${name}#${p.tool_call.id}`;
+        if (status !== 'running') tools.delete(`${name}#running`);
+        if (!tools.has(key)) opts.onTool?.(evt);
+        tools.set(key, evt);
+      } else if (msg.type === 'error') {
+        finish(new CliError(`Jarvis: ${p.message ?? 'error'}`));
+      }
+    });
+    socket.addEventListener('error', () => finish(new CliError('Could not reach Jarvis on the V2 platform.')));
+    socket.addEventListener('close', () => finish(new CliError('The Jarvis connection closed before the reply finished; any action it was taking may or may not have completed.')));
+  });
+}

package/src/sdk/kb.ts

@@ -26,9 +26,12 @@ export class KBSDK {
   }
 
   async createKB(input: CreateKBInput): Promise<KnowledgeBase> {
+    // copilot validates the type case-insensitively but stores it raw, and only
+    // the uppercase values (QNA, URL, FILE) are valid afterwards.
+    const type = (input as { type?: string }).type;
     return this.client.copilotPost<KnowledgeBase>(
       '/organization/:org_id/knowledge-bases',
-      input,
+      { ...input, ...(type ? { type: type.toUpperCase() } : {}) },
     );
   }
 
@@ -74,52 +77,65 @@ export class KBSDK {
     );
   }
 
+  /**
+   * Import a website the way the dashboard does: "selected" imports the given page (the source url
+   * is its site), "full" crawls the whole site from url. copilot fails without the full source shape.
+   */
   async scrapeUrl(kbId: string, url: string, crawlMode: string = 'full'): Promise<unknown> {
+    const selected = crawlMode === 'selected';
+    let site = url;
+    if (selected) {
+      try { site = new URL(url).origin; } catch { site = url; }
+    }
     return this.client.copilotPost(
       `/organization/:org_id/knowledge-bases/${kbId}/import`,
       {
         type: 'url',
-        sources: [{ url, crawl_mode: crawlMode }],
+        manual: false,
+        sources: [{ url: site, crawl_mode: selected ? 'selected' : 'full', selected_urls: selected ? [url] : [], exclude_urls: [], js_script: '' }],
       },
     );
   }
 
-  async uploadFile(kbId: string, filePath: string): Promise<unknown> {
+  /**
+   * Add a document to a knowledge base the way the dashboard does: upload it
+   * to the org's file store for a signed link, then ask the knowledge base to
+   * import from that link. (The upload-urls route is only for a CSV of website
+   * addresses.) Pass qna: true for a file of question/answer rows.
+   */
+  async uploadFile(kbId: string, filePath: string, opts: { qna?: boolean } = {}): Promise<unknown> {
     const fs = await import('fs');
     const path = await import('path');
 
     if (!fs.existsSync(filePath)) {
       throw new Error(`File not found: ${filePath}`);
     }
-
-    const fileBuffer = fs.readFileSync(filePath);
     const fileName = path.basename(filePath);
-    const blob = new Blob([fileBuffer]);
+    const ext = path.extname(fileName).slice(1).toLowerCase();
+    const allowed = ['pdf', 'docx', 'doc', 'txt', 'csv', 'xls', 'xlsx', 'json'];
+    if (!allowed.includes(ext)) {
+      throw new Error(`Unsupported file type ".${ext}". Knowledge bases accept: ${allowed.join(', ')}.`);
+    }
+    const size = fs.statSync(filePath).size;
+    if (size > 10 * 1024 * 1024) {
+      throw new Error(`${fileName} is ${(size / 1024 / 1024).toFixed(1)} MB; the limit is 10 MB.`);
+    }
 
     const formData = new FormData();
-    formData.append('file', blob, fileName);
-
-    // Need a raw fetch since copilotPost sets Content-Type to JSON
-    const hosts = this.client.getHosts();
-    const orgId = this.client.getOrgId();
-    const apiKey = this.client.getApiKey();
-    const url_str = `${hosts.copilot}/organization/${orgId}/knowledge-bases/${kbId}/upload-urls`;
-
-    const res = await fetch(url_str, {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${apiKey}`,
-      },
-      body: formData,
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw new Error(`Upload failed (${res.status}): ${text}`);
-    }
+    formData.append('file', new Blob([fs.readFileSync(filePath)]), fileName);
+    const stored = await this.client.copilotPostForm<{ url?: string; signedUrl?: string; data?: { url?: string; signedUrl?: string } }>(
+      '/organization/:org_id/files/upload-org?generateSignedUrl=true',
+      formData,
+    );
+    // The import service must fetch the file, so it needs the signed link.
+    const url = stored?.signedUrl ?? stored?.data?.signedUrl ?? stored?.url ?? stored?.data?.url;
+    if (!url) throw new Error(`Uploading ${fileName} returned no file link; nothing was imported.`);
 
-    const json = await res.json() as { data?: unknown };
-    return json.data || json;
+    return this.importKB(kbId, {
+      type: 'file',
+      sources: [{ name: fileName, file_type: ext, url }],
+      ...(opts.qna ? { is_qna_import: true } : {}),
+    });
   }
 
   async updateDataSource(
@@ -139,6 +155,11 @@ export class KBSDK {
     );
   }
 
+  /** Knowledge bases linked to an agent: [{ id (KB id), name, type, connectedBots }]. */
+  async listMappings(agentId: string): Promise<Array<{ id: string; name?: string; type?: string; connectedBots?: Array<{ id: string; id_mapping: string }> }>> {
+    return this.client.copilotGet(`/organization/:org_id/ai-studio/bots/${agentId}/mappings`);
+  }
+
   async linkKB(agentId: string, kbIds: string[]): Promise<unknown> {
     return this.client.copilotPost(
       `/organization/:org_id/ai-studio/bots/${agentId}/mappings`,
@@ -175,9 +196,75 @@ export class KBSDK {
   }
 
   async importKB(kbId: string, data: unknown): Promise<unknown> {
-    return this.client.copilotPost(
+    const result = await this.client.copilotPost<{ status?: string; message?: string }>(
       `/organization/:org_id/knowledge-bases/${kbId}/import`,
       data,
     );
+    assertJobStarted(result, 'Import');
+    return result;
+  }
+
+  /** The text chunks the agent actually retrieves from one data source. */
+  async chunks(kbId: string, sourceId: string): Promise<{ id: string; type?: string; source?: string; status?: string; stats?: unknown; chunks: string[] }> {
+    return this.client.copilotGet(`/organization/:org_id/knowledge-bases/${kbId}/data-source/${sourceId}/chunks`);
+  }
+
+  /** Crawl a URL source again (asynchronous). URL sources only. */
+  async reimport(kbId: string, sourceId: string, jsScript?: string): Promise<unknown> {
+    const result = await this.client.copilotPut<{ status?: string; message?: string }>(
+      `/organization/:org_id/knowledge-bases/${kbId}/data-source/${sourceId}/re-import`,
+      jsScript ? { js_script: jsScript } : {},
+    );
+    assertJobStarted(result, 'Re-import');
+    return result;
+  }
+
+  /**
+   * Crawl and file-import status. copilot has no status route, so this reads
+   * the KB's non-manual sources and their scrape jobs.
+   */
+  async scrapeStatus(kbId: string): Promise<Array<{ id?: string; source?: string; status?: string; job_status?: string; error?: string; completed_at?: string }>> {
+    const kb = await this.getKB(kbId) as unknown as { fileWebSources?: Array<Record<string, any>> };
+    return (kb.fileWebSources ?? []).map((s) => ({
+      id: s._id ? String(s._id) : undefined,
+      source: s.source,
+      status: s.status,
+      job_status: s.source_details?.id_scrape_request?.status,
+      error: s.error_message ?? s.source_details?.id_scrape_request?.message,
+      completed_at: s.source_details?.id_scrape_request?.completed_at ?? undefined,
+    }));
+  }
+
+  /** Questions the agents could not answer (0-based pages). */
+  async gaps(opts: { agentId?: string; kbId?: string; page?: number; limit?: number; includeTest?: boolean; dismissed?: boolean; resolved?: boolean } = {}): Promise<unknown> {
+    const query: Record<string, string> = {
+      page: String(opts.page ?? 0),
+      limit: String(Math.min(opts.limit ?? 20, 100)),
+      isDismissed: String(Boolean(opts.dismissed)),
+      isTestMode: String(Boolean(opts.includeTest)),
+    };
+    if (opts.agentId) query.id_bot = opts.agentId;
+    if (opts.kbId) query.id_kb = opts.kbId;
+    if (opts.resolved) query.view = 'resolved';
+    return this.client.copilotGet('/organization/:org_id/knowledge-bases/unanswered/embeddings', query);
+  }
+
+  /** Unanswered questions grouped by theme, most frequent first. */
+  async gapClusters(opts: { status?: 'open' | 'resolved' | 'dismissed'; days?: number; page?: number; limit?: number } = {}): Promise<unknown> {
+    const query: Record<string, string> = { status: opts.status ?? 'open', page: String(opts.page ?? 0), limit: String(Math.min(opts.limit ?? 50, 100)) };
+    if (opts.days) query.days = String(opts.days);
+    return this.client.copilotGet('/organization/:org_id/knowledge-bases/unanswered/clusters', query);
+  }
+
+  /** Could the org's knowledge answer this question? Returns the best matching chunks. */
+  async check(question: string): Promise<{ answerable?: boolean; top_score?: number; sources?: unknown[] }> {
+    return this.client.copilotGet('/organization/:org_id/knowledge-bases/unanswered/kb-check', { query: question });
+  }
+}
+
+/** copilot answers import and re-import with success:true even when they fail; the job status tells the truth. */
+function assertJobStarted(result: { status?: string; message?: string } | undefined, what: string): void {
+  if (result && result.status === 'error') {
+    throw new Error(`${what} failed: ${result.message ?? 'no reason given'}`);
   }
 }

package/src/sdk/orgs.ts

@@ -0,0 +1,62 @@
+import { IndemnClient } from './client.js';
+import type { Channel, OrgMember, OrgSummary } from './types.js';
+
+interface RawProjectUser {
+  role?: string;
+  status?: string;
+  id_user?: { _id?: string; email?: string; firstname?: string; lastname?: string } | string | null;
+  id_project?: { name?: string } | string | null;
+}
+
+export class OrgsSDK {
+  constructor(private client: IndemnClient) {}
+
+  /** Orgs the logged-in person belongs to or created. Also refreshes the list saved at login. */
+  async listOrganizations(): Promise<OrgSummary[]> {
+    const res = await this.client.copilotGet<{ userOrganizations?: Array<{ _id: string; name: string }> }>('/organization');
+    const orgs = (res.userOrganizations ?? []).map((o) => ({ id: String(o._id), name: o.name }));
+    if (this.client.getCredential()?.source === 'config') IndemnClient.saveConfig({ orgs });
+    return orgs;
+  }
+
+  /** People with owner, admin or agent roles in the org, one row per person. */
+  async listMembers(): Promise<OrgMember[]> {
+    let rows: RawProjectUser[];
+    try {
+      const res = await this.client.copilotGet<{ projectUsers?: RawProjectUser[] }>('/organization/:org_id/projects-users');
+      rows = res.projectUsers ?? [];
+    } catch (err) {
+      // copilot answers "not found" with success:false when the org has no such members.
+      if (err instanceof Error && /not found for the given organization/i.test(err.message)) return [];
+      throw err;
+    }
+    const byUser = new Map<string, OrgMember>();
+    for (const row of rows) {
+      const user = typeof row.id_user === 'object' && row.id_user ? row.id_user : { _id: String(row.id_user ?? '') };
+      const id = String(user._id ?? '');
+      if (!id) continue;
+      const project = typeof row.id_project === 'object' && row.id_project ? row.id_project.name : undefined;
+      const existing = byUser.get(id);
+      if (existing) {
+        if (project && !existing.projects.includes(project)) existing.projects.push(project);
+        continue;
+      }
+      const name = [('firstname' in user ? user.firstname : ''), ('lastname' in user ? user.lastname : '')].filter(Boolean).join(' ');
+      byUser.set(id, {
+        user_id: id,
+        email: 'email' in user ? user.email : undefined,
+        name: name || undefined,
+        role: row.role,
+        status: row.status,
+        projects: project ? [project] : [],
+      });
+    }
+    return [...byUser.values()];
+  }
+
+  /** Channels an agent can be published on (WEB, VOICE, ...). */
+  async listChannels(): Promise<Channel[]> {
+    const channels = await this.client.copilotGet<Channel[]>('/organization/:org_id/ai-studio/channels');
+    return channels.map((c) => ({ _id: String(c._id), name: c.name, type: c.type, description: c.description }));
+  }
+}