@indemn/cli 1.6.0 → 1.7.0

package/src/sdk/client.ts

@@ -1,42 +1,108 @@
 import Conf from 'conf';
 import { chmodSync } from 'node:fs';
 import type { ApiResponse, Environment, EnvironmentHosts, IndemnConfig } from './types.js';
+import { CliError, cliVersion, isDebug, SessionExpiredError } from '../core/runtime.js';
+import { copilotAuthHeader, darwinAuthHeader, resolveCredential, type Credential } from './credentials.js';
+import { exchangeIdToken, needsRenewal, refreshIdToken, toStoredSession } from './session.js';
+import { findLinkFile, resolveOrg, type LinkFile, type OrgChoice, type ResolvedOrg } from '../core/org-resolver.js';
+import { emitOrgResolved, getAskers, getOrgFlag, scopedOrg } from '../core/scope.js';
 
-const DEFAULT_HOSTS: Record<Environment, EnvironmentHosts> = {
+export const DEFAULT_HOSTS: Record<Environment, EnvironmentHosts> = {
   dev: {
     copilot: 'https://devcopilot.indemn.ai/api',
     evaluations: 'https://devevaluations.indemn.ai',
     middleware: 'https://devproxy.indemn.ai',
+    platform: 'https://devplatform.indemn.ai/api/v1',
   },
   production: {
     copilot: 'https://copilot.indemn.ai/api',
     evaluations: 'https://evaluations.indemn.ai',
     middleware: 'https://proxy.indemn.ai',
+    platform: 'https://platform.indemn.ai/api/v1',
   },
 };
 
+export type ClientKind = 'cli' | 'mcp';
+let clientKind: ClientKind = 'cli';
+
+type Backend = 'copilot' | 'evaluations' | 'platform';
+type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+interface SendOptions {
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** Attach the credential. False only for the login exchange. */
+  auth?: boolean;
+}
+
+const RETRY_STATUSES = new Set([502, 503, 504]);
+const RETRY_DELAYS_MS = [300, 600];
+
+function isEnvironment(value: unknown): value is Environment {
+  return value === 'dev' || value === 'production';
+}
+
+/**
+ * The environment belongs to the credential. A saved login knows its own
+ * environment; an API key says it in its prefix. INDEMN_ENV is only read for a
+ * host-supplied session token (INDEMN_TOKEN), which carries no environment.
+ */
+export function resolveEnvironment(config: IndemnConfig | null, env: NodeJS.ProcessEnv = process.env): Environment {
+  if (env.INDEMN_TOKEN && isEnvironment(env.INDEMN_ENV)) return env.INDEMN_ENV;
+  if (env.INDEMN_API_KEY?.startsWith('ind_live_')) return 'production';
+  if (env.INDEMN_API_KEY?.startsWith('ind_dev_')) return 'dev';
+  if (config && isEnvironment(config.environment)) return config.environment;
+  return 'dev';
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** One renewal at a time per process, shared by every client. */
+let renewing: Promise<void> | null = null;
+
+export interface OrgContext extends ResolvedOrg {
+  name?: string;
+}
+
 export class IndemnClient {
-  private apiKey: string;
-  private orgId: string;
+  private explicitCredential: Credential | null;
+  private orgOverride?: string;
   private environment: Environment;
   private hosts: EnvironmentHosts;
+  private resolvedOrg?: Promise<OrgContext>;
+  private linkCache?: LinkFile | null;
+  private membershipCache?: OrgChoice[];
 
-  constructor(opts?: { apiKey?: string; orgId?: string; environment?: Environment }) {
-    // Priority: explicit opts > env vars > config file
-    const config = IndemnClient.loadConfig();
+  private ignoreLink: boolean;
 
-    this.apiKey = opts?.apiKey || process.env.INDEMN_API_KEY || config?.api_key || '';
-    this.orgId = opts?.orgId || process.env.INDEMN_ORG_ID || config?.org_id || '';
-    this.environment = opts?.environment || (process.env.INDEMN_ENV as Environment) || config?.environment || 'dev';
+  constructor(opts?: { apiKey?: string; token?: string; orgId?: string; environment?: Environment; ignoreLink?: boolean }) {
+    const config = IndemnClient.loadConfig();
+    const env = opts?.environment || resolveEnvironment(config);
+    this.explicitCredential = opts?.token
+      ? { kind: 'token', token: opts.token, source: 'env', environment: env }
+      : opts?.apiKey
+        ? { kind: 'api_key', key: opts.apiKey, source: 'env', environment: env }
+        : null;
+    this.orgOverride = opts?.orgId;
+    this.ignoreLink = Boolean(opts?.ignoreLink);
+    this.environment = env;
     const defaultHosts = DEFAULT_HOSTS[this.environment];
     const configHosts = config?.hosts?.[this.environment];
     this.hosts = {
       copilot: process.env.INDEMN_COPILOT_URL || configHosts?.copilot || defaultHosts.copilot,
       evaluations: process.env.INDEMN_EVALS_URL || configHosts?.evaluations || defaultHosts.evaluations,
       middleware: process.env.INDEMN_MIDDLEWARE_URL || configHosts?.middleware || defaultHosts.middleware,
+      platform: process.env.INDEMN_PLATFORM_URL || configHosts?.platform || defaultHosts.platform,
     };
   }
 
+  /** Name the caller in the X-Indemn-Client header: the terminal CLI or the MCP server. */
+  static setClientKind(kind: ClientKind): void {
+    clientKind = kind;
+  }
+
   static getConfigStore(): Conf<IndemnConfig> {
     return new Conf<IndemnConfig>({
       projectName: 'indemn',
@@ -45,17 +111,20 @@ export class IndemnClient {
     });
   }
 
+  /** The saved login, or null. Read fresh on every request so a new login in another terminal is picked up. */
   static loadConfig(): IndemnConfig | null {
     try {
       const store = IndemnClient.getConfigStore();
+      const session = store.get('session');
       const apiKey = store.get('api_key');
-      if (!apiKey) return null;
+      if (!session?.token && !apiKey) return null;
       return {
-        api_key: apiKey,
-        org_id: store.get('org_id', ''),
-        org_name: store.get('org_name', '') || undefined,
-        user_id: store.get('user_id', ''),
         environment: store.get('environment', 'dev'),
+        user_id: store.get('user_id', ''),
+        email: store.get('email'),
+        session,
+        orgs: store.get('orgs'),
+        api_key: apiKey,
         hosts: store.get('hosts', DEFAULT_HOSTS),
       };
     } catch {
@@ -66,9 +135,10 @@ export class IndemnClient {
   static saveConfig(config: Partial<IndemnConfig>): void {
     const store = IndemnClient.getConfigStore();
     for (const [key, value] of Object.entries(config)) {
-      store.set(key as keyof IndemnConfig, value);
+      if (value === undefined) store.delete(key as keyof IndemnConfig);
+      else store.set(key as keyof IndemnConfig, value);
     }
-    // Restrict config file to owner-only (contains API key)
+    // Restrict config file to owner-only (contains credentials)
     try {
       chmodSync(store.path, 0o600);
     } catch {
@@ -82,19 +152,158 @@ export class IndemnClient {
   }
 
   getEnvironment(): Environment { return this.environment; }
-  getOrgId(): string { return this.orgId; }
-  getApiKey(): string { return this.apiKey; }
   getHosts(): EnvironmentHosts { return this.hosts; }
 
-  private ensureAuth(): void {
-    if (!this.apiKey) {
-      throw new Error('Not authenticated. Run `indemn login` first.');
+  /** The credential for the next request. Never cached: the saved login may have been renewed or replaced. */
+  getCredential(): Credential | null {
+    return this.explicitCredential ?? resolveCredential(IndemnClient.loadConfig());
+  }
+
+  private requireCredential(): Credential {
+    const cred = this.getCredential();
+    if (!cred) throw new SessionExpiredError('Not logged in. Run `indemn login` first.');
+    return cred;
+  }
+
+  /**
+   * Get a fresh copilot session with the saved Firebase refresh token, save
+   * it, and revoke the old one. Accounts with MFA are asked for the emailed
+   * code when a terminal or MCP host can ask; otherwise the person must log in.
+   */
+  async renewSession(): Promise<void> {
+    if (renewing) return renewing;
+    renewing = (async () => {
+      const config = IndemnClient.loadConfig();
+      const old = config?.session;
+      if (!config || !old?.refresh_token) {
+        throw new SessionExpiredError('Session expired. Run `indemn login`, then retry.');
+      }
+      const { idToken, refreshToken } = await refreshIdToken(config.environment, old.refresh_token);
+      const { token } = await exchangeIdToken(
+        (path, body, headers) => this.copilotPostUnauth(path, body, headers),
+        idToken,
+        getAskers().mfaCode,
+      );
+      IndemnClient.saveConfig({ session: toStoredSession(token, refreshToken) });
+      try {
+        await this.send('copilot', 'POST', `${this.hosts.copilot}/auth/firebase/logout`, {
+          auth: false,
+          headers: { Authorization: `JWT ${old.token}` },
+        });
+      } catch {
+        // Best effort: the old token expires within the hour anyway.
+      }
+    })().finally(() => {
+      renewing = null;
+    });
+    return renewing;
+  }
+
+  /** The credential for the next request, renewed first when a saved session is about to expire. */
+  private async freshCredential(): Promise<Credential> {
+    let cred = this.requireCredential();
+    if (cred.kind === 'token' && cred.source === 'config') {
+      const session = IndemnClient.loadConfig()?.session;
+      if (session && needsRenewal(session)) {
+        await this.renewSession();
+        cred = this.requireCredential();
+      }
+    }
+    return cred;
+  }
+
+  private async authHeader(): Promise<string> {
+    return copilotAuthHeader(await this.freshCredential());
+  }
+
+  // --- Organizations -------------------------------------------------------
+
+  /** The `.indemn/project.json` in effect for this working directory. */
+  getLink(): LinkFile | null {
+    if (this.ignoreLink) return null;
+    if (this.linkCache === undefined) this.linkCache = findLinkFile();
+    return this.linkCache;
+  }
+
+  /** Orgs the user belongs to: saved at login, else asked live from copilot. */
+  async memberships(): Promise<OrgChoice[]> {
+    if (this.membershipCache) return this.membershipCache;
+    const cred = this.requireCredential();
+    const saved = cred.source === 'config' ? IndemnClient.loadConfig()?.orgs : undefined;
+    if (saved?.length) {
+      this.membershipCache = saved;
+    } else {
+      const res = await this.copilotGet<{ userOrganizations?: Array<{ _id: string; name: string }> }>('/organization');
+      this.membershipCache = (res.userOrganizations ?? []).map((o) => ({ id: String(o._id), name: o.name }));
+    }
+    return this.membershipCache;
+  }
+
+  /**
+   * The org this client acts on. `explicit` is an MCP tool's org_id; the
+   * terminal passes --org through the scope module. Decided once per client.
+   */
+  async resolveOrg(explicit?: string, opts: { cache?: boolean } = {}): Promise<OrgContext> {
+    const run = async (): Promise<OrgContext> => {
+      const resolved = await resolveOrg({
+        flag: explicit ?? this.orgOverride ?? getOrgFlag(),
+        envOrg: process.env.INDEMN_ORG_ID || undefined,
+        link: this.getLink(),
+        environment: this.environment,
+        memberships: () => this.memberships(),
+        ask: getAskers().chooseOrg,
+      });
+      const known = this.membershipCache ?? IndemnClient.loadConfig()?.orgs ?? [];
+      const name = known.find((o) => o.id === resolved.id)?.name ?? resolved.link?.org_name;
+      return { ...resolved, name };
+    };
+    if (explicit || opts.cache === false) return run();
+    if (!this.resolvedOrg) {
+      this.resolvedOrg = run().then((org) => {
+        emitOrgResolved({ id: org.id, name: org.name, source: org.source, environment: this.environment });
+        return org;
+      });
+      this.resolvedOrg.catch(() => { this.resolvedOrg = undefined; });
+    }
+    return this.resolvedOrg;
+  }
+
+  /** Org id for the current call: an MCP call's scope first, then this client's resolution. */
+  async currentOrgId(): Promise<string> {
+    return scopedOrg() ?? (await this.resolveOrg()).id;
+  }
+
+  /** What every MCP result reports as its origin. Never triggers a question. */
+  async getResultContext(): Promise<{ org_id?: string; org_name?: string; environment: Environment }> {
+    const scoped = scopedOrg();
+    const settled = this.resolvedOrg ? await this.resolvedOrg.catch(() => undefined) : undefined;
+    const id = scoped ?? settled?.id;
+    const known = this.membershipCache ?? IndemnClient.loadConfig()?.orgs ?? [];
+    return { org_id: id, org_name: id ? known.find((o) => o.id === id)?.name : undefined, environment: this.environment };
+  }
+
+  /**
+   * In a linked folder with an agent list, refuse any agent that is not on
+   * the list before a request leaves the machine.
+   */
+  private assertAgentInScope(path: string): void {
+    const link = this.getLink();
+    if (!link || link.agents.length === 0) return;
+    const match = /\/bots\/([a-f0-9]{24})(?:\/|$|\?)/i.exec(path);
+    if (match && !link.agents.includes(match[1])) {
+      throw new CliError(
+        `Agent ${match[1]} is not linked in ${link.path}. Linked agents: ${link.agents.join(', ')}. ` +
+          'Add it with `indemn link` or work from another folder.',
+      );
     }
   }
 
-  private buildCopilotUrl(path: string): string {
-    // Inject org_id into path templates
-    const resolvedPath = path.replace(':org_id', this.orgId);
+  private async buildCopilotUrl(path: string): Promise<string> {
+    let resolvedPath = path;
+    if (path.includes(':org_id')) {
+      resolvedPath = path.replace(':org_id', await this.currentOrgId());
+    }
+    this.assertAgentInScope(resolvedPath);
     return `${this.hosts.copilot}${resolvedPath}`;
   }
 
@@ -102,134 +311,196 @@ export class IndemnClient {
     return `${this.hosts.evaluations}${path}`;
   }
 
-  // Copilot Server requests (with /api/ prefix and org_id injection)
-  async copilotGet<T = unknown>(path: string, query?: Record<string, string>): Promise<T> {
-    this.ensureAuth();
-    const url = new URL(this.buildCopilotUrl(path));
-    if (query) {
-      for (const [k, v] of Object.entries(query)) {
-        if (v !== undefined && v !== null) url.searchParams.set(k, v);
+  /**
+   * The one place every request goes through: client headers, credential,
+   * --debug tracing, and retries for reads only (a retried create could
+   * create twice).
+   */
+  private async send(backend: Backend, method: Method, url: string, opts: SendOptions = {}): Promise<Response> {
+    const headers: Record<string, string> = {
+      'User-Agent': `indemn-cli/${cliVersion()}`,
+      'X-Indemn-Client': clientKind,
+      ...opts.headers,
+    };
+    let body: BodyInit | undefined;
+    if (opts.body instanceof FormData) {
+      body = opts.body;
+    } else if (opts.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      body = JSON.stringify(opts.body);
+    } else if (method !== 'GET') {
+      headers['Content-Type'] = 'application/json';
+    }
+    if (backend === 'copilot' && opts.auth !== false) {
+      headers['Authorization'] = await this.authHeader();
+    }
+
+    const attempts = method === 'GET' ? RETRY_DELAYS_MS.length + 1 : 1;
+    for (let attempt = 0; ; attempt++) {
+      const started = Date.now();
+      if (isDebug()) process.stderr.write(`[debug] → ${method} ${url}\n`);
+      try {
+        const res = await fetch(url, { method, headers, body });
+        if (isDebug()) process.stderr.write(`[debug] ← ${res.status} ${method} ${url} (${Date.now() - started} ms)\n`);
+        if (RETRY_STATUSES.has(res.status) && attempt + 1 < attempts) {
+          await sleep(RETRY_DELAYS_MS[attempt]);
+          continue;
+        }
+        return res;
+      } catch (err) {
+        if (isDebug()) process.stderr.write(`[debug] ✗ ${method} ${url}: ${(err as Error).message}\n`);
+        if (attempt + 1 < attempts) {
+          await sleep(RETRY_DELAYS_MS[attempt]);
+          continue;
+        }
+        throw err;
       }
     }
-    const res = await fetch(url.toString(), {
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-    });
+  }
+
+  private withQuery(url: string, query?: Record<string, string>): string {
+    if (!query) return url;
+    const u = new URL(url);
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null) u.searchParams.set(k, v);
+    }
+    return u.toString();
+  }
+
+  /**
+   * A copilot request with the session rules: renew before expiry, and on a
+   * 401 with a saved session renew once and retry once.
+   */
+  private async copilotRequest<T>(method: Method, path: string, opts: { body?: unknown; query?: Record<string, string> } = {}): Promise<T> {
+    const url = this.withQuery(await this.buildCopilotUrl(path), opts.query);
+    let res = await this.send('copilot', method, url, { body: opts.body });
+    const cred = this.getCredential();
+    if (res.status === 401 && cred?.kind === 'token' && cred.source === 'config') {
+      await this.renewSession();
+      res = await this.send('copilot', method, url, { body: opts.body });
+    }
     return this.handleCopilotResponse<T>(res);
   }
 
+  /** A copilot request with any method (for PATCH and other routes without a helper). */
+  async copilotRequestRaw<T = unknown>(method: Method | 'PATCH', path: string, body?: unknown): Promise<T> {
+    return this.copilotRequest<T>(method as Method, path, { body });
+  }
+
+  /** A copilot request whose answer is a file or audio, returned as bytes. */
+  async copilotBinary(method: Method, path: string, body?: unknown): Promise<{ contentType: string; data: Buffer }> {
+    const res = await this.send('copilot', method, await this.buildCopilotUrl(path), { body });
+    if (res.status === 401) throw new SessionExpiredError('Authentication failed. Run `indemn login` to re-authenticate.');
+    if (!res.ok) throw new Error(`API error (${res.status}): ${await res.text()}`);
+    return { contentType: res.headers.get('content-type') ?? 'application/octet-stream', data: Buffer.from(await res.arrayBuffer()) };
+  }
+
+  // Copilot Server requests (with /api/ prefix and org_id injection)
+  async copilotGet<T = unknown>(path: string, query?: Record<string, string>): Promise<T> {
+    return this.copilotRequest<T>('GET', path, { query });
+  }
+
   async copilotPost<T = unknown>(path: string, body?: unknown): Promise<T> {
-    this.ensureAuth();
-    const res = await fetch(this.buildCopilotUrl(path), {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-    return this.handleCopilotResponse<T>(res);
+    return this.copilotRequest<T>('POST', path, { body });
+  }
+
+  /** Multipart upload (for example a knowledge-base file). */
+  async copilotPostForm<T = unknown>(path: string, form: FormData): Promise<T> {
+    return this.copilotRequest<T>('POST', path, { body: form });
   }
 
   async copilotPut<T = unknown>(path: string, body?: unknown): Promise<T> {
-    this.ensureAuth();
-    const res = await fetch(this.buildCopilotUrl(path), {
-      method: 'PUT',
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-    return this.handleCopilotResponse<T>(res);
+    return this.copilotRequest<T>('PUT', path, { body });
   }
 
   async copilotDelete<T = unknown>(path: string): Promise<T> {
-    this.ensureAuth();
-    const res = await fetch(this.buildCopilotUrl(path), {
-      method: 'DELETE',
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-    });
-    return this.handleCopilotResponse<T>(res);
+    return this.copilotRequest<T>('DELETE', path);
   }
 
-  // Evaluations Service requests (no /api/ prefix, no org_id, no auth in Phase 1)
-  async evalsGet<T = unknown>(path: string, query?: Record<string, string>): Promise<T> {
-    const url = new URL(this.buildEvalsUrl(path));
-    if (query) {
-      for (const [k, v] of Object.entries(query)) {
-        if (v !== undefined && v !== null) url.searchParams.set(k, v);
-      }
+  /**
+   * Darwin (the V2 platform) request: the same session token as copilot, sent
+   * as Bearer, with the org in X-Organization-Id. Darwin checks membership and
+   * roles itself. A 401 on a saved session renews once and retries once.
+   */
+  async platformRequest<T = unknown>(method: Method, path: string, opts: { body?: unknown; query?: Record<string, string>; orgHeader?: boolean } = {}): Promise<T> {
+    const base = this.hosts.platform;
+    if (!base) throw new CliError('No V2 platform host is configured for this environment.');
+    const url = this.withQuery(`${base}${path}`, opts.query);
+    this.assertAgentInScope(path);
+    const headersFor = async (): Promise<Record<string, string>> => {
+      const headers: Record<string, string> = { Authorization: darwinAuthHeader(await this.freshCredential()) };
+      if (opts.orgHeader !== false) headers['X-Organization-Id'] = await this.currentOrgId();
+      return headers;
+    };
+    let res = await this.send('platform', method, url, { body: opts.body, headers: await headersFor() });
+    const cred = this.getCredential();
+    if (res.status === 401 && cred?.kind === 'token' && cred.source === 'config') {
+      await this.renewSession();
+      res = await this.send('platform', method, url, { body: opts.body, headers: await headersFor() });
     }
-    const res = await fetch(url.toString(), {
-      headers: { 'Content-Type': 'application/json' },
-    });
+    if (res.status === 401) throw new SessionExpiredError('The V2 platform rejected the session. Run `indemn login`, then retry.');
+    if (!res.ok) {
+      const text = await res.text();
+      let detail = text;
+      try { detail = (JSON.parse(text) as { detail?: unknown }).detail as string ?? text; } catch { /* plain text */ }
+      if (res.status === 403) throw new CliError(`Not allowed by the V2 platform: ${typeof detail === 'string' ? detail : JSON.stringify(detail)}`);
+      if (res.status === 404) throw new CliError('Not found on the V2 platform.');
+      throw new CliError(`V2 platform error (${res.status}): ${typeof detail === 'string' ? detail : JSON.stringify(detail)}`);
+    }
+    if (res.status === 204) return undefined as T;
+    return res.json() as Promise<T>;
+  }
+
+  // Evaluations Service requests (no /api/ prefix, no org_id, no auth)
+  async evalsGet<T = unknown>(path: string, query?: Record<string, string>): Promise<T> {
+    const res = await this.send('evaluations', 'GET', this.withQuery(this.buildEvalsUrl(path), query));
     return this.handleEvalsResponse<T>(res);
   }
 
   async evalsPost<T = unknown>(path: string, body?: unknown): Promise<T> {
-    const res = await fetch(this.buildEvalsUrl(path), {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: body ? JSON.stringify(body) : undefined,
-    });
+    const res = await this.send('evaluations', 'POST', this.buildEvalsUrl(path), { body });
     return this.handleEvalsResponse<T>(res);
   }
 
   async evalsPut<T = unknown>(path: string, body?: unknown): Promise<T> {
-    const res = await fetch(this.buildEvalsUrl(path), {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: body ? JSON.stringify(body) : undefined,
-    });
+    const res = await this.send('evaluations', 'PUT', this.buildEvalsUrl(path), { body });
     return this.handleEvalsResponse<T>(res);
   }
 
   async evalsDelete<T = unknown>(path: string): Promise<T> {
-    const res = await fetch(this.buildEvalsUrl(path), {
-      method: 'DELETE',
-      headers: { 'Content-Type': 'application/json' },
-    });
+    const res = await this.send('evaluations', 'DELETE', this.buildEvalsUrl(path));
     return this.handleEvalsResponse<T>(res);
   }
 
   // Unauthenticated Copilot Server requests (for login flow)
   async copilotPostUnauth<T = unknown>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T> {
-    const res = await fetch(`${this.hosts.copilot}${path}`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        ...headers,
-      },
-      body: body ? JSON.stringify(body) : undefined,
-    });
+    const res = await this.send('copilot', 'POST', `${this.hosts.copilot}${path}`, { body, headers, auth: false });
     return this.handleCopilotResponse<T>(res);
   }
 
   private async handleCopilotResponse<T>(res: Response): Promise<T> {
     if (res.status === 401) {
-      throw new Error('Authentication failed. Run `indemn login` to re-authenticate.');
+      throw new SessionExpiredError('Authentication failed. Run `indemn login` to re-authenticate.');
     }
     if (res.status === 403) {
       throw new Error('Access denied. You may not have permission for this operation.');
     }
     if (res.status === 404) {
-      throw new Error('Resource not found.');
+      // Keep the server's reason: voice-service answers 404 with specific messages (no phone number, ...).
+      const text = await res.text().catch(() => '');
+      let reason = '';
+      try { const b = JSON.parse(text) as { message?: unknown; error?: unknown }; reason = String(b.message ?? b.error ?? ''); } catch { reason = text.trim().startsWith('<') ? '' : text.slice(0, 200); }
+      throw new Error(reason ? `Not found: ${reason}` : 'Resource not found.');
     }
     if (!res.ok) {
       const text = await res.text();
       throw new Error(`API error (${res.status}): ${text}`);
     }
-    const json = await res.json() as ApiResponse<T>;
+    const json = await res.json() as ApiResponse<T> & { message?: string };
     // Copilot Server wraps responses in { success, data }
     if (json.success !== undefined) {
       if (!json.success) {
-        throw new Error(json.msg || 'API request failed');
+        throw new Error(json.msg || json.message || 'API request failed');
       }
       return (json.data !== undefined ? json.data : json) as T;
     }