@msg91comm/m91 1.1.0 → 1.2.0

package/examples/claude-agent-sdk.ts

@@ -0,0 +1,23 @@
+/**
+ * A Claude agent that can read anything, but rings a phone before it runs a
+ * shell command or writes a file.
+ *
+ *   M91_SEND_LINK=... ANTHROPIC_API_KEY=... npx tsx examples/claude-agent-sdk.ts
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91CanUseTool, createM91McpServer } from '@msg91comm/m91/integrations/claude-agent-sdk';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+for await (const message of query({
+  prompt: 'Find the feature branches merged more than 30 days ago and delete them.',
+  options: {
+    canUseTool: createM91CanUseTool(client, { tools: ['Bash', 'Write', 'Edit'] }),
+    mcpServers: { m91: await createM91McpServer(client) },
+  },
+})) {
+  if (message.type === 'result') console.log(message);
+}

package/examples/deep-agents.ts

@@ -0,0 +1,31 @@
+/**
+ * A Deep Agent that can plan and research on its own, but rings a phone before
+ * it writes files or runs shell commands.
+ *
+ *   M91_SEND_LINK=... ANTHROPIC_API_KEY=... npx tsx examples/deep-agents.ts
+ */
+
+import { MemorySaver } from '@langchain/langgraph';
+import { createDeepAgent } from 'deepagents';
+
+import { M91Client } from '@msg91comm/m91';
+import { invokeWithM91Approvals } from '@msg91comm/m91/integrations/langchain';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const agent = createDeepAgent({
+  model: 'anthropic:claude-sonnet-4-5',
+  systemPrompt: 'You are a release engineer.',
+  // These tools pause the run; invokeWithM91Approvals rings a phone for each.
+  interruptOn: { write_file: true, edit_file: true, execute: true },
+  checkpointer: new MemorySaver(),
+});
+
+const result = await invokeWithM91Approvals(
+  agent,
+  { messages: [{ role: 'user', content: 'Write the release notes for v2.4 to RELEASE.md.' }] },
+  { configurable: { thread_id: 'release-v2.4' } },
+  client,
+  { timeoutSeconds: 600 },
+);
+console.log(result.messages.at(-1)?.content);

package/examples/google-adk.ts

@@ -0,0 +1,39 @@
+/**
+ * A Google ADK agent whose refunds ring a phone before they run.
+ *
+ *   M91_SEND_LINK=... GOOGLE_GENAI_API_KEY=... npx tsx examples/google-adk.ts
+ */
+
+import { FunctionTool, InMemoryRunner, LlmAgent } from '@google/adk';
+import { z } from 'zod';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91BeforeToolCallback } from '@msg91comm/m91/integrations/google-adk';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const issueRefund = new FunctionTool({
+  name: 'issue_refund',
+  description: 'Refund an order to the original payment method.',
+  parameters: z.object({ orderId: z.string(), amountInr: z.number() }),
+  execute: async ({ orderId, amountInr }) => ({ status: 'refunded', orderId, amountInr }),
+});
+
+const agent = new LlmAgent({
+  name: 'support_agent',
+  model: 'gemini-2.5-flash',
+  instruction: 'Resolve refund requests. If a refund is rejected, tell the customer why.',
+  tools: [issueRefund],
+  beforeToolCallback: createM91BeforeToolCallback(client, { tools: ['issue_refund'] }),
+});
+
+const runner = new InMemoryRunner({ agent, appName: 'm91-example' });
+const session = await runner.sessionService.createSession({ appName: 'm91-example', userId: 'u1' });
+for await (const event of runner.runAsync({
+  userId: 'u1',
+  sessionId: session.id,
+  newMessage: { role: 'user', parts: [{ text: 'Order ORD-40122 never arrived. Refund 4,800 INR.' }] },
+})) {
+  const text = event.content?.parts?.map((p) => p.text ?? '').join('');
+  if (text) console.log(text);
+}

package/examples/mastra.ts

@@ -0,0 +1,41 @@
+/**
+ * A Mastra agent whose refunds need a person's approval, by phone.
+ *
+ *   M91_SEND_LINK=... OPENAI_API_KEY=... npx tsx examples/mastra.ts
+ */
+
+import { Mastra } from '@mastra/core';
+import { Agent } from '@mastra/core/agent';
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+import { M91Client } from '@msg91comm/m91';
+import { generateWithM91Approvals } from '@msg91comm/m91/integrations/mastra';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const issueRefund = createTool({
+  id: 'issue-refund',
+  description: 'Refund an order to the original payment method.',
+  inputSchema: z.object({ orderId: z.string(), amountInr: z.number() }),
+  requireApproval: true,
+  execute: async ({ orderId, amountInr }) => ({ status: 'refunded', orderId, amountInr }),
+});
+
+const support = new Agent({
+  id: 'support',
+  name: 'Support',
+  instructions: 'Resolve refund requests. If a refund is declined, tell the customer why.',
+  model: 'openai/gpt-5-mini',
+  tools: { issueRefund },
+});
+
+// Suspended runs live in Mastra's storage: add a storage provider here in production.
+const mastra = new Mastra({ agents: { support } });
+
+const output = await generateWithM91Approvals(
+  mastra.getAgent('support'),
+  'Order ORD-40122 never arrived. Refund 4,800 INR.',
+  client,
+);
+console.log(output.text);

package/examples/openai-agents.ts

@@ -0,0 +1,33 @@
+/**
+ * An OpenAI Agents SDK agent whose refunds need a person's approval, by phone.
+ *
+ *   M91_SEND_LINK=... OPENAI_API_KEY=... npx tsx examples/openai-agents.ts
+ */
+
+import { Agent, tool } from '@openai/agents';
+import { z } from 'zod';
+
+import { M91Client } from '@msg91comm/m91';
+import { runWithM91Approvals } from '@msg91comm/m91/integrations/openai-agents';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const issueRefund = tool({
+  name: 'issue_refund',
+  description: 'Refund an order to the original payment method.',
+  parameters: z.object({ orderId: z.string(), amountInr: z.number() }),
+  // The SDK pauses here; runWithM91Approvals rings a phone and resumes.
+  needsApproval: true,
+  execute: async ({ orderId, amountInr }) => `Refunded ${amountInr} INR on ${orderId}.`,
+});
+
+const agent = new Agent({
+  name: 'Support',
+  instructions: 'Resolve refund requests. If a refund is not approved, tell the customer why.',
+  tools: [issueRefund],
+});
+
+const result = await runWithM91Approvals(agent, 'Order ORD-40122 never arrived. Refund 4,800 INR.', client, {
+  timeoutSeconds: 600,
+});
+console.log(result.finalOutput);

package/examples/webhook-urls.ts

@@ -38,7 +38,7 @@ for (const url of builder.buildMany([
 
 // In a crontab, where there is no Node at all:
 //
-//   0 9 * * * curl -fsS "https://m91.msg91.com/s/TOKEN?title=Daily+backup+did+not+run&severity=HIGH"
+//   0 9 * * * curl -fsS "https://m91-api.msg91.com/s/TOKEN?title=Daily+backup+did+not+run&severity=HIGH"
 //
 // The URL contains the token, so it is a credential. Keep it out of anything
 // public, and out of anything that ends up in a screenshot.

package/package.json

@@ -1,13 +1,10 @@
 {
   "name": "@msg91comm/m91",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Critical alerting and human-in-the-loop approval for AI agents and on-call systems",
   "type": "module",
   "license": "MIT",
   "author": "MSG91",
-  "publishConfig": {
-    "access": "public"
-  },
   "keywords": [
     "alerting",
     "on-call",
@@ -15,11 +12,26 @@
     "human-in-the-loop",
     "agent",
     "approval",
-    "escalation"
+    "escalation",
+    "langchain",
+    "langgraph",
+    "langchainjs",
+    "vercel-ai",
+    "ai-sdk",
+    "openai-agents",
+    "claude-agent-sdk",
+    "google-adk",
+    "mastra",
+    "tool-approval"
   ],
-  "homepage": "https://m91.msg91.com",
-  "repository": { "type": "git", "url": "git+https://github.com/MSG91/m91-sdk.git" },
-  "bugs": { "url": "https://github.com/MSG91/m91-sdk/issues" },
+  "homepage": "https://m91-api.msg91.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MSG91/m91-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MSG91/m91-sdk/issues"
+  },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
@@ -39,6 +51,22 @@
     "./integrations/vercel-ai": {
       "types": "./dist/src/integrations/vercel-ai.d.ts",
       "default": "./dist/src/integrations/vercel-ai.js"
+    },
+    "./integrations/openai-agents": {
+      "types": "./dist/src/integrations/openai-agents.d.ts",
+      "default": "./dist/src/integrations/openai-agents.js"
+    },
+    "./integrations/claude-agent-sdk": {
+      "types": "./dist/src/integrations/claude-agent-sdk.d.ts",
+      "default": "./dist/src/integrations/claude-agent-sdk.js"
+    },
+    "./integrations/google-adk": {
+      "types": "./dist/src/integrations/google-adk.d.ts",
+      "default": "./dist/src/integrations/google-adk.js"
+    },
+    "./integrations/mastra": {
+      "types": "./dist/src/integrations/mastra.d.ts",
+      "default": "./dist/src/integrations/mastra.js"
     }
   },
   "files": [
@@ -57,24 +85,48 @@
     "test": "tsc && node --test dist/tests/*.test.js",
     "prepublishOnly": "npm run build"
   },
-  "dependencies": {},
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.308",
+    "@google/adk": "^2.3.0",
+    "@langchain/core": "^1.2.20",
+    "@mastra/core": "^1.79.0",
+    "@openai/agents": "^0.21.0",
     "@types/node": "^22.0.0",
-    "typescript": "^5.4.0"
+    "ai": "^7.0.148",
+    "deepagents": "^1.15.1",
+    "langchain": "^1.5.18",
+    "typescript": "^5.4.0",
+    "zod": "^4.6.7"
   },
   "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.3.0",
+    "@google/adk": ">=2.3.0",
     "@langchain/core": ">=0.2.0",
     "@langchain/langgraph": ">=0.2.0",
-    "ai": ">=3.0.0",
+    "@mastra/core": ">=1.79.0",
+    "@openai/agents": ">=0.21.0",
+    "ai": ">=5.0.0",
     "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@google/adk": {
+      "optional": true
+    },
     "@langchain/core": {
       "optional": true
     },
     "@langchain/langgraph": {
       "optional": true
     },
+    "@mastra/core": {
+      "optional": true
+    },
+    "@openai/agents": {
+      "optional": true
+    },
     "ai": {
       "optional": true
     },

package/src/index.ts

@@ -88,4 +88,4 @@ export type {
  * written twice — and it drifted, reporting 1.0.0 while the package shipped as
  * 1.1.0. A test is what makes two copies safe.
  */
-export const VERSION = '1.1.0';
+export const VERSION = '1.2.0';

package/src/integrations/claude-agent-sdk.ts

@@ -0,0 +1,158 @@
+/**
+ * Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`): M91 as the permission
+ * prompt, and M91 as tools.
+ *
+ * **Permission prompt.** `createM91CanUseTool` is a `canUseTool` callback: the
+ * tools you name ring a phone and run only if a person approves. Everything
+ * else is allowed through untouched.
+ *
+ * ```ts
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ * import { M91Client } from '@msg91comm/m91';
+ * import { createM91CanUseTool } from '@msg91comm/m91/integrations/claude-agent-sdk';
+ *
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ *
+ * for await (const message of query({
+ *   prompt: 'Clean up the stale feature branches and deploy main.',
+ *   options: { canUseTool: createM91CanUseTool(client, { tools: ['Bash', 'Write'] }) },
+ * })) {
+ *   if (message.type === 'result') console.log(message);
+ * }
+ * ```
+ *
+ * `canUseTool` only runs when the SDK would otherwise ask. To gate a tool
+ * whatever the permission mode (including `bypassPermissions`), use the
+ * `PreToolUse` hook from `createM91PreToolUseHook` instead.
+ *
+ * **Tools.** `createM91McpServer` exposes `m91_request_approval` and
+ * `m91_send_alert` as an in-process MCP server, for when the agent itself
+ * should decide to ask or to wake somebody.
+ */
+
+import type {
+  CanUseTool,
+  HookCallbackMatcher,
+  McpSdkServerConfigWithInstance,
+  PermissionResult,
+} from '@anthropic-ai/claude-agent-sdk';
+
+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';
+
+/** Tool names, or a predicate. Required: an agent that rings for every `Read` gets muted. */
+type ClaudeGateOptions = GateOptions & { tools: NonNullable<GateOptions['tools']> };
+
+/**
+ * A `canUseTool` callback that asks a person on their phone before the tools
+ * in `options.tools` run.
+ */
+export function createM91CanUseTool(client: M91Client, options: ClaudeGateOptions): CanUseTool {
+  return async (toolName, input, { toolUseID }): Promise<PermissionResult> => {
+    if (!(await needsHuman(options, toolName, input))) {
+      return { behavior: 'allow', updatedInput: input };
+    }
+    const decision = await decideToolCall(client, { toolName, input, callId: toolUseID }, options);
+    return decision.approved
+      ? { behavior: 'allow', updatedInput: input }
+      : { behavior: 'deny', message: decision.reason };
+  };
+}
+
+/**
+ * A `PreToolUse` hook matcher that asks a person before the tools in
+ * `options.tools` run, in every permission mode. Pass it as
+ * `options.hooks.PreToolUse`.
+ *
+ * ```ts
+ * query({ prompt, options: { hooks: { PreToolUse: createM91PreToolUseHook(client, { tools: ['Bash'] }) } } })
+ * ```
+ */
+export function createM91PreToolUseHook(
+  client: M91Client,
+  options: ClaudeGateOptions & { timeoutSeconds?: number },
+): HookCallbackMatcher[] {
+  return [
+    {
+      // The hook must outlive the wait for a human, or the SDK gives up first.
+      timeout: (options.timeoutSeconds ?? 300) + 60,
+      hooks: [
+        async (input) => {
+          if (input.hook_event_name !== 'PreToolUse') return {};
+          if (!(await needsHuman(options, input.tool_name, input.tool_input))) return {};
+          const decision = await decideToolCall(
+            client,
+            { toolName: input.tool_name, input: input.tool_input, callId: input.tool_use_id },
+            options,
+          );
+          return {
+            hookSpecificOutput: {
+              hookEventName: 'PreToolUse',
+              permissionDecision: decision.approved ? 'allow' : 'deny',
+              permissionDecisionReason: decision.reason,
+            },
+          };
+        },
+      ],
+    },
+  ];
+}
+
+interface ClaudeSdkModule {
+  tool: (name: string, description: string, shape: unknown, handler: unknown) => unknown;
+  createSdkMcpServer: (options: { name: string; version?: string; tools: unknown[] }) => unknown;
+}
+
+async function claudeSdk(): Promise<ClaudeSdkModule> {
+  try {
+    const specifier = '@anthropic-ai/claude-agent-sdk';
+    return (await import(specifier)) as unknown as ClaudeSdkModule;
+  } catch (error) {
+    throw new Error(
+      'The Claude Agent SDK integration needs @anthropic-ai/claude-agent-sdk. Install it with: ' +
+        'npm install @anthropic-ai/claude-agent-sdk',
+      { cause: error },
+    );
+  }
+}
+
+const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }] });
+
+/**
+ * `m91_request_approval` and `m91_send_alert` as an in-process MCP server.
+ * Register it under `mcpServers.m91`; the tools appear to Claude as
+ * `mcp__m91__m91_request_approval` and `mcp__m91__m91_send_alert`.
+ */
+export async function createM91McpServer(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<McpSdkServerConfigWithInstance> {
+  const { tool, createSdkMcpServer } = await claudeSdk();
+  const z = await loadZod('Claude Agent SDK');
+  return createSdkMcpServer({
+    name: 'm91',
+    tools: [
+      tool(APPROVAL_TOOL_NAME, APPROVAL_DESCRIPTION, approvalShape(z), async (args: ApprovalArgs) =>
+        text(await runApproval(client, args, defaults)),
+      ),
+      tool(ALERT_TOOL_NAME, ALERT_DESCRIPTION, alertShape(z), async (args: AlertArgs) =>
+        text(await runAlert(client, args, defaults)),
+      ),
+    ],
+  }) as McpSdkServerConfigWithInstance;
+}

package/src/integrations/google-adk.ts

@@ -0,0 +1,122 @@
+/**
+ * Google Agent Development Kit for TypeScript (`@google/adk`): M91 as a
+ * before-tool gate, and M91 as tools.
+ *
+ * **Gate.** `createM91BeforeToolCallback` goes in an `LlmAgent`'s
+ * `beforeToolCallback`. Calls to the tools you name ring a phone first; if the
+ * person rejects (or does not answer), the tool does not run and the agent
+ * gets the reason back as the tool's result.
+ *
+ * ```ts
+ * import { LlmAgent } from '@google/adk';
+ * import { M91Client } from '@msg91comm/m91';
+ * import { createM91BeforeToolCallback, createM91Tools } from '@msg91comm/m91/integrations/google-adk';
+ *
+ * const client = new M91Client(process.env.M91_SEND_LINK!);
+ *
+ * const agent = new LlmAgent({
+ *   name: 'support_agent',
+ *   model: 'gemini-2.5-flash',
+ *   instruction: 'Resolve refund requests.',
+ *   tools: [issueRefund, ...(await createM91Tools(client))],
+ *   beforeToolCallback: createM91BeforeToolCallback(client, { tools: ['issue_refund'] }),
+ * });
+ * ```
+ *
+ * The gate waits for the answer in-process. For approvals that take hours,
+ * use ADK's own Tool Confirmation and resume the session when M91's answer
+ * arrives.
+ */
+
+import type { BaseTool, FunctionTool, SingleBeforeToolCallback } from '@google/adk';
+
+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';
+
+/**
+ * A `beforeToolCallback` that asks a person on their phone before the tools
+ * in `options.tools` run. Returning a result object skips the tool, which is
+ * how a rejection reaches the model.
+ */
+export function createM91BeforeToolCallback(
+  client: M91Client,
+  options: GateOptions & { tools: NonNullable<GateOptions['tools']> },
+): SingleBeforeToolCallback {
+  return async ({ tool, args, context }) => {
+    const toolName = tool.name;
+    if (!(await needsHuman(options, toolName, args))) return undefined;
+    const callId = context.functionCallId ?? `${context.invocationId}-${toolName}`;
+    const decision = await decideToolCall(client, { toolName, input: args, callId }, options);
+    if (decision.approved) return undefined;
+    return { status: 'rejected', error: decision.reason };
+  };
+}
+
+interface AdkModule {
+  FunctionTool: new (options: unknown) => FunctionTool<any>;
+}
+
+async function adkModule(): Promise<AdkModule> {
+  try {
+    const specifier = '@google/adk';
+    return (await import(specifier)) as unknown as AdkModule;
+  } catch (error) {
+    throw new Error(
+      'The Google ADK integration needs @google/adk. Install it with: npm install @google/adk',
+      { cause: error },
+    );
+  }
+}
+
+/** The blocking approval tool, `m91_request_approval`, as an ADK `FunctionTool`. */
+export async function createM91ApprovalTool(
+  client: M91Client,
+  defaults: ApprovalDefaults = {},
+): Promise<BaseTool> {
+  const { FunctionTool } = await adkModule();
+  const z = await loadZod('Google ADK');
+  return new FunctionTool({
+    name: APPROVAL_TOOL_NAME,
+    description: APPROVAL_DESCRIPTION,
+    parameters: z.object(approvalShape(z)),
+    execute: async (args: ApprovalArgs) => ({ result: await runApproval(client, args, defaults) }),
+  });
+}
+
+/** The fire-and-forget alert tool, `m91_send_alert`, as an ADK `FunctionTool`. */
+export async function createM91AlertTool(
+  client: M91Client,
+  defaults: AlertDefaults = {},
+): Promise<BaseTool> {
+  const { FunctionTool } = await adkModule();
+  const z = await loadZod('Google ADK');
+  return new FunctionTool({
+    name: ALERT_TOOL_NAME,
+    description: ALERT_DESCRIPTION,
+    parameters: z.object(alertShape(z)),
+    execute: async (args: AlertArgs) => ({ result: await runAlert(client, args, defaults) }),
+  });
+}
+
+/** Both tools, for an agent's `tools` array. */
+export async function createM91Tools(
+  client: M91Client,
+  defaults: ApprovalDefaults & AlertDefaults = {},
+): Promise<BaseTool[]> {
+  return [await createM91ApprovalTool(client, defaults), await createM91AlertTool(client, defaults)];
+}

package/src/integrations/index.ts

@@ -8,7 +8,7 @@
  * Importing a specific adapter directly is usually better —
  * `@msg91comm/m91/integrations/langchain` — because it pulls in only what you use.
  *
- * `langchain.ts` and `vercel-ai.ts` both export `createM91ApprovalTool`, so
+ * Several adapters export `createM91ApprovalTool`, so
  * they are re-exported under namespaces rather than flattened: two functions of
  * the same name doing the same job for different frameworks is exactly the pair
  * that would silently resolve to the wrong one.
@@ -17,7 +17,11 @@
 export * as langchain from './langchain.js';
 export * as langgraph from './langgraph.js';
 export * as vercelAi from './vercel-ai.js';
+export * as openaiAgents from './openai-agents.js';
+export * as claudeAgentSdk from './claude-agent-sdk.js';
+export * as googleAdk from './google-adk.js';
+export * as mastra from './mastra.js';
 
 export { M91InterruptNotifier, createM91ApprovalNode } from './langgraph.js';
-export { APPROVED, REJECTED, alertResult, errorResult } from './specs.js';
-export type { AlertArgs, ApprovalArgs } from './specs.js';
+export { APPROVED, REJECTED, alertResult, decideToolCall, errorResult } from './specs.js';
+export type { AlertArgs, ApprovalArgs, GateDecision, GateOptions, GatedCall } from './specs.js';