@msg91comm/m91 0.0.0-stage → 1.2.0

package/src/integrations/langchain.ts

@@ -0,0 +1,207 @@
+/**
+ * LangChain tools.
+ *
+ * Two of them, and the split matters more than it looks:
+ *
+ * - the approval tool **blocks**. The agent stops until a human answers on
+ *   their phone. Give it to an agent that can do something irreversible.
+ * - the alert tool does not. It wakes somebody and carries on.
+ *
+ * ```ts
+ * import { M91Client } from '@msg91comm/m91';
+ * import { createM91ApprovalTool, createM91AlertTool } from '@msg91comm/m91/integrations/langchain';
+ *
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ * const tools = [
+ *   await createM91ApprovalTool(client),
+ *   await createM91AlertTool(client),
+ *   ...myTools,
+ * ];
+ * const agent = createAgent({ model: 'openai:gpt-5-mini', tools });  // from 'langchain'
+ * ```
+ *
+ * The factories are **async** because `@langchain/core` is an optional peer
+ * dependency, imported only when one of these is called. That keeps `npm
+ * install @msg91comm/m91` at zero dependencies, which matters for a package whose job is
+ * to work when everything else is on fire.
+ */
+
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+
+import type { M91Client } from '../client.js';
+import {
+  ALERT_DESCRIPTION,
+  ALERT_SCHEMA,
+  ALERT_TOOL_NAME,
+  APPROVAL_DESCRIPTION,
+  APPROVAL_SCHEMA,
+  APPROVAL_TOOL_NAME,
+  type AlertArgs,
+  type AlertDefaults,
+  type ApprovalArgs,
+  type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
+  runAlert,
+  runApproval,
+} from './specs.js';
+
+async function langchainTool(): Promise<(fn: unknown, config: unknown) => unknown> {
+  try {
+    // The specifier is a variable so TypeScript does not try to resolve an
+    // optional peer dependency at build time. Compiling this package must not
+    // require every framework it can adapt to.
+    const specifier = '@langchain/core/tools';
+    const mod = (await import(specifier)) as { tool: (fn: unknown, config: unknown) => unknown };
+    return mod.tool;
+  } catch (error) {
+    throw new Error(
+      'The LangChain integration needs @langchain/core. Install it with: ' +
+        'npm install @langchain/core',
+      { cause: error },
+    );
+  }
+}
+
+/**
+ * The blocking approval gate, as a LangChain tool named `m91_request_approval`.
+ * Returns `"approved"`, `"rejected"` or `"error: …"` — and nothing but a real
+ * human approval returns `"approved"`.
+ */
+export async function createM91ApprovalTool(
+  client: M91Client,
+  defaults: ApprovalDefaults = {},
+): Promise<DynamicStructuredTool> {
+  const tool = await langchainTool();
+  return tool((args: ApprovalArgs) => runApproval(client, args, defaults), {
+    name: APPROVAL_TOOL_NAME,
+    description: APPROVAL_DESCRIPTION,
+    schema: APPROVAL_SCHEMA,
+  }) as DynamicStructuredTool;
+}
+
+/**
+ * The fire-and-forget alert, as a LangChain tool named `m91_send_alert`.
+ * Returns `"sent:delivered=N"` or `"error: …"`.
+ */
+export async function createM91AlertTool(
+  client: M91Client,
+  defaults: AlertDefaults = {},
+): Promise<DynamicStructuredTool> {
+  const tool = await langchainTool();
+  return tool((args: AlertArgs) => runAlert(client, args, defaults), {
+    name: ALERT_TOOL_NAME,
+    description: ALERT_DESCRIPTION,
+    schema: ALERT_SCHEMA,
+  }) as DynamicStructuredTool;
+}
+
+/** Both, in the order an agent's `tools` array usually wants them. */
+export async function createM91Tools(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<DynamicStructuredTool[]> {
+  return [
+    await createM91ApprovalTool(client, defaults),
+    await createM91AlertTool(client, defaults),
+  ];
+}
+
+/* ------------------------------------------------------------------------ */
+/* humanInTheLoopMiddleware / Deep Agents: answering the interrupt          */
+/* ------------------------------------------------------------------------ */
+
+/** One tool call the middleware paused on, as `HITLRequest.actionRequests` carries it. */
+interface ActionRequestLike {
+  name: string;
+  args: Record<string, unknown>;
+  description?: string;
+}
+
+/** The payload of the interrupt `humanInTheLoopMiddleware` (and Deep Agents' `interruptOn`) raises. */
+export interface HITLRequestLike {
+  actionRequests: ActionRequestLike[];
+}
+
+/** What the middleware expects back: one decision per action request, in order. */
+export interface M91HITLResponse {
+  decisions: Array<{ type: 'approve' } | { type: 'reject'; message: string }>;
+}
+
+function isHITLRequest(value: unknown): value is HITLRequestLike {
+  return Array.isArray((value as HITLRequestLike | undefined)?.actionRequests);
+}
+
+/**
+ * Ask a person about every tool call in a `HITLRequest`, one phone alert per
+ * call, and build the `{ decisions }` the middleware resumes with.
+ *
+ * `"approved"` / `"rejected"` strings (what `M91InterruptNotifier` returns) are
+ * **not** a valid resume value for the middleware; this is.
+ *
+ * `threadId` makes each alert's customId stable across a retry of the same
+ * pause, so a retried resume does not ring twice.
+ */
+export async function resolveHITLWithM91(
+  request: HITLRequestLike,
+  client: M91Client,
+  options: GateOptions & { threadId?: string } = {},
+): Promise<M91HITLResponse> {
+  const decisions: M91HITLResponse['decisions'] = [];
+  for (const [index, action] of request.actionRequests.entries()) {
+    const callId = `${options.threadId ?? 'run'}-${index}`;
+    const decision = await decideToolCall(
+      client,
+      { toolName: action.name, input: action.args, callId },
+      options,
+    );
+    decisions.push(decision.approved ? { type: 'approve' } : { type: 'reject', message: decision.reason });
+  }
+  return { decisions };
+}
+
+/** The parts of a LangChain agent / Deep Agent / compiled graph this file calls. */
+export interface InvokableAgentLike {
+  invoke(input: any, config?: any): Promise<any>;
+}
+
+/**
+ * `agent.invoke()`, with every `humanInTheLoopMiddleware` pause answered on a
+ * phone through M91 and resumed with `Command({ resume: { decisions } })`.
+ * Works for `createAgent` with `humanInTheLoopMiddleware` and for Deep Agents
+ * created with `interruptOn`. Needs a checkpointer and a `thread_id`.
+ */
+export async function invokeWithM91Approvals<TResult = any>(
+  agent: InvokableAgentLike,
+  input: unknown,
+  config: { configurable: { thread_id: string } } & Record<string, unknown>,
+  client: M91Client,
+  options: GateOptions & { maxRounds?: number } = {},
+): Promise<TResult> {
+  const { Command } = await langgraphModule();
+  const { maxRounds = 20, ...gate } = options;
+  let result = await agent.invoke(input, config);
+  for (let round = 0; round < maxRounds; round += 1) {
+    const pending = (result?.__interrupt__ as Array<{ value: unknown }> | undefined)?.[0]?.value;
+    if (!isHITLRequest(pending)) break;
+    const response = await resolveHITLWithM91(pending, client, {
+      ...gate,
+      threadId: `${config.configurable.thread_id}-${round}`,
+    });
+    result = await agent.invoke(new Command({ resume: response }), config);
+  }
+  return result as TResult;
+}
+
+async function langgraphModule(): Promise<{ Command: new (options: { resume: unknown }) => unknown }> {
+  try {
+    const specifier = '@langchain/langgraph';
+    return (await import(specifier)) as { Command: new (options: { resume: unknown }) => unknown };
+  } catch (error) {
+    throw new Error(
+      'Resuming a LangChain / Deep Agents interrupt needs @langchain/langgraph. Install it with: ' +
+        'npm install @langchain/langgraph',
+      { cause: error },
+    );
+  }
+}

package/src/integrations/langgraph.ts

@@ -0,0 +1,142 @@
+/**
+ * LangGraph helpers for the `interrupt()` pattern.
+ *
+ * LangGraph already knows how to stop a graph and resume it. What it has no
+ * opinion about is **how the human finds out it stopped** — and the default
+ * answer is that somebody notices a paused run in a web UI. At 2am, for a graph
+ * that paused because it wants to move money, nobody does. M91 fills exactly
+ * that gap: the graph pauses, a phone rings until somebody answers, and the
+ * answer resumes the graph.
+ *
+ * Nothing here imports `@langchain/langgraph`. These are plain callables you use
+ * *around* your graph, so they work the same with `interrupt()`, with
+ * `new Command({ resume })`, or with a node you wrote by hand.
+ */
+
+import type { M91Client } from '../client.js';
+import type { Severity } from '../models.js';
+import { APPROVED, REJECTED } from './specs.js';
+
+export interface NotifyOptions {
+  title: string;
+  customId: string;
+  description?: string;
+  severity?: Severity;
+  approveLabel?: string;
+  rejectLabel?: string;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+}
+
+export type NotifyDefaults = Omit<NotifyOptions, 'title' | 'customId'>;
+
+export type Verdict = typeof APPROVED | typeof REJECTED;
+
+/**
+ * Wake a human about an interrupted graph and return what they said.
+ *
+ * ```ts
+ * const notifier = new M91InterruptNotifier(client);
+ *
+ * const result = await graph.invoke(state, config);
+ * if (result.__interrupt__) {
+ *   const data = result.__interrupt__[0].value;
+ *   const decision = await notifier.notify({
+ *     title: data.question,
+ *     customId: data.customId,
+ *     timeoutMs: 600_000,
+ *   });
+ *   await graph.invoke(new Command({ resume: decision }), config);
+ * }
+ * ```
+ *
+ * Resolves `"approved"` or `"rejected"` and **never anything else** — a failure
+ * to reach anybody comes back as `"rejected"`, because a graph that resumes
+ * with an ambiguous value resumes with whatever the node's `if` happens to do
+ * with it.
+ */
+export class M91InterruptNotifier {
+  private readonly client: M91Client;
+  private readonly defaults: NotifyDefaults;
+
+  constructor(client: M91Client, defaults: NotifyDefaults = {}) {
+    this.client = client;
+    this.defaults = defaults;
+  }
+
+  async notify(options: NotifyOptions): Promise<Verdict> {
+    const { title, customId, ...rest } = options;
+    const merged = { ...this.defaults, ...strip(rest) };
+    try {
+      const approved = await this.client.requestApproval(title, {
+        customId,
+        severity: 'HIGH',
+        timeoutMs: 300_000,
+        ...merged,
+      });
+      return approved ? APPROVED : REJECTED;
+    } catch {
+      // Nobody could be reached, so nobody approved. Resuming a graph with
+      // "approved" because the pager was down is the one outcome worth ruling
+      // out by construction.
+      return REJECTED;
+    }
+  }
+}
+
+/**
+ * Build a graph node that asks a human and writes the answer into state.
+ *
+ * ```ts
+ * builder.addNode('humanApproval', createM91ApprovalNode(client, {
+ *   approveLabel: 'Deploy Now',
+ *   rejectLabel: 'Hold Release',
+ *   timeoutMs: 600_000,
+ * }));
+ * ```
+ *
+ * The node reads `title` (or `question`) and `customId` from state and returns
+ * `{ decision, approved }` for the next edge to branch on. Anything passed here
+ * is a default the state can override per run.
+ */
+export function createM91ApprovalNode(
+  client: M91Client,
+  defaults: NotifyDefaults = {},
+): (state: unknown) => Promise<{ decision: Verdict; approved: boolean; error?: string }> {
+  const notifier = new M91InterruptNotifier(client, defaults);
+
+  return async (state: unknown) => {
+    const data = (state && typeof state === 'object' ? state : {}) as Record<string, unknown>;
+    const title = data.title ?? data.question;
+    const customId = data.customId ?? data.custom_id;
+
+    if (!title || !customId) {
+      // Said loudly rather than defaulted. A node that invents a customId is a
+      // node whose alerts never deduplicate and never close.
+      return {
+        decision: REJECTED,
+        approved: false,
+        error:
+          "error: the approval node needs 'title' (or 'question') and 'customId' in state",
+      };
+    }
+
+    const decision = await notifier.notify({
+      title: String(title),
+      customId: String(customId),
+      ...strip({
+        description: data.description as string | undefined,
+        severity: data.severity as Severity | undefined,
+        approveLabel: data.approveLabel as string | undefined,
+        rejectLabel: data.rejectLabel as string | undefined,
+        timeoutMs: data.timeoutMs as number | undefined,
+      }),
+    });
+    return { decision, approved: decision === APPROVED };
+  };
+}
+
+/** Drop undefined keys so a spread cannot blank out a default with `undefined`. */
+function strip<T extends Record<string, unknown>>(value: T): Partial<T> {
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>;
+}

package/src/integrations/mastra.ts

@@ -0,0 +1,178 @@
+/**
+ * Mastra (`@mastra/core`): M91 as the approver for `requireApproval` tools,
+ * and M91 as tools.
+ *
+ * **Approver.** Mark your risky tools `requireApproval: true`. Mastra suspends
+ * the run when the agent calls one; `generateWithM91Approvals` rings a phone
+ * for each suspended call and approves or declines it with the person's
+ * answer until the run finishes.
+ *
+ * ```ts
+ * import { Agent } from '@mastra/core/agent';
+ * import { createTool } from '@mastra/core/tools';
+ * import { M91Client } from '@msg91comm/m91';
+ * import { generateWithM91Approvals } from '@msg91comm/m91/integrations/mastra';
+ *
+ * const issueRefund = createTool({
+ *   id: 'issue-refund',
+ *   description: 'Refund an order.',
+ *   inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
+ *   requireApproval: true,
+ *   execute: async ({ orderId, amount }) => refunds.create(orderId, amount),
+ * });
+ *
+ * const agent = new Agent({ id: 'support', name: 'Support', instructions: '…',
+ *   model: 'openai/gpt-5-mini', tools: { issueRefund } });
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ *
+ * const output = await generateWithM91Approvals(agent, 'Refund ORD-40122.', client);
+ * console.log(output.text);
+ * ```
+ *
+ * Mastra keeps suspended runs in its storage, so configure a storage provider
+ * on your `Mastra` instance for approvals to resume.
+ */
+
+import type { Tool } from '@mastra/core/tools';
+
+import type { M91Client } from '../client.js';
+import {
+  ALERT_DESCRIPTION,
+  ALERT_TOOL_NAME,
+  APPROVAL_DESCRIPTION,
+  APPROVAL_TOOL_NAME,
+  type AlertArgs,
+  type AlertDefaults,
+  type ApprovalArgs,
+  type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
+  needsHuman,
+  runAlert,
+  runApproval,
+} from './specs.js';
+import { alertShape, approvalShape, loadZod } from './zod-shapes.js';
+
+/** The parts of a Mastra `generate()` result this file reads. */
+export interface MastraOutputLike {
+  text: string;
+  finishReason?: unknown;
+  runId?: string;
+  suspendPayload?: unknown;
+}
+
+/** The parts of a Mastra `Agent` this file calls. */
+export interface MastraAgentLike<TOutput extends MastraOutputLike = MastraOutputLike> {
+  generate(prompt: any, options?: any): Promise<TOutput>;
+  approveToolCallGenerate(options: { runId: string; toolCallId?: string }): Promise<TOutput>;
+  declineToolCallGenerate(options: {
+    runId: string;
+    toolCallId?: string;
+    reason?: string;
+  }): Promise<TOutput>;
+}
+
+interface PendingApproval {
+  toolCallId: string;
+  toolName: string;
+  args: unknown;
+}
+
+function pendingApproval(output: MastraOutputLike): PendingApproval | null {
+  if (output.finishReason !== 'suspended' || !output.runId) return null;
+  const payload = output.suspendPayload as Partial<PendingApproval> | undefined;
+  if (!payload?.toolCallId || !payload.toolName) return null;
+  return { toolCallId: payload.toolCallId, toolName: payload.toolName, args: payload.args };
+}
+
+/**
+ * `agent.generate()`, with every tool approval the run suspends for answered
+ * on a phone through M91. Approvals for tools outside `options.tools` are
+ * returned still suspended, for your own code.
+ */
+export async function generateWithM91Approvals<TOutput extends MastraOutputLike>(
+  agent: MastraAgentLike<TOutput>,
+  prompt: unknown,
+  client: M91Client,
+  options: GateOptions & { generateOptions?: Record<string, unknown>; maxRounds?: number } = {},
+): Promise<TOutput> {
+  const { generateOptions, maxRounds = 20, ...gate } = options;
+  let output = await agent.generate(prompt, generateOptions);
+  for (let round = 0; round < maxRounds; round += 1) {
+    const pending = pendingApproval(output);
+    if (!pending || !(await needsHuman(gate, pending.toolName, pending.args))) break;
+    const runId = output.runId as string;
+    const decision = await decideToolCall(
+      client,
+      { toolName: pending.toolName, input: pending.args, callId: pending.toolCallId },
+      gate,
+    );
+    output = decision.approved
+      ? await agent.approveToolCallGenerate({ runId, toolCallId: pending.toolCallId })
+      : await agent.declineToolCallGenerate({
+          runId,
+          toolCallId: pending.toolCallId,
+          reason: decision.reason,
+        });
+  }
+  return output;
+}
+
+interface MastraToolsModule {
+  createTool: (options: unknown) => unknown;
+}
+
+async function mastraTools(): Promise<MastraToolsModule> {
+  try {
+    const specifier = '@mastra/core/tools';
+    return (await import(specifier)) as unknown as MastraToolsModule;
+  } catch (error) {
+    throw new Error('The Mastra integration needs @mastra/core. Install it with: npm install @mastra/core', {
+      cause: error,
+    });
+  }
+}
+
+/** A Mastra tool, typed loosely enough to drop into any agent's `tools`. */
+export type M91MastraTool = Tool<any, any, any, any, any, string, any>;
+
+/** The blocking approval tool, `m91_request_approval`, as a Mastra tool. */
+export async function createM91ApprovalTool(
+  client: M91Client,
+  defaults: ApprovalDefaults = {},
+): Promise<M91MastraTool> {
+  const { createTool } = await mastraTools();
+  const z = await loadZod('Mastra');
+  return createTool({
+    id: APPROVAL_TOOL_NAME,
+    description: APPROVAL_DESCRIPTION,
+    inputSchema: z.object(approvalShape(z)),
+    execute: async (args: ApprovalArgs) => ({ result: await runApproval(client, args, defaults) }),
+  }) as M91MastraTool;
+}
+
+/** The fire-and-forget alert tool, `m91_send_alert`, as a Mastra tool. */
+export async function createM91AlertTool(
+  client: M91Client,
+  defaults: AlertDefaults = {},
+): Promise<M91MastraTool> {
+  const { createTool } = await mastraTools();
+  const z = await loadZod('Mastra');
+  return createTool({
+    id: ALERT_TOOL_NAME,
+    description: ALERT_DESCRIPTION,
+    inputSchema: z.object(alertShape(z)),
+    execute: async (args: AlertArgs) => ({ result: await runAlert(client, args, defaults) }),
+  }) as M91MastraTool;
+}
+
+/** Both tools, keyed for an `Agent`'s `tools` object. */
+export async function createM91Tools(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<Record<string, M91MastraTool>> {
+  return {
+    [APPROVAL_TOOL_NAME]: await createM91ApprovalTool(client, defaults),
+    [ALERT_TOOL_NAME]: await createM91AlertTool(client, defaults),
+  };
+}

package/src/integrations/openai-agents.ts

@@ -0,0 +1,173 @@
+/**
+ * OpenAI Agents SDK (`@openai/agents`): two tools, and M91 as the approver.
+ *
+ * **Approver.** Mark your risky tools `needsApproval: true`. The SDK pauses the
+ * run and returns `result.interruptions`; `runWithM91Approvals` rings a phone
+ * for each one, approves or rejects it on the run state with the person's
+ * answer, and resumes the same run until it finishes.
+ *
+ * ```ts
+ * import { Agent, tool } from '@openai/agents';
+ * import { M91Client } from '@msg91comm/m91';
+ * import { runWithM91Approvals } from '@msg91comm/m91/integrations/openai-agents';
+ *
+ * const issueRefund = tool({
+ *   name: 'issue_refund',
+ *   description: 'Refund an order.',
+ *   parameters: z.object({ orderId: z.string(), amount: z.number() }),
+ *   needsApproval: true,
+ *   execute: async ({ orderId, amount }) => refunds.create(orderId, amount),
+ * });
+ *
+ * const agent = new Agent({ name: 'Support', instructions: '…', tools: [issueRefund] });
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ *
+ * const result = await runWithM91Approvals(agent, 'Refund ORD-40122, it never arrived.', client);
+ * console.log(result.finalOutput);
+ * ```
+ *
+ * **Tools** (`createM91Tools`) are for when the model itself should decide to
+ * ask, or to wake somebody about something that happened.
+ *
+ * `@openai/agents` is an optional peer dependency, imported only when one of
+ * these is called.
+ */
+
+import type { Agent, FunctionTool, RunResult, RunState, RunToolApprovalItem } from '@openai/agents';
+
+import type { M91Client } from '../client.js';
+import {
+  ALERT_DESCRIPTION,
+  ALERT_SCHEMA,
+  ALERT_TOOL_NAME,
+  APPROVAL_DESCRIPTION,
+  APPROVAL_SCHEMA,
+  APPROVAL_TOOL_NAME,
+  type AlertArgs,
+  type AlertDefaults,
+  type ApprovalArgs,
+  type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
+  needsHuman,
+  runAlert,
+  runApproval,
+} from './specs.js';
+
+interface AgentsModule {
+  tool: (options: unknown) => unknown;
+  run: (agent: unknown, input: unknown, options?: unknown) => Promise<unknown>;
+}
+
+async function agentsModule(): Promise<AgentsModule> {
+  try {
+    const specifier = '@openai/agents';
+    return (await import(specifier)) as unknown as AgentsModule;
+  } catch (error) {
+    throw new Error(
+      'The OpenAI Agents integration needs @openai/agents. Install it with: npm install @openai/agents',
+      { cause: error },
+    );
+  }
+}
+
+/** The blocking approval tool, `m91_request_approval`. Returns `"approved"`, `"rejected"` or `"error: …"`. */
+export async function createM91ApprovalTool(
+  client: M91Client,
+  defaults: ApprovalDefaults = {},
+): Promise<FunctionTool> {
+  const { tool } = await agentsModule();
+  return tool({
+    name: APPROVAL_TOOL_NAME,
+    description: APPROVAL_DESCRIPTION,
+    // JSON Schema with optional fields: the non-strict mode accepts it as is.
+    parameters: APPROVAL_SCHEMA,
+    strict: false,
+    execute: (args: ApprovalArgs) => runApproval(client, args, defaults),
+  }) as FunctionTool;
+}
+
+/** The fire-and-forget alert tool, `m91_send_alert`. Returns `"sent:delivered=N"` or `"error: …"`. */
+export async function createM91AlertTool(
+  client: M91Client,
+  defaults: AlertDefaults = {},
+): Promise<FunctionTool> {
+  const { tool } = await agentsModule();
+  return tool({
+    name: ALERT_TOOL_NAME,
+    description: ALERT_DESCRIPTION,
+    parameters: ALERT_SCHEMA,
+    strict: false,
+    execute: (args: AlertArgs) => runAlert(client, args, defaults),
+  }) as FunctionTool;
+}
+
+/** Both tools, for an agent's `tools` array. */
+export async function createM91Tools(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<FunctionTool[]> {
+  return [await createM91ApprovalTool(client, defaults), await createM91AlertTool(client, defaults)];
+}
+
+function parseArguments(item: RunToolApprovalItem): unknown {
+  const raw = item.arguments;
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function callIdOf(item: RunToolApprovalItem): string {
+  const raw = item.rawItem as { callId?: string; id?: string };
+  return raw.callId ?? raw.id ?? `${item.name ?? 'tool'}-${item.arguments ?? ''}`.slice(0, 60);
+}
+
+/**
+ * Ask a person about every pending approval on a paused run, and record the
+ * answers on its state. Returns how many were decided; resume with
+ * `run(agent, result.state)`.
+ *
+ * Interruptions for tools outside `options.tools` are left pending for your
+ * own code to decide.
+ */
+export async function approveInterruptionsWithM91(
+  result: Pick<RunResult<any, any>, 'interruptions' | 'state'>,
+  client: M91Client,
+  options: GateOptions = {},
+): Promise<number> {
+  const state = result.state as RunState<any, any>;
+  let decided = 0;
+  for (const item of result.interruptions ?? []) {
+    const toolName = item.name ?? 'tool';
+    const input = parseArguments(item);
+    if (!(await needsHuman(options, toolName, input))) continue;
+    const decision = await decideToolCall(client, { toolName, input, callId: callIdOf(item) }, options);
+    if (decision.approved) state.approve(item);
+    else state.reject(item, { message: decision.reason });
+    decided += 1;
+  }
+  return decided;
+}
+
+/**
+ * `run()`, with every approval the run pauses for answered on a phone through
+ * M91, until the run finishes or nothing left to decide is M91's.
+ */
+export async function runWithM91Approvals<TAgent extends Agent<any, any>>(
+  agent: TAgent,
+  input: string | Parameters<typeof import('@openai/agents').run>[1],
+  client: M91Client,
+  options: GateOptions & { runOptions?: Record<string, unknown>; maxRounds?: number } = {},
+): Promise<RunResult<any, TAgent>> {
+  const { run } = await agentsModule();
+  const { runOptions, maxRounds = 20, ...gate } = options;
+  let result = (await run(agent, input, runOptions)) as RunResult<any, TAgent>;
+  for (let round = 0; round < maxRounds && (result.interruptions?.length ?? 0) > 0; round += 1) {
+    if ((await approveInterruptionsWithM91(result, client, gate)) === 0) break;
+    result = (await run(agent, result.state, runOptions)) as RunResult<any, TAgent>;
+  }
+  return result;
+}