@msg91comm/m91 1.1.0 → 1.2.0

package/src/integrations/langchain.ts

@@ -17,7 +17,7 @@
  *   await createM91AlertTool(client),
  *   ...myTools,
  * ];
- * const agent = createReactAgent({ llm, tools });
+ * const agent = createAgent({ model: 'openai:gpt-5-mini', tools });  // from 'langchain'
  * ```
  *
  * The factories are **async** because `@langchain/core` is an optional peer
@@ -26,6 +26,8 @@
  * to work when everything else is on fire.
  */
 
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+
 import type { M91Client } from '../client.js';
 import {
   ALERT_DESCRIPTION,
@@ -38,6 +40,8 @@ import {
   type AlertDefaults,
   type ApprovalArgs,
   type ApprovalDefaults,
+  type GateOptions,
+  decideToolCall,
   runAlert,
   runApproval,
 } from './specs.js';
@@ -67,13 +71,13 @@ async function langchainTool(): Promise<(fn: unknown, config: unknown) => unknow
 export async function createM91ApprovalTool(
   client: M91Client,
   defaults: ApprovalDefaults = {},
-): Promise<unknown> {
+): 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;
 }
 
 /**
@@ -83,22 +87,121 @@ export async function createM91ApprovalTool(
 export async function createM91AlertTool(
   client: M91Client,
   defaults: AlertDefaults = {},
-): Promise<unknown> {
+): 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<unknown[]> {
+): 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/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;
+}

package/src/integrations/specs.ts

@@ -222,3 +222,107 @@ export async function runAlert(
     return errorResult(error);
   }
 }
+
+/* ------------------------------------------------------------------------ */
+/* Gating a framework's own tool calls                                       */
+/* ------------------------------------------------------------------------ */
+
+/**
+ * One tool call a framework is about to make, in the only three fields every
+ * framework agrees on.
+ */
+export interface GatedCall {
+  toolName: string;
+  input: unknown;
+  /** The framework's id for this call. Becomes the alert's customId. */
+  callId: string;
+}
+
+/** How a gate decides who gets asked, and how the question reads. */
+export interface GateOptions extends ApprovalDefaults {
+  /**
+   * Which tool calls need a human: a list of tool names, or a predicate.
+   *
+   * Required where a framework routes every call through the gate (Claude
+   * Agent SDK, Google ADK, Vercel `toolApproval`): ringing somebody's phone
+   * for every file read is how a channel gets muted.
+   */
+  tools?: readonly string[] | ((toolName: string, input: unknown) => boolean | Promise<boolean>);
+  /** Write the lock-screen question yourself. Default: "Allow <tool>?" plus the arguments. */
+  describe?: (call: GatedCall) => { title: string; description?: string };
+}
+
+export interface GateDecision {
+  approved: boolean;
+  /** Why, in words a model can repeat to the user. */
+  reason: string;
+}
+
+/** Does this call need a human? With no `tools`, every call that reaches the gate does. */
+export async function needsHuman(
+  options: GateOptions,
+  toolName: string,
+  input: unknown,
+): Promise<boolean> {
+  const { tools } = options;
+  if (tools === undefined) return true;
+  if (typeof tools === 'function') return Boolean(await tools(toolName, input));
+  return tools.includes(toolName);
+}
+
+/** A customId M91 accepts, stable across a framework's retries of the same call. */
+export function gateCustomId(call: GatedCall): string {
+  const raw = `tool-${call.toolName}-${call.callId}`;
+  return raw.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 100);
+}
+
+function defaultQuestion(call: GatedCall): { title: string; description: string } {
+  let args: string;
+  try {
+    args = JSON.stringify(call.input, null, 2) ?? '';
+  } catch {
+    args = String(call.input);
+  }
+  if (args.length > 1500) args = `${args.slice(0, 1500)}\n… (truncated)`;
+  return {
+    title: `Allow the agent to run ${call.toolName}?`,
+    description: `The agent wants to call ${call.toolName} with:\n${args}`,
+  };
+}
+
+/**
+ * Ring a phone about a tool call and wait for the answer.
+ *
+ * Fails closed: an M91 error, an unreachable channel or a timeout is a no,
+ * with the reason spelled out, never a silent yes.
+ */
+export async function decideToolCall(
+  client: M91Client,
+  call: GatedCall,
+  options: GateOptions = {},
+): Promise<GateDecision> {
+  const question = options.describe ? options.describe(call) : defaultQuestion(call);
+  try {
+    const approved = await client.requestApproval(question.title, {
+      customId: gateCustomId(call),
+      description: question.description,
+      severity: options.severity ?? 'HIGH',
+      approveLabel: options.approveLabel ?? 'Approve',
+      rejectLabel: options.rejectLabel ?? 'Reject',
+      timeoutMs: (options.timeoutSeconds ?? 300) * 1000,
+    });
+    return approved
+      ? { approved: true, reason: 'Approved by a human via M91.' }
+      : {
+          approved: false,
+          reason:
+            'A human rejected this action via M91 (or did not answer in time). ' +
+            'Do not retry it; tell the user it was not approved.',
+        };
+  } catch (error) {
+    return {
+      approved: false,
+      reason: `Could not get human approval via M91, so the action was not run. ${errorResult(error)}`,
+    };
+  }
+}