@indemn/cli 1.6.0 → 1.7.0

package/src/sdk/agent-bundle.ts

@@ -0,0 +1,245 @@
+import type { IndemnClient } from './client.js';
+import { AgentsSDK } from './agents.js';
+import { ConfigSDK } from './config.js';
+import { FunctionsSDK } from './functions.js';
+import { transferDestination } from './skills.js';
+import { modelForAgent } from './config-change.js';
+import { KBSDK } from './kb.js';
+import { CliError, EXIT } from '../core/runtime.js';
+import type { Agent, BotFunction, FunctionParameter } from './types.js';
+
+export const BUNDLE_FORMAT = 'indemn-agent/1';
+const REDACTED = '<redacted>';
+const SECRET_KEY = /(api[-_]?key|token|secret|password|passwd|authorization|auth|bearer|credential|private[-_]?key|client[-_]?secret)/i;
+/** Web addresses that are secrets themselves: webhooks (anyone holding one can post), and URLs with a key in the query. */
+const SECRET_URL = /^https?:\/\/\S*(hooks\.slack\.com\/|hooks\.zapier\.com\/|discord(app)?\.com\/api\/webhooks\/|\/webhooks?\/|[?&](api[-_]?key|key|token|secret|sig|signature|access_token|password)=)/i;
+
+/** Replace every value under a secret-looking key, and every secret web address, at any depth. */
+export function redactSecrets<T>(value: T): { value: T; redacted: string[] } {
+  const redacted: string[] = [];
+  const walk = (v: unknown, path: string): unknown => {
+    if (Array.isArray(v)) return v.map((x, i) => walk(x, `${path}[${i}]`));
+    if (v && typeof v === 'object') {
+      const out: Record<string, unknown> = {};
+      for (const [k, x] of Object.entries(v as Record<string, unknown>)) {
+        const p = path ? `${path}.${k}` : k;
+        if ((SECRET_KEY.test(k) && x !== null && typeof x !== 'object' && x !== '') || (typeof x === 'string' && SECRET_URL.test(x))) {
+          out[k] = REDACTED;
+          redacted.push(p);
+        } else {
+          out[k] = walk(x, p);
+        }
+      }
+      return out;
+    }
+    return v;
+  };
+  return { value: walk(value, '') as T, redacted };
+}
+
+export interface AgentBundle {
+  format: typeof BUNDLE_FORMAT;
+  exported_at: string;
+  source: { agent_id: string; org_id: string; environment: string };
+  agent: { name: string; description?: string; channels: string[] };
+  configuration: { system_prompt?: string; first_message?: unknown; llm_config?: { provider?: string; model?: string; parameters?: unknown } };
+  skills: Array<{ type: string; name?: string; description?: string; configurationSchema?: Record<string, unknown>; parameters: Array<Omit<FunctionParameter, '_id'>> }>;
+  knowledge_base_ids: string[];
+  redacted: string[];
+}
+
+function channelNames(channels: unknown[] | undefined): string[] {
+  return (channels ?? []).map((c) => (typeof c === 'string' ? c : String((c as Record<string, unknown>).name ?? (c as Record<string, unknown>).type ?? c)));
+}
+
+/**
+ * Everything needed to rebuild an agent elsewhere: name, channels, prompt,
+ * greeting, model, skills with parameters, and the ids of linked knowledge
+ * bases. Secrets inside skill settings are redacted unless asked otherwise.
+ */
+export async function exportAgent(client: IndemnClient, agentId: string, opts: { includeSecrets?: boolean } = {}): Promise<AgentBundle> {
+  const agents = new AgentsSDK(client);
+  const functions = new FunctionsSDK(client);
+  const agent = await agents.getAgent(agentId);
+  const config = await new ConfigSDK(client).getConfig(agentId);
+  const skills: BotFunction[] = await functions.listFunctions(agentId);
+  const withParams = [];
+  for (const f of skills) {
+    const params = await functions.listParameters(agentId, f._id).catch(() => [] as FunctionParameter[]);
+    withParams.push({
+      type: f.type,
+      name: f.name,
+      description: f.description,
+      configurationSchema: (f as unknown as { configurationSchema?: Record<string, unknown> }).configurationSchema,
+      parameters: params.map(({ _id, ...rest }) => rest),
+    });
+  }
+  const mappings = await new KBSDK(client).listMappings(agentId).catch(() => [] as Array<{ id: string }>);
+  const llm = (config as { llm_config?: { provider?: string; model?: string; parameters?: unknown } }).llm_config;
+  const bundle: AgentBundle = {
+    format: BUNDLE_FORMAT,
+    exported_at: new Date().toISOString(),
+    source: { agent_id: agentId, org_id: await client.currentOrgId(), environment: client.getEnvironment() },
+    agent: { name: agent.name, description: agent.description, channels: channelNames(agent.channels as unknown[] | undefined) },
+    configuration: {
+      system_prompt: config.ai_config?.system_prompt,
+      first_message: config.first_message,
+      llm_config: llm ? { provider: llm.provider, model: llm.model, parameters: llm.parameters } : undefined,
+    },
+    skills: withParams,
+    knowledge_base_ids: mappings.map((m) => String(m.id ?? '')).filter(Boolean),
+    redacted: [],
+  };
+  if (opts.includeSecrets) return bundle;
+  const { value, redacted } = redactSecrets(bundle.skills);
+  return { ...bundle, skills: value, redacted };
+}
+
+export interface ImportReport {
+  agent: Agent;
+  skills_created: number;
+  /** Built-in skills (FAQ retriever, handoff) the new agent already had; their settings were copied over. */
+  built_in_skills_reused: string[];
+  skills_failed: Array<{ name?: string; error: string }>;
+  knowledge_bases_linked: string[];
+  knowledge_bases_skipped: string[];
+  needs_secrets: string[];
+}
+
+/**
+ * Create a new agent in the current org from a bundle. Skills that carry
+ * redacted secrets are still created; the report lists what must be filled in.
+ */
+export async function importAgent(
+  client: IndemnClient,
+  bundle: AgentBundle,
+  opts: { name?: string; allowDuplicate?: boolean; linkKnowledgeBases?: boolean } = {},
+): Promise<ImportReport> {
+  if (bundle.format !== BUNDLE_FORMAT) throw new CliError(`Not an agent bundle (format ${String(bundle.format)}; expected ${BUNDLE_FORMAT}).`);
+  const agents = new AgentsSDK(client);
+  const functions = new FunctionsSDK(client);
+  const name = opts.name ?? bundle.agent.name;
+  if (!opts.allowDuplicate && (await agents.findByName(name)).length) {
+    throw new CliError(`An agent named "${name}" already exists in this org. Pass a new name, or allow a duplicate explicitly.`, EXIT.NEEDS_INPUT);
+  }
+  const agent = await agents.createAgent({ name, channels: bundle.agent.channels.length ? bundle.agent.channels : ['WEB'] });
+  if (bundle.agent.description) await agents.updateAgent(agent._id, { description: bundle.agent.description });
+
+  const config: Record<string, unknown> = {};
+  if (bundle.configuration.system_prompt !== undefined) config.system_prompt = bundle.configuration.system_prompt;
+  if (bundle.configuration.first_message) config.first_message = JSON.stringify(bundle.configuration.first_message);
+  if (bundle.configuration.llm_config?.model) config.llm_config = bundle.configuration.llm_config;
+  if (Object.keys(config).length) await new ConfigSDK(client).setConfig(agent._id, config);
+
+  const report: ImportReport = {
+    agent, skills_created: 0, built_in_skills_reused: [], skills_failed: [], knowledge_bases_linked: [], knowledge_bases_skipped: [], needs_secrets: bundle.redacted,
+  };
+  // A new agent comes with the built-in skills; creating them again duplicates them (or fails).
+  const builtIns = (await functions.listFunctions(agent._id)).filter((f) => (f as { systemDeveloped?: boolean }).systemDeveloped);
+  for (const skill of bundle.skills) {
+    try {
+      // Call transfers are saved the way the dashboard saves them (older exports carry the destination elsewhere).
+      const config = skill.type === 'transfer_call' && skill.configurationSchema ? transferDestination({}, skill.configurationSchema) : skill.configurationSchema;
+      const builtIn = builtIns.find((f) => f.type === skill.type);
+      if (builtIn) {
+        if (config) {
+          await functions.updateFunction(agent._id, builtIn._id, {
+            type: skill.type, description: skill.description ?? builtIn.description ?? '', configurationSchema: config,
+          });
+        }
+        builtIns.splice(builtIns.indexOf(builtIn), 1);
+        report.built_in_skills_reused.push(skill.name ?? skill.type);
+        continue;
+      }
+      const created = await functions.createFunction(agent._id, { type: skill.type, name: skill.name, description: skill.description });
+      if (config) {
+        await functions.updateFunction(agent._id, created._id, {
+          type: skill.type, description: skill.description ?? '', configurationSchema: config,
+        });
+      }
+      for (const p of skill.parameters) {
+        const allowedValues = p.isEnumsEnabled ? (p.enums ?? []).map((e) => e.payload ?? e.title ?? '').filter(Boolean) : undefined;
+        await functions.addParameter(agent._id, created._id, { name: p.name, type: p.type, description: p.description, required: p.is_required, allowedValues });
+      }
+      report.skills_created++;
+    } catch (err) {
+      report.skills_failed.push({ name: skill.name, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  if (opts.linkKnowledgeBases && bundle.knowledge_base_ids.length) {
+    const kb = new KBSDK(client);
+    for (const id of bundle.knowledge_base_ids) {
+      try {
+        await kb.linkKB(agent._id, [id]);
+        report.knowledge_bases_linked.push(id);
+      } catch {
+        report.knowledge_bases_skipped.push(id);
+      }
+    }
+  } else {
+    report.knowledge_bases_skipped.push(...bundle.knowledge_base_ids);
+  }
+  return report;
+}
+
+export interface AgentSkeleton {
+  name: string;
+  channels?: string[];
+  /** What the agent is for; stored as the agent description. */
+  description?: string;
+  system_prompt?: string;
+  model?: { provider: string; model: string };
+}
+
+/** Fields a new agent should have before it is created; the caller asks for the missing ones. */
+export function missingSkeletonFields(s: Partial<AgentSkeleton>): Array<keyof AgentSkeleton> {
+  const missing: Array<keyof AgentSkeleton> = [];
+  if (!s.name?.trim()) missing.push('name');
+  if (!s.description?.trim()) missing.push('description');
+  if (!s.system_prompt?.trim()) missing.push('system_prompt');
+  return missing;
+}
+
+/**
+ * Create an agent with its basics in one go: refuse a duplicate name, create
+ * it, then set the purpose, prompt and model. Returns what was set.
+ */
+export async function createAgentFromSkeleton(
+  client: IndemnClient,
+  s: AgentSkeleton,
+  opts: { allowDuplicate?: boolean } = {},
+): Promise<{ agent: Agent; set: string[] }> {
+  const agents = new AgentsSDK(client);
+  const name = s.name.trim();
+  if (!name) throw new CliError('An agent needs a name.', EXIT.NEEDS_INPUT);
+  if (!opts.allowDuplicate) {
+    const same = await agents.findByName(name);
+    if (same.length) {
+      throw new CliError(
+        `An agent named "${name}" already exists in this org (${same.map((a) => a._id).join(', ')}). Choose another name or allow a duplicate explicitly.`,
+        EXIT.NEEDS_INPUT,
+      );
+    }
+  }
+  const agent = await agents.createAgent({ name, channels: s.channels?.length ? s.channels : ['WEB'] });
+  const set = ['name', 'channels'];
+  if (s.description?.trim()) {
+    await agents.updateAgent(agent._id, { description: s.description.trim() });
+    set.push('description');
+  }
+  const config: Record<string, unknown> = {};
+  if (s.system_prompt?.trim()) config.system_prompt = s.system_prompt;
+  if (s.model) config.llm_config = await modelForAgent(client, s.model, s.channels ?? ['WEB']);
+  if (Object.keys(config).length) {
+    await new ConfigSDK(client).setConfig(agent._id, config);
+    set.push(...Object.keys(config).map((k) => (k === 'llm_config' ? 'model' : k)));
+  }
+  return { agent, set };
+}
+
+/** "openai/gpt-4.1" -> { provider: "openai", model: "gpt-4.1" }. */
+export function parseModel(value: string): { provider: string; model: string } {
+  const i = value.indexOf('/');
+  if (i <= 0 || i === value.length - 1) throw new CliError(`Model must look like provider/model, for example openai/gpt-4.1 (got "${value}").`, EXIT.NEEDS_INPUT);
+  return { provider: value.slice(0, i), model: value.slice(i + 1) };
+}

package/src/sdk/agents.ts

@@ -1,4 +1,5 @@
 import type { IndemnClient } from './client.js';
+import { CliError } from '../core/runtime.js';
 import type { Agent, CreateAgentInput, UpdateAgentInput } from './types.js';
 
 export class AgentsSDK {
@@ -14,14 +15,17 @@ export class AgentsSDK {
     const result = await this.client.copilotGet<Agent | Agent[]>(
       `/organization/:org_id/ai-studio/v2/bots/${id}`,
     );
-    // v2 endpoint returns array even for single bot
-    return Array.isArray(result) ? result[0] : result;
+    // v2 endpoint returns array even for single bot; an empty one means deleted or not in this org
+    const agent = Array.isArray(result) ? result[0] : result;
+    if (!agent) throw new CliError(`Agent ${id} was not found in this organization (deleted, or in another org).`);
+    return agent;
   }
 
   async createAgent(input: CreateAgentInput): Promise<Agent> {
     return this.client.copilotPost<Agent>(
       '/organization/:org_id/ai-studio/bots',
-      { name: input.name, channels: input.channels || ['WEB'] },
+      // copilot matches channel names exactly (WEB, VOICE, EMAIL) and fails on "voice".
+      { name: input.name, channels: (input.channels || ['WEB']).map((c) => c.toUpperCase()) },
     );
   }
 
@@ -38,10 +42,75 @@ export class AgentsSDK {
     );
   }
 
-  async cloneAgent(id: string): Promise<Agent> {
+  /** Agents in this org with the same name (case and surrounding spaces ignored). */
+  async findByName(name: string): Promise<Agent[]> {
+    const wanted = name.trim().toLowerCase();
+    return (await this.listAgents()).filter((a) => !a.trashed && (a.name ?? '').trim().toLowerCase() === wanted);
+  }
+
+  /**
+   * Copy an agent within the current org. copilot's clone route accepts a
+   * source from any org, so the source is first fetched through the org
+   * (copilot refuses an agent of another org) before cloning.
+   */
+  async cloneAgent(id: string, opts: { name?: string; channels?: string[] } = {}): Promise<Agent> {
+    const source = await this.getAgent(id);
+    if (!source) throw new Error(`Agent ${id} is not in this org.`);
     return this.client.copilotPost<Agent>(
       '/organization/:org_id/ai-studio/v2/bots/clone',
-      { source_id_bot: id },
+      { source_id_bot: id, ...(opts.name ? { agent_name: opts.name } : {}), ...(opts.channels ? { channels: opts.channels.map((c) => c.toUpperCase()) } : {}) },
     );
   }
 }
+
+export type Lifecycle = 'prototype' | 'beta' | 'published';
+
+/** An agent as the V2 platform (Darwin) describes it: lifecycle, owner, tools and knowledge. */
+export interface AgentDetail {
+  id: string;
+  name: string;
+  lifecycle?: Lifecycle;
+  owner?: { id: string; firstname?: string; lastname?: string; email?: string } | null;
+  owner_id?: string;
+  lifecycle_history?: Array<{ from_stage?: string; to_stage?: string; changed_by?: string; changed_at?: string }>;
+  [key: string]: unknown;
+}
+
+function isoDay(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Agent operations that live on the V2 platform or in analytics. Lifecycle
+ * and ownership go through Darwin because it checks the caller is the owner
+ * or an org admin; copilot only checks membership.
+ */
+export class AgentInsightsSDK {
+  constructor(private client: IndemnClient) {}
+
+  detail(id: string): Promise<AgentDetail> {
+    return this.client.platformRequest<AgentDetail>('GET', `/v1-agents/${id}`);
+  }
+
+  setLifecycle(id: string, lifecycle: Lifecycle): Promise<AgentDetail> {
+    return this.client.platformRequest<AgentDetail>('PATCH', `/v1-agents/${id}/lifecycle`, { body: { lifecycle } });
+  }
+
+  transferOwner(id: string, ownerId: string): Promise<AgentDetail> {
+    return this.client.platformRequest<AgentDetail>('PATCH', `/v1-agents/${id}/owner`, { body: { owner_id: ownerId } });
+  }
+
+  /** A compact description an AI can read before acting: `text` is one paragraph, otherwise skills and knowledge are listed. */
+  summary(id: string, opts: { text?: boolean } = {}): Promise<unknown> {
+    return this.client.platformRequest('GET', `/v1-agents/${id}/summary${opts.text ? '/text' : ''}`);
+  }
+
+  /** Conversation metrics for one agent (org analytics filtered by agent). Default: the last 30 days. */
+  stats(id: string, opts: { from?: string; to?: string; channel?: 'web' | 'voice' | 'all' } = {}): Promise<unknown> {
+    const to = opts.to ?? isoDay(new Date());
+    const from = opts.from ?? isoDay(new Date(Date.now() - 30 * 86_400_000));
+    return this.client.copilotGet('/organization/:org_id/analytics/metrics', {
+      agent_id: id, date_from: from, date_to: to, channel: opts.channel ?? 'all',
+    });
+  }
+}

package/src/sdk/analytics.ts

@@ -0,0 +1,220 @@
+import type { IndemnClient } from './client.js';
+import { CliError, EXIT } from '../core/runtime.js';
+
+export interface AnalyticsRange {
+  from?: string;
+  to?: string;
+  channel?: 'web' | 'voice' | 'all';
+  agentId?: string;
+}
+
+function day(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/** YYYY-MM-DD range, default the last 30 days; copilot refuses spans over 365 days. */
+export function rangeQuery(r: AnalyticsRange, opts: { withChannel?: boolean; withAgent?: boolean } = { withChannel: true, withAgent: true }): Record<string, string> {
+  const to = r.to ?? day(new Date());
+  const from = r.from ?? day(new Date(Date.parse(to) - 30 * 86_400_000));
+  const span = (Date.parse(to) - Date.parse(from)) / 86_400_000;
+  if (Number.isNaN(span) || span < 0) throw new CliError('Dates must be YYYY-MM-DD with from before to.', EXIT.NEEDS_INPUT);
+  if (span > 365) throw new CliError('Analytics cover at most 365 days.', EXIT.NEEDS_INPUT);
+  const q: Record<string, string> = { date_from: from, date_to: to };
+  if (opts.withChannel !== false) q.channel = r.channel ?? 'all';
+  if (opts.withAgent !== false && r.agentId) q.agent_id = r.agentId;
+  return q;
+}
+
+export type MetricKind = 'metrics' | 'model-performance' | 'model-performance/bots' | 'agent-volume' | 'handoff-precursors' | 'critical-feedback';
+
+/** The numbers the dashboard's analytics pages show. Test conversations are excluded by copilot. */
+export class AnalyticsSDK {
+  constructor(private client: IndemnClient) {}
+
+  get(kind: MetricKind, range: AnalyticsRange = {}): Promise<unknown> {
+    const opts = {
+      withChannel: !['model-performance/bots', 'agent-volume'].includes(kind),
+      withAgent: !['model-performance/bots', 'agent-volume'].includes(kind),
+    };
+    return this.client.copilotGet(`/organization/:org_id/analytics/${kind}`, rangeQuery(range, opts));
+  }
+
+  /** Conversations behind a number, for example all with a given outcome (1-based pages, at most 200 rows). */
+  conversations(range: AnalyticsRange & { dimension?: string; value?: string; search?: string; page?: number; pageSize?: number }): Promise<unknown> {
+    const q = rangeQuery(range);
+    if (range.dimension) q.dimension = range.dimension;
+    if (range.value) q.value = range.value;
+    if (range.search) q.search = range.search;
+    q.page = String(range.page ?? 1);
+    q.page_size = String(Math.min(range.pageSize ?? 50, 200));
+    return this.client.copilotGet('/organization/:org_id/analytics/conversations/list', q);
+  }
+
+  charts(): Promise<{ charts?: unknown[] }> {
+    return this.client.copilotGet('/organization/:org_id/custom-charts');
+  }
+
+  chart(id: string, range: AnalyticsRange = {}): Promise<unknown> {
+    return this.client.copilotGet(`/organization/:org_id/custom-charts/${id}/data`, rangeQuery(range));
+  }
+}
+
+export interface BusinessHours {
+  businessHoursEnabled: boolean;
+  businessHours?: Array<{ day: number; slots: unknown[] }>;
+  businessHoursUtterance?: string;
+}
+
+/**
+ * Org settings the dashboard lets members change: timezone, business hours,
+ * holidays. Handoff settings are read-only over the API. The route that
+ * deletes the whole configuration is deliberately never called.
+ */
+export class OrgSettingsSDK {
+  constructor(private client: IndemnClient) {}
+
+  get(): Promise<Record<string, unknown>> {
+    return this.client.copilotGet('/organization/:org_id/configurations');
+  }
+
+  /** Whether the org is inside business hours now. */
+  availability(): Promise<unknown> {
+    return this.client.copilotGet('/organization/:org_id/configurations/availability');
+  }
+
+  async setTimezone(timezone: string): Promise<unknown> {
+    try {
+      new Intl.DateTimeFormat('en', { timeZone: timezone });
+    } catch {
+      throw new CliError(`"${timezone}" is not a time zone name, for example America/New_York.`, EXIT.NEEDS_INPUT);
+    }
+    return this.client.copilotRequestRaw('PATCH', '/organization/:org_id/configurations', { timezone });
+  }
+
+  async setBusinessHours(hours: BusinessHours): Promise<unknown> {
+    for (const d of hours.businessHours ?? []) {
+      if (!Number.isInteger(d.day) || d.day < 0 || d.day > 6) throw new CliError('Each business-hours day must be 0 (Sunday) to 6.', EXIT.NEEDS_INPUT);
+    }
+    return this.client.copilotRequestRaw('PATCH', '/organization/:org_id/configurations/business-hours', hours);
+  }
+
+  async addHolidays(holidays: Array<{ name: string; date: string; type?: string; holidayFallbackUtterance?: string }>): Promise<unknown> {
+    if (!holidays.length) throw new CliError('Give at least one holiday.', EXIT.NEEDS_INPUT);
+    return this.client.copilotRequestRaw('PATCH', '/organization/:org_id/configurations/holidays', { holidays });
+  }
+
+  removeHolidays(dates: string[]): Promise<unknown> {
+    return this.client.copilotRequestRaw('DELETE', '/organization/:org_id/configurations/holidays', { holidays: dates.map((date) => ({ date })) });
+  }
+
+  /** Indemn-only feature switches; copilot refuses anyone without an @indemn.ai login. */
+  setAdminSettings(settings: Record<string, unknown>): Promise<unknown> {
+    return this.client.copilotRequestRaw('PATCH', '/organization/:org_id/configurations/admin-settings', settings);
+  }
+
+  /** An Admin-tab change checked as the page checks it; reads the saved disclosure only when the change touches it. */
+  async planAdmin(input: Record<string, unknown>): Promise<AdminPlan> {
+    const touchesDisclosure = input.web_ai_disclosure !== undefined || input.web_ai_disclosure_text !== undefined;
+    return planAdminSettings(input, touchesDisclosure ? await this.get() : {});
+  }
+}
+
+/** The switches on the dashboard's Settings → Admin tab (org-settings.tsx), by the name the MCP tool takes. */
+export const ADMIN_SWITCHES = {
+  conversation_summaries: { key: 'summaryEnabled', label: 'AI Conversation Summaries' },
+  canned_responses: { key: 'cannedResponsesEnabled', label: 'Canned Responses' },
+  indemn_branding: { key: 'displayBranding', label: 'Show Indemn Branding' },
+  underwriting_portal: { key: 'enableUnderwritingPortal', label: 'Underwriting Portal (Intake Manager)' },
+  smart_inbox: { key: 'enableSmartInbox', label: 'Smart Inbox' },
+  solutions: { key: 'enableSolutions', label: 'Solutions' },
+  tickets: { key: 'enableTickets', label: 'Tickets' },
+  agent_testing: { key: 'enableAgentTesting', label: 'Agent Testing Mode' },
+  composer_dictation: { key: 'enableComposerDictation', label: 'Composer Dictation' },
+  web_ai_disclosure: { key: 'showAiDisclosureWeb', label: 'Show Web AI Disclosure' },
+} as const;
+
+/** The conversation timers, in minutes here; copilot stores days and refuses less than these minimums (orgConfig.js). */
+export const ADMIN_TIMERS = {
+  ongoing_to_ended_minutes: { key: 'unassignedInactiveDays', label: 'Ongoing → Ended', min: 1 },
+  ended_to_resolved_minutes: { key: 'endedToResolvedDays', label: 'Ended → Resolved', min: 10 },
+  resolved_to_archived_minutes: { key: 'resolvedToArchivedDays', label: 'Resolved → Archived', min: 1 },
+} as const;
+
+export interface AdminPlan {
+  /** The admin-settings body: real booleans, days for the timers, null for "the default". */
+  body: Record<string, unknown>;
+  /** The changes in the page's words, for the approval. */
+  changes: string[];
+}
+
+function duration(minutes: number): string {
+  const [n, unit] = minutes % 1440 === 0 ? [minutes / 1440, 'day'] : minutes % 60 === 0 ? [minutes / 60, 'hour'] : [minutes, 'minute'];
+  return `${n} ${unit}${n === 1 ? '' : 's'}`;
+}
+
+/** Refuses what the Admin tab refuses: nothing to change, a timer under its minimum, a disclosure shown without text. */
+export function planAdminSettings(input: Record<string, unknown>, saved: Record<string, unknown> = {}): AdminPlan {
+  const body: Record<string, unknown> = {};
+  const changes: string[] = [];
+  for (const [name, s] of Object.entries(ADMIN_SWITCHES)) {
+    if (typeof input[name] !== 'boolean') continue;
+    body[s.key] = input[name];
+    changes.push(`turn ${input[name] ? 'on' : 'off'} ${s.label}`);
+  }
+  // Blank text counts as not given: models fill optional text with "", which must not wipe a saved name or text.
+  const name = typeof input.underwriting_portal_name === 'string' ? input.underwriting_portal_name.trim() : '';
+  if (name) {
+    body.underwritingPortalName = name;
+    changes.push(`name the Intake Manager item "${name}"`);
+  }
+  const disclosure = typeof input.web_ai_disclosure_text === 'string' ? input.web_ai_disclosure_text.trim() : '';
+  if (disclosure) {
+    body.aiDisclosureWeb = disclosure;
+    changes.push(`set the web AI disclosure text to "${disclosure}"`);
+  }
+  for (const [name, t] of Object.entries(ADMIN_TIMERS)) {
+    const minutes = input[name];
+    if (typeof minutes !== 'number') continue;
+    if (minutes !== 0 && (!Number.isFinite(minutes) || minutes < t.min)) {
+      throw new CliError(`${t.label} must be at least ${t.min} minute${t.min === 1 ? '' : 's'}, or 0 for the default.`, EXIT.NEEDS_INPUT);
+    }
+    body[t.key] = minutes === 0 ? null : minutes / 1440;
+    changes.push(minutes === 0 ? `set ${t.label} back to the default` : `set ${t.label} to ${duration(minutes)}`);
+  }
+  if (!changes.length) throw new CliError('Give at least one Admin setting to change.', EXIT.NEEDS_INPUT);
+  const shown = (body.showAiDisclosureWeb ?? saved.showAiDisclosureWeb) === true;
+  const text = body.aiDisclosureWeb ?? saved.aiDisclosureWeb;
+  if (shown && !(typeof text === 'string' && text.trim())) {
+    throw new CliError('The web AI disclosure needs its text: give web_ai_disclosure_text.', EXIT.NEEDS_INPUT);
+  }
+  return { body, changes };
+}
+
+export interface AuditEntry {
+  _id?: string;
+  id_user?: string;
+  event_type?: string;
+  action?: string;
+  resource_type?: string;
+  resource_id?: string;
+  resource_display?: string;
+  status?: string;
+  createdAt?: string;
+  [key: string]: unknown;
+}
+
+/** Who changed what in the org. copilot returns the full history; filtering happens here. */
+export class AuditSDK {
+  constructor(private client: IndemnClient) {}
+
+  async list(filter: { since?: string; action?: string; resourceType?: string; user?: string; limit?: number } = {}): Promise<AuditEntry[]> {
+    const all = await this.client.copilotGet<AuditEntry[]>('/organization/:org_id/audit-logs');
+    const since = filter.since ? Date.parse(filter.since) : undefined;
+    return (all ?? [])
+      .filter((e) => (since === undefined || Date.parse(String(e.createdAt)) >= since))
+      .filter((e) => !filter.action || e.action === filter.action || e.event_type === filter.action)
+      .filter((e) => !filter.resourceType || e.resource_type === filter.resourceType)
+      .filter((e) => !filter.user || String(e.id_user) === filter.user)
+      .slice(0, filter.limit ?? 50);
+  }
+}