@msg91comm/m91 0.0.0-stage → 1.2.0

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/langchain-agent.ts

@@ -0,0 +1,65 @@
+/**
+ * A LangChain agent that has to ask before it spends money.
+ *
+ * The interesting part is not the wiring — it is the system prompt. A tool the
+ * model *can* call is not a tool the model *will* call, and "ask a human before
+ * anything irreversible" has to be stated as a rule with a list, not implied.
+ */
+
+import { ChatAnthropic } from '@langchain/anthropic';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91AlertTool, createM91ApprovalTool } from '@msg91comm/m91/integrations/langchain';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const tools = [
+  await createM91ApprovalTool(client), // blocks until a human answers
+  await createM91AlertTool(client), // wakes somebody and carries on
+  // ...your own tools: issueRefund, deploy, deleteAccount, and so on.
+];
+
+const SYSTEM = `You are an operations agent with access to production systems.
+
+Before ANY of the following, you must call m91_request_approval and wait for the
+answer:
+  - moving money: refunds, payouts, charges, credits
+  - deleting or overwriting anything a customer owns
+  - deploying, rolling back, or changing production configuration
+  - sending a message to a customer on the company's behalf
+
+Rules for that call:
+  - \`title\` is what somebody reads on a lock screen at 3am. Name the action and
+    the amount or the target: "Refund 48,000 on ORD-40122?" — not "approve action".
+  - \`description\` is everything they need to answer without asking you anything.
+  - \`customId\` is derived from the thing being decided — the order id, the
+    commit sha, the account id. Never a timestamp, never a UUID: it is what
+    stops a retry raising a second alert, and what closes the alert afterwards.
+  - The result is "approved" or "rejected". If it is not exactly "approved",
+    do not do the thing. Say what you were going to do and stop.
+
+Use m91_send_alert, which does not wait, when something has already gone wrong
+and a human needs to know now — a failed job, a breach, a stuck queue. Do not
+use it for anything that could wait until morning: it wakes people up.`;
+
+const agent = createReactAgent({
+  llm: new ChatAnthropic({ model: 'claude-sonnet-5' }),
+  tools,
+  prompt: SYSTEM,
+});
+
+// The agent pauses here — a phone rings, somebody taps Approve or Reject, and
+// the run continues with their answer in the transcript.
+const result = await agent.invoke({
+  messages: [
+    {
+      role: 'user',
+      content:
+        'Customer on order ORD-40122 says their item never arrived. ' +
+        'Look into it and refund them if it checks out.',
+    },
+  ],
+});
+
+console.log(result.messages.at(-1)?.content);

package/examples/langgraph-hitl.ts

@@ -0,0 +1,70 @@
+/**
+ * LangGraph's `interrupt()` pattern, with M91 filling the gap.
+ *
+ * LangGraph 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 is the part between the pause and the resume.
+ */
+
+import { Annotation, Command, END, MemorySaver, START, StateGraph, interrupt } from '@langchain/langgraph';
+
+import { M91Client } from '@msg91comm/m91';
+import { M91InterruptNotifier } from '@msg91comm/m91/integrations/langgraph';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+const notifier = new M91InterruptNotifier(client, { severity: 'HIGH', timeoutMs: 600_000 });
+
+const State = Annotation.Root({
+  id: Annotation<string>,
+  amount: Annotation<number>,
+  result: Annotation<string>,
+});
+
+const builder = new StateGraph(State)
+  .addNode('riskyAction', (state) => {
+    if (state.amount > 10_000) {
+      // The graph stops here and hands the payload out to the orchestrator.
+      const decision = interrupt({
+        question: `Approve payment of ₹${state.amount.toLocaleString()} on order ${state.id}?`,
+        customId: `payment-${state.id}`,
+      });
+      if (decision !== 'approved') return { result: 'payment_rejected' };
+    }
+    // await executePayment(state);
+    return { result: 'payment_completed' };
+  })
+  .addEdge(START, 'riskyAction')
+  .addEdge('riskyAction', END);
+
+const graph = builder.compile({ checkpointer: new MemorySaver() });
+const config = { configurable: { thread_id: 'order-40122' } };
+
+let result = await graph.invoke({ id: 'ORD-40122', amount: 48_000 }, config);
+
+if (result.__interrupt__) {
+  const data = result.__interrupt__[0].value as { question: string; customId: string };
+
+  // A phone rings at full volume, through Do Not Disturb, until somebody
+  // answers — and gets a voice call if 45 seconds pass in silence.
+  const decision = await notifier.notify({
+    title: data.question,
+    customId: data.customId, // the graph chose it, and it is stable
+  });
+
+  result = await graph.invoke(new Command({ resume: decision }), config);
+}
+
+console.log(result.result);
+
+// The same thing as a node, when you would rather the graph own it:
+//
+//   import { createM91ApprovalNode } from '@msg91comm/m91/integrations/langgraph';
+//   builder.addNode('approveRefund', createM91ApprovalNode(client, {
+//     approveLabel: 'Process Refund', rejectLabel: 'Hold Refund', timeoutMs: 600_000,
+//   }));
+//
+// It reads `title`/`question` and `customId` from state, and writes
+// { decision, approved } back for the next edge to branch on.

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/vercel-ai-agent.ts

@@ -0,0 +1,34 @@
+/**
+ * An agent on the Vercel AI SDK that asks before it deletes anything.
+ */
+
+import { openai } from '@ai-sdk/openai';
+import { generateText, stepCountIs } from 'ai';
+
+import { M91Client } from '@msg91comm/m91';
+import { createM91AlertTool, createM91ApprovalTool } from '@msg91comm/m91/integrations/vercel-ai';
+
+const client = new M91Client(process.env.M91_SEND_LINK!);
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  system:
+    'You are an operations agent. Before anything irreversible — deleting customer ' +
+    'data, moving money, deploying to production — you must call m91_request_approval ' +
+    'and wait. Give it a title naming the action and its target, a description with ' +
+    'everything the person needs to decide, and a customId derived from what is being ' +
+    'decided (never a timestamp). Proceed only on exactly "approved". ' +
+    'Use m91_send_alert, which does not wait, to report something that has already ' +
+    'gone wrong and needs somebody now.',
+  tools: {
+    m91_request_approval: await createM91ApprovalTool(client),
+    m91_send_alert: await createM91AlertTool(client),
+    // ...your own tools
+  },
+  stopWhen: stepCountIs(10),
+  prompt:
+    'Account acct_8821 has asked to be deleted under GDPR. Verify the request and, ' +
+    'if it is valid, delete the account.',
+});
+
+console.log(text);

package/examples/webhook-urls.ts

@@ -0,0 +1,44 @@
+/**
+ * Alert URLs for tools whose only integration field is "URL to call".
+ *
+ * Grafana, Sentry, UptimeRobot, Zapier, a GitHub Action, a cron `curl`, an iOS
+ * Shortcut, a browser bookmark, an `<img>` tag in a status page. No client, no
+ * headers, no code — which is the point: this is the difference between M91
+ * being wired into something this afternoon and being wired in never.
+ */
+
+import { M91URLBuilder } from '@msg91comm/m91';
+
+const builder = new M91URLBuilder(process.env.M91_SEND_LINK!);
+
+// Paste this into Grafana's webhook URL field.
+console.log(
+  builder.build('CPU above 95% on prod-server-3', {
+    severity: 'HIGH',
+    customId: 'cpu-high-prod3',
+    // First label is SHARED — one person takes it on and it clears for the rest.
+    // The others are PERSONAL: an acknowledgement that leaves it looking for an owner.
+    respond: ['On it', 'Escalate'],
+  }),
+);
+
+// The bare link. Opening it RAISES NOTHING and answers with the channel's name,
+// so whoever is pasting it can see they picked the right team. That is also why
+// a link preview, a crawler or a mail scanner touching the URL wakes nobody.
+console.log(builder.testUrl());
+
+// A batch, for generating a dashboard's worth at once.
+for (const url of builder.buildMany([
+  { title: 'Disk above 90% on prod-3', customId: 'disk-high-prod3', severity: 'MEDIUM' },
+  { title: 'Certificate expires in 48 hours', customId: 'cert-expiry', severity: 'LOW' },
+  { title: 'Payment gateway unreachable', customId: 'gateway-down', severity: 'CRITICAL' },
+])) {
+  console.log(url);
+}
+
+// In a crontab, where there is no Node at all:
+//
+//   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,6 +1,137 @@
 {
   "name": "@msg91comm/m91",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "keywords": [
+    "alerting",
+    "on-call",
+    "paging",
+    "human-in-the-loop",
+    "agent",
+    "approval",
+    "escalation",
+    "langchain",
+    "langgraph",
+    "langchainjs",
+    "vercel-ai",
+    "ai-sdk",
+    "openai-agents",
+    "claude-agent-sdk",
+    "google-adk",
+    "mastra",
+    "tool-approval"
+  ],
+  "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": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./integrations/langchain": {
+      "types": "./dist/src/integrations/langchain.d.ts",
+      "default": "./dist/src/integrations/langchain.js"
+    },
+    "./integrations/langgraph": {
+      "types": "./dist/src/integrations/langgraph.d.ts",
+      "default": "./dist/src/integrations/langgraph.js"
+    },
+    "./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": [
+    "dist/src",
+    "src",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/tests/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "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",
+    "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",
+    "@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
+    },
+    "zod": {
+      "optional": true
+    }
+  }
+}