@indemn/cli 1.6.0 → 1.7.0

package/src/sdk/platform.ts

@@ -0,0 +1,115 @@
+import type { IndemnClient } from './client.js';
+import { CliError, EXIT } from '../core/runtime.js';
+
+/** Collections of the V2 platform (Darwin) the CLI can read. */
+export type PlatformResource = 'agents' | 'templates' | 'components' | 'connectors' | 'connector-bindings' | 'scenarios';
+
+/** Which of them the CLI may change. Components and connectors are a global catalog with no auth on Darwin: read-only here. */
+const WRITABLE: PlatformResource[] = ['agents', 'templates', 'connector-bindings', 'scenarios'];
+
+export interface JarvisJob {
+  job_id: string;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  bot_ids?: string[];
+  progress?: { completed?: number; total?: number; results?: Array<{ bot_id: string; bot_name?: string; success: boolean; error?: string }> };
+  [key: string]: unknown;
+}
+
+function assertWritable(resource: PlatformResource): void {
+  if (!WRITABLE.includes(resource)) {
+    throw new CliError(`${resource} is a shared catalog on the V2 platform; the CLI only reads it.`, EXIT.NEEDS_INPUT);
+  }
+}
+
+/** The V2 platform (Darwin): V2 agents, templates, scenarios, simulations and Jarvis jobs, all checked by Darwin against your org and role. */
+export class PlatformSDK {
+  constructor(private client: IndemnClient) {}
+
+  list(resource: PlatformResource, query?: Record<string, string>): Promise<unknown[]> {
+    return this.client.platformRequest('GET', `/${resource}`, { query });
+  }
+
+  get(resource: PlatformResource, id: string): Promise<Record<string, unknown>> {
+    return this.client.platformRequest('GET', `/${resource}/${encodeURIComponent(id)}`);
+  }
+
+  async create(resource: PlatformResource, body: Record<string, unknown>): Promise<unknown> {
+    assertWritable(resource);
+    return this.client.platformRequest('POST', `/${resource}`, { body });
+  }
+
+  async update(resource: PlatformResource, id: string, body: Record<string, unknown>): Promise<unknown> {
+    assertWritable(resource);
+    return this.client.platformRequest('PUT', `/${resource}/${encodeURIComponent(id)}`, { body });
+  }
+
+  async remove(resource: PlatformResource, id: string): Promise<unknown> {
+    assertWritable(resource);
+    return this.client.platformRequest('DELETE', `/${resource}/${encodeURIComponent(id)}`);
+  }
+
+  /** Checks a template's graph: components exist and edges point at real nodes. */
+  validateTemplate(id: string): Promise<{ valid: boolean; errors: string[]; warnings: string[] }> {
+    return this.client.platformRequest('POST', `/templates/${encodeURIComponent(id)}/validate`);
+  }
+
+  /** Validates input against a connector's schema and previews the request; never calls the connector. */
+  testConnector(id: string, input: Record<string, unknown>): Promise<unknown> {
+    return this.client.platformRequest('POST', `/connectors/${encodeURIComponent(id)}/test`, { body: { test_input: input } });
+  }
+
+  /** Run scenarios against a V2 agent. Darwin does not check the agent's org here, so the agent is read first (that read is org-checked). */
+  async runSimulation(agentId: string, scenarioIds: string[] = []): Promise<unknown> {
+    await this.get('agents', agentId);
+    return this.client.platformRequest('POST', '/simulations/run', { body: { agent_id: agentId, scenario_ids: scenarioIds, triggered_by: 'user' } });
+  }
+
+  simulationJobs(filter: { agentId?: string; status?: string } = {}): Promise<unknown[]> {
+    const q: Record<string, string> = {};
+    if (filter.agentId) q.agent_id = filter.agentId;
+    if (filter.status) q.status = filter.status;
+    return this.client.platformRequest('GET', '/simulations/jobs', { query: q });
+  }
+
+  simulationJob(id: string): Promise<unknown> {
+    return this.client.platformRequest('GET', `/simulations/jobs/${encodeURIComponent(id)}`);
+  }
+
+  simulationResults(filter: { agentId?: string; resultId?: string; limit?: number } = {}): Promise<unknown> {
+    if (filter.resultId) return this.client.platformRequest('GET', `/simulations/results/${encodeURIComponent(filter.resultId)}`);
+    const q: Record<string, string> = { limit: String(Math.min(filter.limit ?? 10, 100)) };
+    if (filter.agentId) q.agent_id = filter.agentId;
+    return this.client.platformRequest('GET', '/simulations/results', { query: q });
+  }
+
+  /** Which agents of the org have a baseline evaluation, and which are stale. */
+  orgEvaluations(): Promise<unknown> {
+    return this.client.platformRequest('GET', '/org-evaluations');
+  }
+
+  /** Ask Jarvis to generate baseline evaluations for up to 50 agents (Darwin checks they are in the org). */
+  createJarvisJob(botIds: string[]): Promise<JarvisJob> {
+    if (botIds.length < 1 || botIds.length > 50) throw new CliError('Give 1 to 50 agent ids.', EXIT.NEEDS_INPUT);
+    return this.client.platformRequest('POST', '/jarvis/jobs', { body: { job_type: 'baseline_generation', bot_ids: botIds } });
+  }
+
+  jarvisJobs(status?: string): Promise<JarvisJob[]> {
+    return this.client.platformRequest('GET', '/jarvis/jobs', { query: status ? { status } : undefined });
+  }
+
+  jarvisJob(id: string): Promise<JarvisJob> {
+    return this.client.platformRequest('GET', `/jarvis/jobs/${encodeURIComponent(id)}`);
+  }
+
+  /** Poll a Jarvis job until it completes (Darwin never marks jobs failed; per-agent failures are in progress.results). */
+  async waitForJarvisJob(id: string, opts: { intervalMs?: number; timeoutMs?: number; onProgress?: (j: JarvisJob) => void } = {}): Promise<JarvisJob> {
+    const started = Date.now();
+    for (;;) {
+      const job = await this.jarvisJob(id);
+      opts.onProgress?.(job);
+      if (job.status === 'completed' || job.status === 'failed') return job;
+      if (Date.now() - started > (opts.timeoutMs ?? 30 * 60_000)) throw new CliError(`Jarvis job ${id} is still ${job.status}.`);
+      await new Promise((r) => setTimeout(r, opts.intervalMs ?? 5_000));
+    }
+  }
+}

package/src/sdk/session.ts

@@ -0,0 +1,90 @@
+import type { Environment, StoredSession } from './types.js';
+
+export type { StoredSession };
+import { SessionExpiredError } from '../core/runtime.js';
+import { FIREBASE_CONFIGS } from './auth.js';
+
+const SECURE_TOKEN_URL = 'https://securetoken.googleapis.com/v1/token';
+
+export type UnauthPost = <T>(path: string, body: unknown, headers?: Record<string, string>) => Promise<T>;
+
+const RELOGIN = 'Run `indemn login` in a terminal, then retry.';
+
+/** Expiry from the JWT `exp` claim, or null when the token has none. */
+export function tokenExpiry(token: string): Date | null {
+  const payload = token.split('.')[1];
+  if (!payload) return null;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: number };
+    return typeof claims.exp === 'number' ? new Date(claims.exp * 1000) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Renew when less than `windowMs` (default one hour) of life is left. Unknown expiry never renews. */
+export function needsRenewal(session: StoredSession, now: Date = new Date(), windowMs = 60 * 60 * 1000): boolean {
+  const expiry = session.expires_at ? new Date(session.expires_at) : tokenExpiry(session.token);
+  if (!expiry || Number.isNaN(expiry.getTime())) return false;
+  return expiry.getTime() - now.getTime() < windowMs;
+}
+
+/** Trade the Firebase refresh token for a fresh Firebase ID token (Google secure-token API). */
+export async function refreshIdToken(env: Environment, refreshToken: string): Promise<{ idToken: string; refreshToken: string }> {
+  const url = `${SECURE_TOKEN_URL}?key=${encodeURIComponent(FIREBASE_CONFIGS[env].apiKey)}`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken }).toString(),
+  });
+  if (!res.ok) {
+    // Revoked, password changed or account disabled: a real login is the right answer.
+    throw new SessionExpiredError(`Session expired and could not be renewed. ${RELOGIN}`);
+  }
+  const json = await res.json() as { id_token?: string; refresh_token?: string };
+  if (!json.id_token) throw new SessionExpiredError(`Session renewal returned no token. ${RELOGIN}`);
+  return { idToken: json.id_token, refreshToken: json.refresh_token || refreshToken };
+}
+
+function stripScheme(token: string): string {
+  return token.replace(/^JWT\s+/i, '');
+}
+
+/**
+ * Exchange a Firebase ID token for a copilot session, exactly as the dashboard
+ * does. Accounts with MFA get an emailed code; without a way to ask for it the
+ * caller must log in interactively.
+ */
+export async function exchangeIdToken(
+  post: UnauthPost,
+  idToken: string,
+  askMfaCode?: () => Promise<string>,
+): Promise<{ token: string; userId: string; email?: string }> {
+  const signin = await post<{
+    requiresMfa?: boolean;
+    mfaSessionId?: string;
+    token?: string;
+    user?: { _id: string; email?: string };
+  }>('/auth/firebase/signin', { idToken });
+
+  if (signin.requiresMfa) {
+    if (!askMfaCode) {
+      throw new SessionExpiredError(`Your account needs an MFA code to renew the session. ${RELOGIN}`);
+    }
+    const code = (await askMfaCode()).trim();
+    const verified = await post<{ token: string; user: { _id: string; email?: string } }>(
+      '/auth/firebase/mfa/verify',
+      { sessionId: signin.mfaSessionId, code },
+    );
+    return { token: stripScheme(verified.token), userId: verified.user._id, email: verified.user.email };
+  }
+
+  if (!signin.token || !signin.user) throw new SessionExpiredError(`Sign-in returned no session. ${RELOGIN}`);
+  return { token: stripScheme(signin.token), userId: signin.user._id, email: signin.user.email };
+}
+
+/** Package a copilot token for storage. */
+export function toStoredSession(token: string, refreshToken?: string): StoredSession {
+  const expiry = tokenExpiry(token);
+  return { token, expires_at: expiry?.toISOString(), refresh_token: refreshToken };
+}

package/src/sdk/skills.ts

@@ -0,0 +1,188 @@
+import { readFileSync } from 'node:fs';
+import { CliError, EXIT } from '../core/runtime.js';
+
+const FILLER_WORDS = new Set(['tool', 'tools', 'skill', 'skills', 'function', 'functions']);
+/** Built-in skills a user skill must not imitate (copilot utils/constants.js INTERNAL_FUNCTIONS_LIST). */
+const INTERNAL_SKILLS = ['faqs-retriever'];
+
+/**
+ * copilot's name skeleton (utils/stringUtil.js skillNameKey), reproduced so a
+ * clash is reported before anything is sent. "FAQs Retriever",
+ * "FQ retrievers" and "F.A.Q. retrieval tool" all become "fqrtrv".
+ */
+export function skillNameKey(name: string): string {
+  const joined = String(name || '')
+    .replace(/[.']/g, '')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z]+/)
+    .filter((word) => word && !FILLER_WORDS.has(word))
+    .map((word) => (word.length > 4 ? word.replace(/(ers|er|als|al|ings|ing|e)$/, '') : word))
+    .sort()
+    .join('');
+  return joined.charAt(0) + joined.slice(1).replace(/[aeious]/g, '');
+}
+
+/** Throw the same error copilot would, before any request, when a name imitates a built-in skill. */
+export function assertSkillNameAllowed(name: string | undefined, type?: string): void {
+  if (!name || (type && INTERNAL_SKILLS.includes(type))) return;
+  const key = skillNameKey(name);
+  if (INTERNAL_SKILLS.some((reserved) => skillNameKey(reserved) === key)) {
+    throw new CliError(
+      `"${name}" is too similar to the built-in skill "${INTERNAL_SKILLS.join('", "')}", which every agent already has. Choose a different name.`,
+      EXIT.NEEDS_INPUT,
+    );
+  }
+}
+
+let stdinCache: string | undefined;
+function readStdin(): string {
+  if (stdinCache === undefined) stdinCache = readFileSync(0, 'utf8');
+  return stdinCache;
+}
+
+/**
+ * A secret passed to a flag, kept out of shell history when possible:
+ * "@path" reads a file, "env:NAME" reads an environment variable, "-" reads
+ * stdin. A plain value still works but prints a warning.
+ */
+export function resolveSecretArg(flag: string, value: string | undefined, warn: (msg: string) => void = (m) => process.stderr.write(m + '\n')): string | undefined {
+  if (value === undefined) return undefined;
+  if (value === '-') return readStdin().trim();
+  if (value.startsWith('@')) {
+    try {
+      return readFileSync(value.slice(1), 'utf8').trim();
+    } catch {
+      throw new CliError(`${flag}: cannot read ${value.slice(1)}.`);
+    }
+  }
+  if (value.startsWith('env:')) {
+    const name = value.slice(4);
+    const v = process.env[name];
+    if (v === undefined || v === '') throw new CliError(`${flag}: environment variable ${name} is not set.`);
+    return v;
+  }
+  warn(`Warning: ${flag} was typed on the command line and is now in your shell history. Next time use ${flag} @file, ${flag} env:NAME or ${flag} - (stdin).`);
+  return value;
+}
+
+/** Find the list of proposed skills in a generate-from-doc answer. */
+/**
+ * A skill's configurationSchema from plain fields, laid over `base` (the saved one on update,
+ * since copilot replaces it whole). copilot needs an authorization type on rest_api skills;
+ * unauthenticated APIs get no-auth.
+ */
+/**
+ * A call-transfer destination the way the dashboard saves it: phoneNumber (+ intlTelObj) or sipUri
+ * (+ sipHeaders). Older skills say handoffNumber, and some exports carry the runtime's
+ * {"action":"transfer","payload":{"to":...}} as payload. copilot reads sipUri, then phoneNumber, then
+ * handoffNumber, so a new destination in `patch` must replace the saved one of either kind.
+ */
+export function transferDestination(base: Record<string, unknown>, patch: Record<string, unknown> = {}): Record<string, unknown> {
+  const str = (v: unknown) => (typeof v === 'string' && v ? v : undefined);
+  const legacyTo = (c: Record<string, unknown>) => {
+    if (typeof c.payload !== 'string') return undefined;
+    try {
+      const p = JSON.parse(c.payload) as { action?: string; payload?: { to?: unknown } };
+      return p?.action === 'transfer' ? str(p.payload?.to) : undefined;
+    } catch { return undefined; }
+  };
+  const pick = (c: Record<string, unknown>) => {
+    const to = legacyTo(c);
+    const sip = str(c.sipUri) ?? (to?.startsWith('sip:') ? to : undefined);
+    const phone = str(c.phoneNumber) ?? str(c.handoffNumber) ?? (to && !to.startsWith('sip:') ? to : undefined);
+    return sip ? { sip, headers: c.sipHeaders } : phone ? { phone } : undefined;
+  };
+  const dest = pick(patch) ?? pick(base);
+  const out: Record<string, unknown> = { ...base, ...patch };
+  if (legacyTo(out) !== undefined) { delete out.payload; delete out.payloadOps; }
+  for (const k of ['sipUri', 'sipHeaders', 'phoneNumber', 'intlTelObj', 'handoffNumber']) delete out[k];
+  if (dest && 'sip' in dest) {
+    out.sipUri = dest.sip;
+    if (dest.headers && typeof dest.headers === 'object' && Object.keys(dest.headers).length) out.sipHeaders = dest.headers;
+  } else if (dest?.phone) {
+    out.phoneNumber = dest.phone;
+    out.intlTelObj = { number: dest.phone, e164Number: dest.phone };
+  }
+  return out;
+}
+
+/**
+ * The dashboard's REST form quotes a bare {{parameter}} before saving (rest-api-form.tsx quoteBareMentions):
+ * `"guests": {{guests}}` becomes `"guests": "{{guests}}"`, so the body is the valid JSON copilot requires.
+ */
+export function quoteBareMentions(payload: string): string {
+  let out = '';
+  let inString = false;
+  for (let i = 0; i < payload.length; i++) {
+    const ch = payload[i];
+    if (inString) {
+      out += ch;
+      if (ch === '\\') out += payload[++i] ?? '';
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+    } else if (ch === '{' && payload[i + 1] === '{') {
+      const close = payload.indexOf('}}', i + 2);
+      if (close !== -1) {
+        out += JSON.stringify(payload.slice(i, close + 2));
+        i = close + 1;
+        continue;
+      }
+    }
+    out += ch;
+  }
+  return out;
+}
+
+/** A REST body as copilot saves it: JSON text with bare placeholders quoted; refused when it is still not JSON. */
+export function requestBody(payload: unknown): string {
+  if (typeof payload !== 'string') return JSON.stringify(payload);
+  if (!payload.trim()) return payload;
+  const body = quoteBareMentions(payload);
+  try {
+    JSON.parse(body);
+  } catch (err) {
+    throw new CliError(`The request body is not valid JSON (${err instanceof Error ? err.message : String(err)}). Nothing was saved. Send it as JSON text, e.g. {"event_date": "{{event_date}}"}.`, EXIT.ERROR);
+  }
+  return body;
+}
+
+export function skillConfiguration(
+  type: string,
+  f: {
+    url?: string; method?: string; payload?: unknown; response_field?: string;
+    output_instructions?: string; craft_response?: boolean; configuration?: Record<string, unknown>;
+    transfer_to?: string;
+  },
+  base: Record<string, unknown> = {},
+): Record<string, unknown> | undefined {
+  const patch: Record<string, unknown> = { ...(f.configuration ?? {}) };
+  if (f.url !== undefined) patch.endpoint = f.url;
+  if (f.method !== undefined) patch.method = f.method.toUpperCase();
+  if (f.payload !== undefined) patch.payload = f.payload;
+  if (patch.payload !== undefined) patch.payload = requestBody(patch.payload);
+  if (f.response_field !== undefined) patch.responseField = f.response_field;
+  if (f.output_instructions !== undefined) patch.outputInstructions = f.output_instructions;
+  if (f.craft_response !== undefined) patch.craftResponse = f.craft_response;
+  if (f.transfer_to !== undefined) patch[f.transfer_to.startsWith('sip:') ? 'sipUri' : 'phoneNumber'] = f.transfer_to;
+  if (!Object.keys(patch).length) return undefined;
+  if (type === 'transfer_call') return transferDestination(base, patch);
+  const merged = { ...base, ...patch };
+  if (type === 'rest_api' && merged.authorization === undefined) merged.authorization = { type: 'no-auth' };
+  return merged;
+}
+
+export function proposedSkills(res: unknown): Array<Record<string, unknown>> | null {
+  if (Array.isArray(res)) return res as Array<Record<string, unknown>>;
+  if (res && typeof res === 'object') {
+    const r = res as Record<string, unknown>;
+    for (const key of ['functions', 'skills', 'tools', 'data', 'result']) {
+      const found = proposedSkills(r[key]);
+      if (found) return found;
+    }
+  }
+  return null;
+}

package/src/sdk/test-chat.ts

@@ -0,0 +1,151 @@
+import { IndemnClient } from './client.js';
+import { AgentsSDK } from './agents.js';
+import { ConfigSDK } from './config.js';
+import { ChatSession } from './chat.js';
+import { ConversationsSDK, conversationUrl, idOf } from './conversations.js';
+import type { Agent } from './types.js';
+
+/** Who is testing: the login email, else the email inside a host-supplied session token. */
+export function testerIdentity(client: IndemnClient): string | null {
+  const cred = client.getCredential();
+  if (cred?.source === 'config') {
+    const email = IndemnClient.loadConfig()?.email;
+    if (email) return email;
+  }
+  if (cred?.kind === 'token') {
+    try {
+      const claims = JSON.parse(Buffer.from(cred.token.split('.')[1] ?? '', 'base64url').toString('utf8')) as { email?: string };
+      if (claims.email) return claims.email;
+    } catch {
+      // not a readable JWT
+    }
+  }
+  return null;
+}
+
+/**
+ * The dashboard's "Talk to agent" preview record for this person and agent.
+ * Reused when it exists (never overwritten, it may hold context they saved in
+ * the dashboard); created empty otherwise. Optional: failure only means the
+ * dashboard cannot show the tester card.
+ */
+export async function ensurePreview(client: IndemnClient, agentId: string): Promise<string | null> {
+  const path = `/organization/:org_id/ai-studio/bots/${agentId}/preview/agent`;
+  try {
+    const existing = await client.copilotGet<{ _id?: string } | null>(path);
+    if (existing && existing._id) return String(existing._id);
+    const created = await client.copilotPost<{ _id?: string }>(path, {});
+    return created?._id ? String(created._id) : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface OpenedTestChat {
+  session: ChatSession;
+  sessionId: string;
+  agent: Agent;
+  orgId: string;
+  projectId: string;
+  url: string;
+  tester: string | null;
+  preview: string | null;
+  resumed: boolean;
+  /** Every complete agent message so far, greeting included. */
+  transcript: string[];
+  /** True while the agent is streaming a message. */
+  isReceiving: () => boolean;
+}
+
+/**
+ * Open a chat that is guaranteed to be a test conversation in the chosen org:
+ * the agent is fetched through copilot (which refuses an agent from another
+ * org), the session is opened with isTestMode, and the stored conversation is
+ * read back before the caller may send anything.
+ */
+export async function openTestChat(
+  client: IndemnClient,
+  agentId: string,
+  opts: { sessionId?: string; verifyTimeoutMs?: number; onSession?: (session: ChatSession) => void } = {},
+): Promise<OpenedTestChat> {
+  const orgId = await client.currentOrgId();
+  const agent = await new AgentsSDK(client).getAgent(agentId);
+  if (!agent) throw new Error(`Agent ${agentId} not found in this org.`);
+  const projectId = idOf(agent.id_project);
+  const tester = testerIdentity(client);
+  const preview = opts.sessionId ? null : await ensurePreview(client, agent._id);
+  // The middleware greets with customData.first_message, else a stock line; the dashboard preview sends the saved one.
+  const firstMessage = opts.sessionId ? undefined : (await new ConfigSDK(client).getConfig(agent._id).catch(() => undefined))?.first_message;
+  const customData = firstMessage?.text ? { first_message: firstMessage } : undefined;
+
+  const session = new ChatSession(agent._id, client.getHosts().middleware, opts.sessionId, { tester, preview, customData });
+  const transcript: string[] = [];
+  let receiving = false;
+  session.on('stream', (data: { isFirstChunk?: boolean; streamFinished?: boolean }) => {
+    if (data.isFirstChunk) receiving = true;
+    if (data.streamFinished) receiving = false;
+  });
+  session.on('message', (text: string) => transcript.push(text));
+  opts.onSession?.(session);
+  const sessionId = await session.connect();
+  try {
+    if (!projectId) throw new Error(`Agent ${agent._id} has no project; cannot confirm the conversation is a test. Nothing was sent.`);
+    await new ConversationsSDK(client).verifyTestConversation(projectId, sessionId, orgId, { timeoutMs: opts.verifyTimeoutMs });
+  } catch (err) {
+    await session.disconnect();
+    throw err;
+  }
+  return {
+    session,
+    sessionId,
+    agent,
+    orgId,
+    projectId,
+    url: conversationUrl(client, projectId, sessionId),
+    tester,
+    preview,
+    resumed: Boolean(opts.sessionId),
+    transcript,
+    isReceiving: () => receiving,
+  };
+}
+
+function until(check: () => boolean, timeoutMs: number, stepMs = 100): Promise<boolean> {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const tick = () => {
+      if (check()) return resolve(true);
+      if (Date.now() - started >= timeoutMs) return resolve(false);
+      setTimeout(tick, stepMs);
+    };
+    tick();
+  });
+}
+
+/**
+ * Send one message and collect the reply. A new conversation first waits for
+ * the greeting. The reply is complete when the agent has been quiet for
+ * `settleMs` after its last message.
+ */
+export async function exchange(
+  chat: OpenedTestChat,
+  message: string,
+  opts: { greetingWaitMs?: number; timeoutMs?: number; settleMs?: number } = {},
+): Promise<{ greeting: string; response: string }> {
+  if (!chat.resumed) {
+    await until(() => chat.transcript.length > 0 && !chat.isReceiving(), opts.greetingWaitMs ?? 8_000);
+  }
+  const greeting = chat.transcript.join('\n');
+  const start = chat.transcript.length;
+  chat.session.send(message);
+
+  const gotReply = await until(() => chat.transcript.length > start && !chat.isReceiving(), opts.timeoutMs ?? 60_000);
+  if (!gotReply) throw new Error(`Agent did not respond within ${Math.round((opts.timeoutMs ?? 60_000) / 1000)} seconds.`);
+  let seen = chat.transcript.length;
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, opts.settleMs ?? 1_500));
+    if (chat.transcript.length === seen && !chat.isReceiving()) break;
+    seen = chat.transcript.length;
+  }
+  return { greeting, response: chat.transcript.slice(start).join('\n') };
+}

package/src/sdk/tickets.ts

@@ -0,0 +1,120 @@
+import type { IndemnClient } from './client.js';
+import { CliError, EXIT } from '../core/runtime.js';
+
+export type TicketStatus = 'not_started' | 'in_progress' | 'completed';
+export type TicketPriority = 'urgent' | 'high' | 'normal' | 'low';
+
+export interface Ticket {
+  _id: string;
+  title?: string;
+  status?: TicketStatus;
+  priority?: TicketPriority;
+  ticket_ref?: string;
+  assignee?: unknown;
+  [key: string]: unknown;
+}
+
+export interface TicketInput {
+  title: string;
+  description?: string;
+  notes?: string;
+  category?: string;
+  priority?: TicketPriority;
+  due_date?: string;
+  tags?: string[];
+  assignee?: { type: string; target?: string; user_id?: string } | null;
+  conversations?: Array<{ request_id: string; summary?: string }>;
+}
+
+export type CreateResult =
+  | { saved: true; ticket: Ticket }
+  | { saved: false; similar: Ticket[]; message: string };
+
+/** Tickets and the rules that create them. Both need tickets turned on for the org. */
+export class TicketsSDK {
+  constructor(private client: IndemnClient) {}
+
+  list(filter: { status?: TicketStatus[]; source?: string; assignee?: string; search?: string; limit?: number; skip?: number } = {}): Promise<Ticket[]> {
+    const q: Record<string, string> = { limit: String(Math.min(filter.limit ?? 50, 500)), skip: String(filter.skip ?? 0) };
+    if (filter.status?.length) q.status = filter.status.join(',');
+    if (filter.source) q.source = filter.source;
+    if (filter.assignee) q.assignee = filter.assignee;
+    if (filter.search) q.q = filter.search;
+    return this.client.copilotGet('/organization/:org_id/tickets', q);
+  }
+
+  get(id: string): Promise<Ticket> {
+    return this.client.copilotGet(`/organization/:org_id/tickets/${id}`);
+  }
+
+  byConversation(requestId: string): Promise<Ticket[]> {
+    return this.client.copilotGet(`/organization/:org_id/tickets/by-request/${encodeURIComponent(requestId)}`);
+  }
+
+  /**
+   * Create a ticket. Without `force`, copilot first looks for similar open
+   * tickets (an LLM call) and stores nothing when it finds some.
+   */
+  async create(input: TicketInput, opts: { force?: boolean } = {}): Promise<CreateResult> {
+    if (!input.title?.trim()) throw new CliError('A ticket needs a title.', EXIT.NEEDS_INPUT);
+    const res = await this.client.copilotPost<Ticket | { saved?: boolean; similar?: Ticket[] }>('/organization/:org_id/tickets', { ...input, ...(opts.force ? { force: true } : {}) });
+    const maybe = res as { saved?: boolean; similar?: Ticket[] };
+    if (maybe.saved === false && Array.isArray(maybe.similar)) {
+      return { saved: false, similar: maybe.similar, message: 'Similar tickets exist; nothing was created. Link to one of them, or create anyway with force.' };
+    }
+    return { saved: true, ticket: res as Ticket };
+  }
+
+  update(id: string, changes: Partial<Pick<TicketInput, 'title' | 'description' | 'notes' | 'category' | 'priority' | 'due_date' | 'tags'>> & { status?: TicketStatus }): Promise<Ticket> {
+    return this.client.copilotPut(`/organization/:org_id/tickets/${id}`, changes);
+  }
+
+  /** Assign to a member (`{ type: "user", target: userId }`), another assignee type, or null to unassign. */
+  assign(id: string, assignee: { type: string; target: string } | null): Promise<Ticket> {
+    return this.client.copilotPost(`/organization/:org_id/tickets/${id}/assign`, { assignee });
+  }
+
+  /** Close a ticket, optionally adding a note. */
+  resolve(id: string, note?: string): Promise<Ticket> {
+    return this.client.copilotPost(`/organization/:org_id/tickets/${id}/resolve`, note ? { note } : {});
+  }
+
+  addConversation(id: string, requestId: string, summary?: string): Promise<Ticket> {
+    return this.client.copilotPost(`/organization/:org_id/tickets/${id}/conversations`, { conversation: { request_id: requestId }, ...(summary ? { summary } : {}) });
+  }
+
+  link(id: string, relatedId: string): Promise<Ticket> {
+    return this.client.copilotPost(`/organization/:org_id/tickets/${id}/link`, { related_ticket_id: relatedId });
+  }
+
+  archive(id: string): Promise<unknown> {
+    return this.client.copilotDelete(`/organization/:org_id/tickets/${id}`);
+  }
+
+  listRules(opts: { agentId?: string; includeTrashed?: boolean } = {}): Promise<unknown[]> {
+    const q: Record<string, string> = {};
+    if (opts.agentId) q.agent = opts.agentId;
+    if (opts.includeTrashed) q.includeTrashed = 'true';
+    return this.client.copilotGet('/organization/:org_id/ticket-creation-rules', q);
+  }
+
+  /**
+   * Create or change a rule. A new rule without `force` is first checked by an
+   * LLM for overlaps; when it has caveats nothing is stored.
+   */
+  async saveRule(input: { ruleId?: string; name?: string; prompt?: string; assignment?: unknown; scope?: unknown; enabled?: boolean }, opts: { force?: boolean } = {}): Promise<{ saved: boolean; rule?: unknown; caveats?: unknown[]; suggested_name?: string }> {
+    const body: Record<string, unknown> = {};
+    for (const k of ['name', 'prompt', 'assignment', 'scope', 'enabled'] as const) if (input[k] !== undefined) body[k] = input[k];
+    if (input.ruleId) {
+      return { saved: true, rule: await this.client.copilotPut(`/organization/:org_id/ticket-creation-rules/${input.ruleId}`, body) };
+    }
+    if (!input.prompt) throw new CliError('A new rule needs a prompt: when should a ticket be created?', EXIT.NEEDS_INPUT);
+    const res = await this.client.copilotPost<{ saved?: boolean; caveats?: unknown[]; suggested_name?: string }>('/organization/:org_id/ticket-creation-rules', { ...body, ...(opts.force ? { force: true } : {}) });
+    if (res && res.saved === false) return { saved: false, caveats: res.caveats, suggested_name: res.suggested_name };
+    return { saved: true, rule: res };
+  }
+
+  deleteRule(ruleId: string): Promise<unknown> {
+    return this.client.copilotDelete(`/organization/:org_id/ticket-creation-rules/${ruleId}`);
+  }
+}