@msg91comm/m91 0.0.0-stage → 1.2.0

package/dist/src/integrations/langgraph.js

@@ -0,0 +1,114 @@
+/**
+ * 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 { APPROVED, REJECTED } from './specs.js';
+/**
+ * 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 {
+    client;
+    defaults;
+    constructor(client, defaults = {}) {
+        this.client = client;
+        this.defaults = defaults;
+    }
+    async notify(options) {
+        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, defaults = {}) {
+    const notifier = new M91InterruptNotifier(client, defaults);
+    return async (state) => {
+        const data = (state && typeof state === 'object' ? state : {});
+        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,
+                severity: data.severity,
+                approveLabel: data.approveLabel,
+                rejectLabel: data.rejectLabel,
+                timeoutMs: data.timeoutMs,
+            }),
+        });
+        return { decision, approved: decision === APPROVED };
+    };
+}
+/** Drop undefined keys so a spread cannot blank out a default with `undefined`. */
+function strip(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+//# sourceMappingURL=langgraph.js.map

package/dist/src/integrations/langgraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langgraph.js","sourceRoot":"","sources":["../../../src/integrations/langgraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiBhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,oBAAoB;IACd,MAAM,CAAY;IAClB,QAAQ,CAAiB;IAE1C,YAAY,MAAiB,EAAE,WAA2B,EAAE;QAC1D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAsB;QACjC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAC7C,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE;gBACxD,QAAQ;gBACR,QAAQ,EAAE,MAAM;gBAChB,SAAS,EAAE,OAAO;gBAClB,GAAG,MAAM;aACV,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;YACrE,wEAAwE;YACxE,uBAAuB;YACvB,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,WAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE5D,OAAO,KAAK,EAAE,KAAc,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;QAC1F,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC;QAEjD,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACxB,yEAAyE;YACzE,uDAAuD;YACvD,OAAO;gBACL,QAAQ,EAAE,QAAQ;gBAClB,QAAQ,EAAE,KAAK;gBACf,KAAK,EACH,gFAAgF;aACnF,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;YACrC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;YACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;YAC1B,GAAG,KAAK,CAAC;gBACP,WAAW,EAAE,IAAI,CAAC,WAAiC;gBACnD,QAAQ,EAAE,IAAI,CAAC,QAAgC;gBAC/C,YAAY,EAAE,IAAI,CAAC,YAAkC;gBACrD,WAAW,EAAE,IAAI,CAAC,WAAiC;gBACnD,SAAS,EAAE,IAAI,CAAC,SAA+B;aAChD,CAAC;SACH,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,KAAK,QAAQ,EAAE,CAAC;IACvD,CAAC,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,SAAS,KAAK,CAAoC,KAAQ;IACxD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAe,CAAC;AACpG,CAAC"}

package/dist/src/integrations/mastra.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { type AlertDefaults, type ApprovalDefaults, type GateOptions } from './specs.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>;
+}
+/**
+ * `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 declare function generateWithM91Approvals<TOutput extends MastraOutputLike>(agent: MastraAgentLike<TOutput>, prompt: unknown, client: M91Client, options?: GateOptions & {
+    generateOptions?: Record<string, unknown>;
+    maxRounds?: number;
+}): Promise<TOutput>;
+/** 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 declare function createM91ApprovalTool(client: M91Client, defaults?: ApprovalDefaults): Promise<M91MastraTool>;
+/** The fire-and-forget alert tool, `m91_send_alert`, as a Mastra tool. */
+export declare function createM91AlertTool(client: M91Client, defaults?: AlertDefaults): Promise<M91MastraTool>;
+/** Both tools, keyed for an `Agent`'s `tools` object. */
+export declare function createM91Tools(client: M91Client, defaults?: ApprovalDefaults & AlertDefaults): Promise<Record<string, M91MastraTool>>;
+//# sourceMappingURL=mastra.d.ts.map

package/dist/src/integrations/mastra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra.d.ts","sourceRoot":"","sources":["../../../src/integrations/mastra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAML,KAAK,aAAa,EAElB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAGpB,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe,CAAC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IAClF,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,uBAAuB,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,uBAAuB,CAAC,OAAO,EAAE;QAC/B,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAeD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,SAAS,gBAAgB,EAC7E,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,EAC/B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAW,GAAG;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5F,OAAO,CAAC,OAAO,CAAC,CAqBlB;AAiBD,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;AAEvE,4EAA4E;AAC5E,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,QAAQ,GAAE,gBAAqB,GAC9B,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,0EAA0E;AAC1E,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,QAAQ,GAAE,aAAkB,GAC3B,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,yDAAyD;AACzD,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,EACjB,QAAQ,GAAE,gBAAgB,GAAG,aAAkB,GAC9C,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAKxC"}

package/dist/src/integrations/mastra.js

@@ -0,0 +1,109 @@
+/**
+ * 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 { ALERT_DESCRIPTION, ALERT_TOOL_NAME, APPROVAL_DESCRIPTION, APPROVAL_TOOL_NAME, decideToolCall, needsHuman, runAlert, runApproval, } from './specs.js';
+import { alertShape, approvalShape, loadZod } from './zod-shapes.js';
+function pendingApproval(output) {
+    if (output.finishReason !== 'suspended' || !output.runId)
+        return null;
+    const payload = output.suspendPayload;
+    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(agent, prompt, client, options = {}) {
+    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;
+        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;
+}
+async function mastraTools() {
+    try {
+        const specifier = '@mastra/core/tools';
+        return (await import(specifier));
+    }
+    catch (error) {
+        throw new Error('The Mastra integration needs @mastra/core. Install it with: npm install @mastra/core', {
+            cause: error,
+        });
+    }
+}
+/** The blocking approval tool, `m91_request_approval`, as a Mastra tool. */
+export async function createM91ApprovalTool(client, defaults = {}) {
+    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) => ({ result: await runApproval(client, args, defaults) }),
+    });
+}
+/** The fire-and-forget alert tool, `m91_send_alert`, as a Mastra tool. */
+export async function createM91AlertTool(client, defaults = {}) {
+    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) => ({ result: await runAlert(client, args, defaults) }),
+    });
+}
+/** Both tools, keyed for an `Agent`'s `tools` object. */
+export async function createM91Tools(client, defaults = {}) {
+    return {
+        [APPROVAL_TOOL_NAME]: await createM91ApprovalTool(client, defaults),
+        [ALERT_TOOL_NAME]: await createM91AlertTool(client, defaults),
+    };
+}
+//# sourceMappingURL=mastra.js.map

package/dist/src/integrations/mastra.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra.js","sourceRoot":"","sources":["../../../src/integrations/mastra.ts"],"names":[],"mappings":"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"}

package/dist/src/integrations/openai-agents.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 } from '@openai/agents';
+import type { M91Client } from '../client.js';
+import { type AlertDefaults, type ApprovalDefaults, type GateOptions } from './specs.js';
+/** The blocking approval tool, `m91_request_approval`. Returns `"approved"`, `"rejected"` or `"error: …"`. */
+export declare function createM91ApprovalTool(client: M91Client, defaults?: ApprovalDefaults): Promise<FunctionTool>;
+/** The fire-and-forget alert tool, `m91_send_alert`. Returns `"sent:delivered=N"` or `"error: …"`. */
+export declare function createM91AlertTool(client: M91Client, defaults?: AlertDefaults): Promise<FunctionTool>;
+/** Both tools, for an agent's `tools` array. */
+export declare function createM91Tools(client: M91Client, defaults?: ApprovalDefaults & AlertDefaults): Promise<FunctionTool[]>;
+/**
+ * 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 declare function approveInterruptionsWithM91(result: Pick<RunResult<any, any>, 'interruptions' | 'state'>, client: M91Client, options?: GateOptions): Promise<number>;
+/**
+ * `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 declare 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>>;
+//# sourceMappingURL=openai-agents.d.ts.map

package/dist/src/integrations/openai-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-agents.d.ts","sourceRoot":"","sources":["../../../src/integrations/openai-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAiC,MAAM,gBAAgB,CAAC;AAEpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAQL,KAAK,aAAa,EAElB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAmBpB,8GAA8G;AAC9G,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,QAAQ,GAAE,gBAAqB,GAC9B,OAAO,CAAC,YAAY,CAAC,CAUvB;AAED,sGAAsG;AACtG,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,QAAQ,GAAE,aAAkB,GAC3B,OAAO,CAAC,YAAY,CAAC,CASvB;AAED,gDAAgD;AAChD,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,EACjB,QAAQ,GAAE,gBAAgB,GAAG,aAAkB,GAC9C,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB;AAiBD;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,EAC5D,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,CAajB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,SAAS,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,EACtE,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,cAAc,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAClE,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,WAAW,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACvF,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CASjC"}

package/dist/src/integrations/openai-agents.js

@@ -0,0 +1,127 @@
+/**
+ * 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 { ALERT_DESCRIPTION, ALERT_SCHEMA, ALERT_TOOL_NAME, APPROVAL_DESCRIPTION, APPROVAL_SCHEMA, APPROVAL_TOOL_NAME, decideToolCall, needsHuman, runAlert, runApproval, } from './specs.js';
+async function agentsModule() {
+    try {
+        const specifier = '@openai/agents';
+        return (await import(specifier));
+    }
+    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, defaults = {}) {
+    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) => runApproval(client, args, defaults),
+    });
+}
+/** The fire-and-forget alert tool, `m91_send_alert`. Returns `"sent:delivered=N"` or `"error: …"`. */
+export async function createM91AlertTool(client, defaults = {}) {
+    const { tool } = await agentsModule();
+    return tool({
+        name: ALERT_TOOL_NAME,
+        description: ALERT_DESCRIPTION,
+        parameters: ALERT_SCHEMA,
+        strict: false,
+        execute: (args) => runAlert(client, args, defaults),
+    });
+}
+/** Both tools, for an agent's `tools` array. */
+export async function createM91Tools(client, defaults = {}) {
+    return [await createM91ApprovalTool(client, defaults), await createM91AlertTool(client, defaults)];
+}
+function parseArguments(item) {
+    const raw = item.arguments;
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function callIdOf(item) {
+    const raw = item.rawItem;
+    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, client, options = {}) {
+    const state = result.state;
+    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(agent, input, client, options = {}) {
+    const { run } = await agentsModule();
+    const { runOptions, maxRounds = 20, ...gate } = options;
+    let result = (await run(agent, input, runOptions));
+    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));
+    }
+    return result;
+}
+//# sourceMappingURL=openai-agents.js.map

package/dist/src/integrations/openai-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-agents.js","sourceRoot":"","sources":["../../../src/integrations/openai-agents.ts"],"names":[],"mappings":"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"}