agent-operator 0.1.0

package/dist/connectors/solana.js

@@ -0,0 +1,91 @@
+import { getWallet, signTransaction } from "@open-wallet-standard/core";
+import { solana } from "@solana/mpp/client";
+import { Mppx } from "mppx/client";
+export class SolanaConnector {
+    chain = "solana";
+    sessions = new Map();
+    async openSession(params) {
+        const { service, maxBudget, walletId } = params;
+        const wallet = getWallet(walletId);
+        const solanaAccount = wallet.accounts.find((a) => a.chainId.startsWith("solana"));
+        if (!solanaAccount) {
+            throw new Error(`Wallet '${walletId}' has no Solana account`);
+        }
+        // create an OWS-backed TransactionSigner compatible with @solana/kit
+        const { address } = await import("@solana/kit");
+        const owsSigner = {
+            address: address(solanaAccount.address),
+            async signTransactions(transactions) {
+                return Promise.all(transactions.map(async (tx) => {
+                    const txBytes = typeof tx.serialize === "function"
+                        ? tx.serialize()
+                        : new Uint8Array(tx);
+                    const txHex = Buffer.from(txBytes).toString("hex");
+                    const result = signTransaction(walletId, "solana:mainnet-beta", txHex);
+                    // return the signed transaction bytes
+                    return Buffer.from(result.signature, "hex");
+                }));
+            },
+        };
+        // create @solana/mpp charge method with OWS signer
+        const chargeMethod = solana.charge({
+            signer: owsSigner,
+        });
+        const mppxClient = Mppx.create({
+            methods: [chargeMethod],
+        });
+        // initiate payment via the 402 challenge-response flow
+        await mppxClient.fetch(service, {
+            headers: { "X-Max-Budget": String(maxBudget) },
+        });
+        const sessionId = crypto.randomUUID();
+        this.sessions.set(sessionId, {
+            sessionId,
+            service,
+            maxBudget,
+            mppxClient,
+        });
+        return {
+            sessionId,
+            chain: this.chain,
+            service,
+            maxBudget,
+            spent: 0,
+            status: "active",
+        };
+    }
+    async closeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session '${sessionId}' not found`);
+        }
+        this.sessions.delete(sessionId);
+        return {
+            sessionId,
+            totalSpent: session.maxBudget,
+        };
+    }
+    async getBalance(walletId) {
+        const wallet = getWallet(walletId);
+        const solanaAccount = wallet.accounts.find((a) => a.chainId.startsWith("solana"));
+        if (!solanaAccount) {
+            return { chain: this.chain, amount: 0, currency: "USDC" };
+        }
+        try {
+            const { createSolanaRpc } = await import("@solana/kit");
+            const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+            // get native SOL balance
+            const { value } = await rpc
+                .getBalance(solanaAccount.address)
+                .send();
+            return {
+                chain: this.chain,
+                amount: Number(value) / 1e9,
+                currency: "SOL",
+            };
+        }
+        catch {
+            return { chain: this.chain, amount: 0, currency: "SOL" };
+        }
+    }
+}

package/dist/connectors/tempo.d.ts

@@ -0,0 +1,12 @@
+import type { Connector, Session, SessionResult, Balance } from "./types.js";
+export declare class TempoConnector implements Connector {
+    chain: string;
+    private sessions;
+    openSession(params: {
+        service: string;
+        maxBudget: number;
+        walletId: string;
+    }): Promise<Session>;
+    closeSession(sessionId: string): Promise<SessionResult>;
+    getBalance(walletId: string): Promise<Balance>;
+}

package/dist/connectors/tempo.js

@@ -0,0 +1,102 @@
+import { tempo as tempoClient } from "mppx/client";
+import { signMessage, getWallet } from "@open-wallet-standard/core";
+export class TempoConnector {
+    chain = "tempo";
+    sessions = new Map();
+    async openSession(params) {
+        const { service, maxBudget, walletId } = params;
+        const wallet = getWallet(walletId);
+        const evmAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155"));
+        if (!evmAccount) {
+            throw new Error(`Wallet '${walletId}' has no EVM account for Tempo`);
+        }
+        // create OWS-backed viem custom account for Tempo
+        const { toAccount } = await import("viem/accounts");
+        const { createPublicClient, http } = await import("viem");
+        const { tempo: tempoChain } = await import("viem/chains");
+        const owsAccount = toAccount({
+            address: evmAccount.address,
+            async signMessage({ message }) {
+                const msgStr = typeof message === "string"
+                    ? message
+                    : Buffer.from(message.raw).toString("hex");
+                const result = signMessage(walletId, "eip155:1", msgStr);
+                return result.signature;
+            },
+            async signTransaction(tx) {
+                const { signTransaction: owsSignTx } = await import("@open-wallet-standard/core");
+                const txHex = typeof tx === "string" ? tx : JSON.stringify(tx);
+                const result = owsSignTx(walletId, "eip155:1", txHex);
+                return result.signature;
+            },
+            async signTypedData(typedData) {
+                const { signTypedData: owsSignTyped } = await import("@open-wallet-standard/core");
+                const result = owsSignTyped(walletId, "eip155:1", JSON.stringify(typedData));
+                return result.signature;
+            },
+        });
+        // create the session manager with Tempo's built-in method
+        const manager = tempoClient.session({
+            account: owsAccount,
+            maxDeposit: String(maxBudget),
+        });
+        // open the session (creates on-chain channel)
+        await manager.open({ deposit: BigInt(Math.floor(maxBudget * 1e6)) });
+        const sessionId = manager.channelId ?? crypto.randomUUID();
+        this.sessions.set(sessionId, {
+            sessionId,
+            service,
+            maxBudget,
+            manager,
+        });
+        return {
+            sessionId,
+            chain: this.chain,
+            service,
+            maxBudget,
+            spent: 0,
+            status: "active",
+        };
+    }
+    async closeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new Error(`Session '${sessionId}' not found`);
+        }
+        const receipt = await session.manager.close();
+        this.sessions.delete(sessionId);
+        const totalSpent = Number(session.manager.cumulative) / 1e6;
+        return {
+            sessionId,
+            totalSpent,
+            refund: session.maxBudget - totalSpent,
+        };
+    }
+    async getBalance(walletId) {
+        const wallet = getWallet(walletId);
+        const evmAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155"));
+        if (!evmAccount) {
+            return { chain: this.chain, amount: 0, currency: "TEMPO" };
+        }
+        try {
+            const { createPublicClient, http, parseAbi } = await import("viem");
+            const { tempo: tempoChain } = await import("viem/chains");
+            const client = createPublicClient({
+                chain: tempoChain,
+                transport: http(),
+            });
+            // query native balance
+            const balance = await client.getBalance({
+                address: evmAccount.address,
+            });
+            return {
+                chain: this.chain,
+                amount: Number(balance) / 1e18,
+                currency: "TEMPO",
+            };
+        }
+        catch {
+            return { chain: this.chain, amount: 0, currency: "TEMPO" };
+        }
+    }
+}

package/dist/connectors/types.d.ts

@@ -0,0 +1,28 @@
+export interface Connector {
+    chain: string;
+    openSession(params: {
+        service: string;
+        maxBudget: number;
+        walletId: string;
+    }): Promise<Session>;
+    closeSession(sessionId: string): Promise<SessionResult>;
+    getBalance(walletId: string): Promise<Balance>;
+}
+export interface Session {
+    sessionId: string;
+    chain: string;
+    service: string;
+    maxBudget: number;
+    spent: number;
+    status: "active" | "closed";
+}
+export interface SessionResult {
+    sessionId: string;
+    totalSpent: number;
+    refund?: number;
+}
+export interface Balance {
+    chain: string;
+    amount: number;
+    currency: string;
+}

package/dist/connectors/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { Operator } from "./operator.js";
+export { Operator } from "./operator.js";
+export type { PayParams } from "./operator.js";
+export { loadConfig } from "./config.js";
+export type { OperatorConfig, WalletConfig, NotificationConfig } from "./config.js";
+export type { Connector, Session, SessionResult, Balance } from "./connectors/types.js";
+export { TempoConnector } from "./connectors/tempo.js";
+export { BaseConnector } from "./connectors/base.js";
+export { SolanaConnector } from "./connectors/solana.js";
+export type { NotificationProvider, AgentEvent, ApprovalEvent, ApprovalResult, AlertsConfig, } from "./notifications/types.js";
+export { TelegramProvider } from "./notifications/telegram.js";
+export { NotificationEngine } from "./notifications/engine.js";
+export { PolicyDeniedError, ConnectorError } from "./policies/types.js";
+export type { PoliciesConfig } from "./policies/types.js";
+export declare function createOperator(configPath?: string): Promise<Operator>;

package/dist/index.js

@@ -0,0 +1,16 @@
+import { loadConfig } from "./config.js";
+import { Operator } from "./operator.js";
+export { Operator } from "./operator.js";
+export { loadConfig } from "./config.js";
+export { TempoConnector } from "./connectors/tempo.js";
+export { BaseConnector } from "./connectors/base.js";
+export { SolanaConnector } from "./connectors/solana.js";
+export { TelegramProvider } from "./notifications/telegram.js";
+export { NotificationEngine } from "./notifications/engine.js";
+export { PolicyDeniedError, ConnectorError } from "./policies/types.js";
+export async function createOperator(configPath) {
+    const config = loadConfig(configPath);
+    const operator = new Operator(config);
+    await operator.start();
+    return operator;
+}

package/dist/notifications/engine.d.ts

@@ -0,0 +1,11 @@
+import type { NotificationProvider, AgentEvent, ApprovalEvent, ApprovalResult, AlertsConfig } from "./types.js";
+export declare class NotificationEngine {
+    private providers;
+    registerProvider(walletName: string, provider: NotificationProvider): void;
+    getProvider(walletName: string): NotificationProvider;
+    startAll(): Promise<void>;
+    stopAll(): Promise<void>;
+    notify(walletName: string, event: AgentEvent, alerts: AlertsConfig): Promise<void>;
+    requestApproval(walletName: string, event: ApprovalEvent): Promise<ApprovalResult>;
+    private shouldSend;
+}

package/dist/notifications/engine.js

@@ -0,0 +1,64 @@
+export class NotificationEngine {
+    providers = new Map();
+    registerProvider(walletName, provider) {
+        this.providers.set(walletName, provider);
+    }
+    getProvider(walletName) {
+        const provider = this.providers.get(walletName);
+        if (!provider) {
+            throw new Error(`No notification provider configured for wallet '${walletName}'`);
+        }
+        return provider;
+    }
+    async startAll() {
+        const started = new Set();
+        for (const [, provider] of this.providers) {
+            // avoid starting the same provider instance twice
+            // (multiple wallets could share a provider)
+            if (!started.has(provider.name)) {
+                await provider.start();
+                started.add(provider.name);
+            }
+        }
+    }
+    async stopAll() {
+        const stopped = new Set();
+        for (const [, provider] of this.providers) {
+            if (!stopped.has(provider.name)) {
+                await provider.stop();
+                stopped.add(provider.name);
+            }
+        }
+    }
+    async notify(walletName, event, alerts) {
+        if (!this.shouldSend(event.type, alerts))
+            return;
+        const provider = this.providers.get(walletName);
+        if (!provider)
+            return;
+        try {
+            await provider.send(event);
+        }
+        catch (err) {
+            console.error(`[agent-operator] notification failed for '${walletName}':`, err);
+        }
+    }
+    async requestApproval(walletName, event) {
+        const provider = this.getProvider(walletName);
+        return provider.sendWithApproval(event);
+    }
+    shouldSend(type, alerts) {
+        switch (type) {
+            case "low_balance":
+                return alerts.lowBalance !== false;
+            case "policy_denied":
+                return alerts.policyDenied !== false;
+            case "daily_summary":
+                return alerts.dailySummary !== false;
+            case "session_opened":
+                return alerts.sessionOpened === true;
+            default:
+                return true;
+        }
+    }
+}

package/dist/notifications/telegram.d.ts

@@ -0,0 +1,21 @@
+import type { NotificationProvider, AgentEvent, ApprovalEvent, ApprovalResult } from "./types.js";
+interface TelegramConfig {
+    botToken: string;
+    chatId: string;
+    approvalTimeout?: number;
+}
+export declare class TelegramProvider implements NotificationProvider {
+    name: string;
+    private bot;
+    private pendingApprovals;
+    private config;
+    private started;
+    constructor(config: TelegramConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(event: AgentEvent): Promise<void>;
+    sendWithApproval(event: ApprovalEvent): Promise<ApprovalResult>;
+    private formatEvent;
+    private formatApprovalEvent;
+}
+export {};

package/dist/notifications/telegram.js

@@ -0,0 +1,146 @@
+import { Bot } from "grammy";
+const DEFAULT_APPROVAL_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+export class TelegramProvider {
+    name = "telegram";
+    bot = null;
+    pendingApprovals = new Map();
+    config;
+    started = false;
+    constructor(config) {
+        this.config = config;
+    }
+    async start() {
+        if (this.started)
+            return;
+        try {
+            this.bot = new Bot(this.config.botToken);
+            this.bot.on("callback_query:data", async (ctx) => {
+                const data = ctx.callbackQuery.data;
+                const [action, approvalId] = data.split(":");
+                const resolve = this.pendingApprovals.get(approvalId);
+                if (!resolve) {
+                    await ctx.answerCallbackQuery({ text: "This approval has expired." });
+                    return;
+                }
+                const approved = action === "approve";
+                resolve(approved);
+                this.pendingApprovals.delete(approvalId);
+                await ctx.answerCallbackQuery({
+                    text: approved ? "Approved" : "Rejected",
+                });
+                await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+                await ctx.api.sendMessage(this.config.chatId, approved ? "✅ Approved" : "❌ Rejected");
+            });
+            this.bot.start({ drop_pending_updates: true });
+            this.started = true;
+        }
+        catch (err) {
+            throw new Error(`Failed to start TelegramProvider. Is 'grammy' installed? ${err}`);
+        }
+    }
+    async stop() {
+        if (this.bot && this.started) {
+            await this.bot.stop();
+            this.started = false;
+        }
+        for (const [id, resolve] of this.pendingApprovals) {
+            resolve(false);
+            this.pendingApprovals.delete(id);
+        }
+    }
+    async send(event) {
+        const message = this.formatEvent(event);
+        await this.bot.api.sendMessage(this.config.chatId, message, {
+            parse_mode: "HTML",
+        });
+    }
+    async sendWithApproval(event) {
+        const message = this.formatApprovalEvent(event);
+        const timeout = this.config.approvalTimeout ?? DEFAULT_APPROVAL_TIMEOUT;
+        await this.bot.api.sendMessage(this.config.chatId, message, {
+            parse_mode: "HTML",
+            reply_markup: {
+                inline_keyboard: [
+                    [
+                        {
+                            text: "✅ Approve",
+                            callback_data: `approve:${event.approvalId}`,
+                        },
+                        {
+                            text: "❌ Reject",
+                            callback_data: `reject:${event.approvalId}`,
+                        },
+                    ],
+                ],
+            },
+        });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingApprovals.delete(event.approvalId);
+                resolve({ approved: false, approvalId: event.approvalId });
+            }, timeout);
+            this.pendingApprovals.set(event.approvalId, (approved) => {
+                clearTimeout(timer);
+                resolve({ approved, approvalId: event.approvalId });
+            });
+        });
+    }
+    formatEvent(event) {
+        const { type, walletName, chain, data } = event;
+        switch (type) {
+            case "low_balance":
+                return [
+                    `⚠️ <b>Low Balance</b>`,
+                    `Wallet: ${walletName}${chain ? ` on ${chain}` : ""}`,
+                    `Balance: $${data.balance}`,
+                    `Threshold: $${data.threshold}`,
+                ].join("\n");
+            case "policy_denied":
+                return [
+                    `❌ <b>Policy Denied</b>`,
+                    `Wallet: ${walletName}`,
+                    `Reason: ${data.reason}`,
+                    `Details: ${JSON.stringify(data.details)}`,
+                ].join("\n");
+            case "daily_summary":
+                return [
+                    `📊 <b>Daily Summary</b>`,
+                    `Wallet: ${walletName}`,
+                    `Spent: $${data.spent} / $${data.dailyLimit}`,
+                    `Sessions: ${data.sessionCount}`,
+                    `Balance: $${data.balance}`,
+                ].join("\n");
+            case "session_opened":
+                return [
+                    `🔗 <b>Session Opened</b>`,
+                    `Wallet: ${walletName}${chain ? ` on ${chain}` : ""}`,
+                    `Service: ${data.service}`,
+                    `Budget: $${data.maxBudget}`,
+                ].join("\n");
+            default:
+                return `📢 ${type}: ${JSON.stringify(data)}`;
+        }
+    }
+    formatApprovalEvent(event) {
+        const { type, walletName, chain, data } = event;
+        switch (type) {
+            case "high_value_tx":
+                return [
+                    `🚨 <b>High Value Transaction</b>`,
+                    `Wallet: ${walletName}${chain ? ` on ${chain}` : ""}`,
+                    `Service: ${data.service}`,
+                    `Amount: $${data.amount}`,
+                    `Threshold: $${data.threshold}`,
+                ].join("\n");
+            case "new_counterparty":
+                return [
+                    `👀 <b>New Counterparty</b>`,
+                    `Wallet: ${walletName}${chain ? ` on ${chain}` : ""}`,
+                    `Service: ${data.service}`,
+                    `Max Budget: $${data.maxBudget}`,
+                ].join("\n");
+            default:
+                return `❓ Approval needed: ${JSON.stringify(data)}`;
+        }
+    }
+}

package/dist/notifications/types.d.ts

@@ -0,0 +1,32 @@
+export interface NotificationProvider {
+    name: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    send(event: AgentEvent): Promise<void>;
+    sendWithApproval(event: ApprovalEvent): Promise<ApprovalResult>;
+}
+export type AgentEventType = "low_balance" | "policy_denied" | "daily_summary" | "session_opened";
+export type ApprovalEventType = "high_value_tx" | "new_counterparty";
+export interface AgentEvent {
+    type: AgentEventType;
+    walletName: string;
+    chain?: string;
+    data: Record<string, unknown>;
+    timestamp: string;
+}
+export interface ApprovalEvent extends Omit<AgentEvent, "type"> {
+    type: ApprovalEventType;
+    approvalId: string;
+}
+export interface ApprovalResult {
+    approved: boolean;
+    approvalId: string;
+}
+export interface AlertsConfig {
+    lowBalance?: boolean;
+    highValueTx?: boolean;
+    newCounterparty?: boolean;
+    policyDenied?: boolean;
+    dailySummary?: boolean;
+    sessionOpened?: boolean;
+}

package/dist/notifications/types.js

@@ -0,0 +1 @@
+export {};

package/dist/operator.d.ts

@@ -0,0 +1,26 @@
+import type { OperatorConfig } from "./config.js";
+import type { SessionResult, Balance } from "./connectors/types.js";
+export interface PayParams {
+    service: string;
+    chain: string;
+    maxBudget: number;
+}
+export declare class Operator {
+    private config;
+    private connectors;
+    private notifications;
+    private dailySummaryInterval;
+    constructor(config: OperatorConfig);
+    private initConnectors;
+    private initNotifications;
+    private createProvider;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    pay(walletName: string, params: PayParams): Promise<SessionResult>;
+    getBalance(walletName: string, chain: string): Promise<Balance>;
+    closeSession(walletName: string, sessionId: string): Promise<SessionResult>;
+    getWalletNames(): string[];
+    private getWalletConfig;
+    private getConnector;
+    private startDailySummary;
+}