@indemn/cli 1.6.0 → 1.7.1

package/src/core/runtime.ts

@@ -0,0 +1,73 @@
+import { createRequire } from 'node:module';
+
+/** Process exit codes. Scripts and agents branch on these. */
+export const EXIT = {
+  OK: 0,
+  ERROR: 1,
+  /** A choice is needed (for example which org) or the command was used wrongly. */
+  NEEDS_INPUT: 2,
+  /** Not logged in, or the session expired and could not be renewed. */
+  AUTH: 3,
+} as const;
+
+export class CliError extends Error {
+  constructor(
+    message: string,
+    public readonly exitCode: number = EXIT.ERROR,
+    public readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = 'CliError';
+  }
+}
+
+export interface Choice {
+  id: string;
+  label: string;
+}
+
+export class NeedsInputError extends CliError {
+  constructor(message: string, public readonly choices: Choice[] = []) {
+    super(message, EXIT.NEEDS_INPUT, { choices });
+    this.name = 'NeedsInputError';
+  }
+}
+
+export class SessionExpiredError extends CliError {
+  constructor(message = 'Session expired. Run `indemn login`, then retry.') {
+    super(message, EXIT.AUTH);
+    this.name = 'SessionExpiredError';
+  }
+}
+
+/**
+ * True when nobody can answer a prompt: an AI agent (Claude Code sets
+ * CLAUDECODE=1), CI, an explicit opt-out, or stdin that is not a terminal.
+ */
+export function isNonInteractive(
+  env: NodeJS.ProcessEnv = process.env,
+  stdinIsTTY: boolean = Boolean(process.stdin.isTTY),
+): boolean {
+  if (env.CLAUDECODE === '1') return true;
+  if (env.CI && env.CI !== 'false' && env.CI !== '0') return true;
+  if (env.INDEMN_NON_INTERACTIVE === '1') return true;
+  return !stdinIsTTY;
+}
+
+export function isDebug(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.INDEMN_DEBUG === '1';
+}
+
+let cachedVersion: string | undefined;
+
+/** The package version, read from package.json (src/core and dist/core are both two levels down). */
+export function cliVersion(): string {
+  if (!cachedVersion) {
+    const require = createRequire(import.meta.url);
+    cachedVersion = (require('../../package.json') as { version: string }).version;
+  }
+  return cachedVersion;
+}
+
+/** How long a question to a person (through an MCP host) may stay open. The MCP default of 60 s is too short to read a diff. */
+export const PERSON_TIMEOUT_MS = 10 * 60_000;

package/src/core/scope.ts

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Environment } from '../sdk/types.js';
+import type { OrgChoice, OrgSource } from './org-resolver.js';
+
+/**
+ * The org one MCP tool call acts on. Each call runs inside its own scope, so
+ * two concurrent calls for different orgs never see each other's org.
+ */
+const orgScope = new AsyncLocalStorage<{ orgId: string }>();
+
+export function runWithOrg<T>(orgId: string | undefined, fn: () => Promise<T>): Promise<T> {
+  return orgId ? orgScope.run({ orgId }, fn) : fn();
+}
+
+export function scopedOrg(): string | undefined {
+  return orgScope.getStore()?.orgId;
+}
+
+/** The terminal `--org` flag, process-wide for one CLI command. */
+let orgFlag: string | undefined;
+export function setOrgFlag(flag?: string): void {
+  orgFlag = flag || undefined;
+}
+export function getOrgFlag(): string | undefined {
+  return orgFlag;
+}
+
+/** How to ask the person something: a terminal prompt, an MCP elicitation, or nothing. */
+export interface FormField {
+  key: string;
+  title: string;
+  description?: string;
+  required?: boolean;
+}
+
+export interface Askers {
+  chooseOrg?: (choices: OrgChoice[]) => Promise<string | undefined>;
+  mfaCode?: () => Promise<string>;
+  /** Ask for several text fields at once; undefined when declined or nobody can answer. */
+  form?: (message: string, fields: FormField[]) => Promise<Record<string, string> | undefined>;
+}
+let askers: Askers = {};
+export function setAskers(a: Askers): void {
+  askers = a;
+}
+export function getAskers(): Askers {
+  return askers;
+}
+
+export interface ResolvedOrgEvent {
+  id: string;
+  name?: string;
+  source: OrgSource;
+  environment: Environment;
+}
+type Listener = (org: ResolvedOrgEvent) => void;
+const listeners: Listener[] = [];
+/** Called once per client when its org is decided; the CLI prints its banner here. */
+export function onOrgResolved(fn: Listener): void {
+  listeners.push(fn);
+}
+export function emitOrgResolved(org: ResolvedOrgEvent): void {
+  for (const fn of listeners) fn(org);
+}

package/src/mcp/registry.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod/v3';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Environment } from '../sdk/types.js';
+import { NeedsInputError, PERSON_TIMEOUT_MS } from '../core/runtime.js';
+import { runWithOrg } from '../core/scope.js';
+import { TOOL_META, type ToolMeta } from './tool-meta.js';
+
+/** Where a tool result came from. Every successful result carries it. */
+export interface ResultContext {
+  org_id?: string;
+  org_name?: string;
+  environment: Environment;
+  /** The person approved this call in the host's approval form (the model cannot see that form). */
+  approved_by_person?: boolean;
+}
+
+type Shape = Record<string, z.ZodTypeAny>;
+type Args = Record<string, unknown>;
+/** `confirmedByPerson` is true when the host asked the person and they agreed. */
+type Handler = (args: any, meta: { confirmedByPerson: boolean }) => Promise<CallToolResult>;
+
+function text(data: unknown, isError = false): CallToolResult {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], ...(isError ? { isError: true } : {}) };
+}
+
+/**
+ * Handlers return `success(data)`, a JSON text block. Rewrap it as
+ * `{ context, data }` so the caller always sees which org and platform
+ * answered. Error results and non-JSON text pass through untouched.
+ */
+/** About 20k tokens: Claude Code refuses tool results over 25k tokens. */
+export const MAX_RESULT_CHARS = 80_000;
+
+/** Keep a result inside the size limit: trim a list and say so, or cut other text with a note. */
+function fit(body: { context: ResultContext; data: unknown }): CallToolResult {
+  const full = JSON.stringify(body, null, 2);
+  if (full.length <= MAX_RESULT_CHARS) return text(body);
+  const hint = 'Result was too large. Ask for less: use limit/page, a filter, or response_format "concise".';
+  const list = Array.isArray(body.data) ? body.data : (body.data as { items?: unknown[] } | null)?.items;
+  if (Array.isArray(list)) {
+    const shaped = (keep: number) => ({ context: body.context, data: { items: list.slice(0, keep), returned: keep, total: list.length, truncated: true, hint } });
+    let keep = list.length;
+    while (keep > 0 && JSON.stringify(shaped(keep), null, 2).length > MAX_RESULT_CHARS) keep = Math.floor(keep * 0.7);
+    return text(shaped(keep));
+  }
+  return { content: [{ type: 'text', text: `${full.slice(0, MAX_RESULT_CHARS)}\n... [truncated: ${full.length - MAX_RESULT_CHARS} more characters. ${hint}]` }] };
+}
+
+function withContext(result: CallToolResult, context: ResultContext, page?: { limit: number; page: number }): CallToolResult {
+  if (result.isError || result.content.length !== 1 || result.content[0].type !== 'text') return result;
+  let data: unknown;
+  try {
+    data = JSON.parse(result.content[0].text);
+  } catch {
+    return result;
+  }
+  // A question back to the caller is not data from the platform: keep its shape.
+  if (data && typeof data === 'object' && (data as { needs_input?: unknown }).needs_input === true) return result;
+  if (page && Array.isArray(data)) {
+    const all = data;
+    const end = (page.page - 1) * page.limit + page.limit;
+    const hasMore = end < all.length;
+    // Spelled out: a bare has_more is easy for a model to skip, then it answers from one page.
+    const next = hasMore ? { next: `${all.length - end} more: call again with page ${page.page + 1}` } : {};
+    data = { items: all.slice(end - page.limit, end), page: page.page, limit: page.limit, total: all.length, has_more: hasMore, ...next };
+  }
+  return fit({ context, data });
+}
+
+/** Why a person's answer stopped the change, so the agent tells them instead of retrying. */
+const NOT_APPROVED: Record<string, string> = {
+  accept: 'Proceed was not ticked. Nothing was changed.',
+  // Said as a choice, not a failure: a model reading "declined" as an error calls the tool again.
+  decline: 'The person pressed Decline: they chose not to make this change. Nothing was changed. Tell them so and do not call this tool again unless they ask for it again.',
+  cancel: 'The question was dismissed, or this host cannot show it (Claude Code in -p mode cancels at once). Nothing was changed; calling again with confirm: true does not help. Approve in an interactive session, or use the indemn CLI with --yes.',
+};
+
+/**
+ * Ask before a destructive call. With elicitation the host asks the person
+ * directly and a `confirm` argument is ignored, so an agent cannot confirm
+ * for itself. Without elicitation `confirm: true` proceeds; anything else
+ * returns a dry run and the call is not made.
+ */
+/** Approval forms show a few short lines: a long prompt diff would push the Proceed box off the screen. */
+export function fitForm(text: string, maxLines = 8, maxLine = 140): string {
+  const lines = text.split('\n');
+  // A short message stays whole; only long, many-line text (a prompt diff) is shortened.
+  const cut = lines.length > maxLines || text.length > 900;
+  const shown = lines.slice(0, maxLines).map((l) => (l.length > maxLine ? `${l.slice(0, maxLine - 1)}…` : l));
+  return cut ? `${shown.join('\n')}\n(Shortened to fit; ask to see the full change before approving.)` : text;
+}
+
+export async function guardDestructive(
+  server: McpServer,
+  toolName: string,
+  args: Args,
+  preview: string,
+  formText: string = preview,
+): Promise<{ proceed: true; byPerson: boolean } | { proceed: false; result: CallToolResult }> {
+  if (server.server.getClientCapabilities()?.elicitation) {
+    try {
+      const answer = await server.server.elicitInput({
+        message: `${formText} Proceed?`,
+        requestedSchema: {
+          type: 'object',
+          properties: { confirm: { type: 'boolean', title: 'Proceed', description: 'Tick (Space), then submit, to make this change.' } },
+          required: ['confirm'],
+        },
+      }, { timeout: PERSON_TIMEOUT_MS });
+      if (answer.action === 'accept' && answer.content?.confirm === true) return { proceed: true, byPerson: true };
+      return { proceed: false, result: text({ cancelled: true, action: toolName, would: preview, reason: NOT_APPROVED[answer.action] }) };
+    } catch (err) {
+      if ((err as { code?: number } | undefined)?.code === ErrorCode.RequestTimeout) {
+        return { proceed: false, result: text({ cancelled: true, action: toolName, would: preview, reason: 'No answer within 10 minutes; nothing was changed.' }) };
+      }
+      // The host can ask the person but asking failed: nothing is changed. Falling back to `confirm`
+      // would let the model approve its own change.
+      return { proceed: false, result: text({ cancelled: true, action: toolName, would: preview, reason: 'The approval form could not be shown, so nothing was changed. Tell the person; they can ask again.' }) };
+    }
+  }
+  if (args.confirm === true) return { proceed: true, byPerson: false };
+  return {
+    proceed: false,
+    result: text({
+      dry_run: true,
+      action: toolName,
+      would: preview,
+      to_proceed: 'Show this to the user. Only after they agree, call again with confirm: true.',
+    }),
+  };
+}
+
+function defaultPreview(name: string, meta: ToolMeta, args: Args): string {
+  const shown = Object.entries(args)
+    .filter(([k]) => k !== 'confirm' && k !== 'org_id')
+    .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+    .join(', ');
+  return `${meta.title} (${name}${shown ? `: ${shown}` : ''}).`;
+}
+
+export function createRegistry(
+  server: McpServer,
+  opts: {
+    context: () => Promise<ResultContext> | ResultContext;
+    meta?: Record<string, ToolMeta>;
+    /** Decide the org for one call from its org_id argument (else link, only org, or ask). */
+    resolveOrg?: (explicit?: string) => Promise<{ id: string; name?: string }>;
+    /**
+     * Names for the ids of a call (agent, knowledge base, org…), shown in approvals instead of the ids,
+     * and the ids that name nothing (no card is shown for those).
+     */
+    displayNames?: (args: Args, orgId?: string) => Promise<{ names: Record<string, string>; missing?: string[] }>;
+  },
+) {
+  const metaTable = opts.meta ?? TOOL_META;
+  const registered: string[] = [];
+
+  return {
+    tool(name: string, description: string, shape: Shape, handler: Handler, extra: { preview?: (args: Args) => Promise<string>; guardWhen?: (args: Args) => Promise<boolean> } = {}): void {
+      const meta = metaTable[name];
+      if (!meta) throw new Error(`MCP tool "${name}" has no entry in tool-meta.ts`);
+
+      const inputSchema: Shape = { ...shape };
+      const orgScoped = meta.orgScoped !== false && Boolean(opts.resolveOrg);
+      if (orgScoped) {
+        inputSchema.org_id = z
+          .string()
+          .optional()
+          .describe('Organization id to act on. Omit it to use the linked folder or your only org; with several orgs you are asked.');
+      }
+      if (meta.paginate && ('limit' in shape || 'page' in shape)) {
+        throw new Error(`MCP tool "${name}" is paged by the registry; remove its own limit/page arguments`);
+      }
+      const paginate = Boolean(meta.paginate);
+      if (paginate) {
+        inputSchema.limit = z.number().int().min(1).max(200).optional().describe('Items per page (default 50)');
+        inputSchema.page = z.number().int().min(1).optional().describe('Page, starting at 1');
+      }
+      if (meta.guard) {
+        inputSchema.confirm = z
+          .boolean()
+          .optional()
+          .describe('Set true only after the user has agreed to the dry run. Ignored when the host can ask the user itself.');
+      }
+
+      server.registerTool(
+        name,
+        { title: meta.title, description, inputSchema, annotations: meta.annotations },
+        (async (args: Args) => {
+          try {
+            const org = orgScoped ? await opts.resolveOrg!(typeof args.org_id === 'string' ? args.org_id : undefined) : undefined;
+            return await runWithOrg(org?.id, async () => {
+              let confirmedByPerson = false;
+              // A guarded tool asks every time, or only when guardWhen says so (e.g. the agent may be live).
+              if (meta.guard && (!extra.guardWhen || await extra.guardWhen(args))) {
+                // Names, not ids, in what the person approves ("Darwin Web Test", not 6abb…).
+                const found: { names: Record<string, string>; missing?: string[] } = opts.displayNames
+                  ? await opts.displayNames(args, org?.id).catch(() => ({ names: {} }))
+                  : { names: {} };
+                if (found.missing?.length) {
+                  return { content: [{ type: 'text', text: `Error: Not found: ${found.missing.join(', ')}. Nothing was changed and nothing was asked. Look it up again (list tools give the ids) and retry.` }], isError: true };
+                }
+                const names: Record<string, string> = found.names;
+                const named = (s: string) => Object.entries(names).reduce((t, [id, label]) => t.split(id).join(`"${label}"`), s);
+                const base = named(extra.preview ? await extra.preview(args) : meta.describe ? meta.describe(args) : defaultPreview(name, meta, args));
+                const ctx = await opts.context();
+                const orgLabel = org ? org.name ?? names[org.id] ?? org.id : undefined;
+                const where = orgLabel ? ` Org: ${orgLabel}. Platform: ${ctx.environment}.` : ` Platform: ${ctx.environment}.`;
+                const gate = await guardDestructive(server, name, args, base + where, fitForm(base) + where);
+                if (!gate.proceed) return gate.result;
+                confirmedByPerson = gate.byPerson;
+              }
+              const result = await handler(args, { confirmedByPerson });
+              return withContext(result, { ...(await opts.context()), ...(confirmedByPerson ? { approved_by_person: true } : {}) }, paginate ? { limit: Number(args.limit ?? 50), page: Number(args.page ?? 1) } : undefined);
+            });
+          } catch (err) {
+            if (err instanceof NeedsInputError) {
+              // The resolver's text names the CLI flag; an MCP caller passes org_id.
+              const message = err.message.replace('Choose one with --org <id>', 'Call again with org_id set to one of the ids below');
+              return text({ needs_input: true, message, choices: err.choices, to_proceed: 'Ask the user which organization to use, then call again with org_id set to its id.' });
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+          }
+        }) as never,
+      );
+      registered.push(name);
+    },
+    names(): string[] {
+      return [...registered];
+    },
+  };
+}
+
+export type Registry = ReturnType<typeof createRegistry>;

package/src/mcp/server.ts

@@ -2,14 +2,96 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { IndemnClient } from '../sdk/client.js';
 import { registerTools } from './tools.js';
+import { setAskers, type Askers } from '../core/scope.js';
+import { cliVersion, SessionExpiredError, PERSON_TIMEOUT_MS } from '../core/runtime.js';
+
+/**
+ * Questions the CLI may need answered during a tool call, asked through the
+ * host (Claude Code shows a dialog). Stdin carries the MCP protocol, so the
+ * terminal is never used. Without elicitation: the org question becomes a
+ * needs_input result, and an MFA renewal asks the person to log in again.
+ */
+export function mcpAskers(server: McpServer): Askers {
+  const canAsk = () => Boolean(server.server.getClientCapabilities()?.elicitation);
+  // A person needs time to answer; the MCP default of 60 s is too short.
+  const ask = (params: Parameters<typeof server.server.elicitInput>[0]) => server.server.elicitInput(params, { timeout: PERSON_TIMEOUT_MS });
+  return {
+    chooseOrg: async (choices) => {
+      if (!canAsk()) return undefined;
+      try {
+        const answer = await ask({
+          message: 'You belong to several organizations. Which one should this act on?',
+          requestedSchema: {
+            type: 'object',
+            properties: {
+              org_id: {
+                type: 'string',
+                title: 'Organization',
+                oneOf: choices.map((c) => ({ const: c.id, title: c.name ? `${c.name} (${c.id})` : c.id })),
+              },
+            },
+            required: ['org_id'],
+          },
+        });
+        return answer.action === 'accept' && typeof answer.content?.org_id === 'string' ? answer.content.org_id : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    form: async (message, fields) => {
+      if (!canAsk()) return undefined;
+      try {
+        const answer = await ask({
+          message,
+          requestedSchema: {
+            type: 'object',
+            properties: Object.fromEntries(fields.map((f) => [f.key, { type: 'string', title: f.title, description: f.description }])),
+            required: fields.filter((f) => f.required).map((f) => f.key),
+          },
+        });
+        if (answer.action !== 'accept' || !answer.content) return undefined;
+        return Object.fromEntries(Object.entries(answer.content).map(([k, v]) => [k, String(v ?? '')]));
+      } catch {
+        return undefined;
+      }
+    },
+    mfaCode: async () => {
+      if (!canAsk()) {
+        throw new SessionExpiredError('The session needs renewing and your account uses MFA. Run `indemn login` in a terminal, then retry.');
+      }
+      const answer = await ask({
+        message: 'Your Indemn session needs renewing. Enter the MFA code that was just emailed to you.',
+        requestedSchema: {
+          type: 'object',
+          properties: { code: { type: 'string', title: 'MFA code', description: '6 digits', minLength: 6, maxLength: 6 } },
+          required: ['code'],
+        },
+      });
+      if (answer.action !== 'accept' || typeof answer.content?.code !== 'string') {
+        throw new SessionExpiredError('MFA code not entered. Run `indemn login` in a terminal, then retry.');
+      }
+      return answer.content.code;
+    },
+  };
+}
+
+/** Guidance every MCP host (Claude Code, Jarvis, others) gives the model. */
+const SERVER_INSTRUCTIONS = [
+  'Indemn tools manage AI agents on the Indemn platform for the signed-in person.',
+  'Talking to people: call agents, knowledge bases, skills, test sets, rubrics and runs by their names, never ids. Show an id only when the person asks for one; tell two items with the same name apart by a detail such as the channel or phone number. When the person wants more about an item, give its url (its page in the dashboard). Use plain words instead of internal field names, keep answers short, and offer details on request.',
+  'Changes: when the host shows an approval form, that form is the question; call the tool and do not ask again in chat. context.approved_by_person means the person approved in that form. When a tool returns dry_run instead, show it and call again with confirm: true only after the person agreed.',
+  'If a tool returns needs_input, ask the person and call again with their answer.',
+].join('\n');
 
 export async function startServer(): Promise<void> {
+  IndemnClient.setClientKind('mcp');
   const client = new IndemnClient();
   const server = new McpServer({
     name: 'indemn',
-    version: '1.0.0',
-  });
+    version: cliVersion(),
+  }, { instructions: SERVER_INSTRUCTIONS });
 
+  setAskers(mcpAskers(server));
   registerTools(server, client);
 
   const transport = new StdioServerTransport();