agent-operator 0.1.0

package/dist/operator.js

@@ -0,0 +1,206 @@
+import { NotificationEngine } from "./notifications/engine.js";
+import { TelegramProvider } from "./notifications/telegram.js";
+import { runPolicyChecks } from "./policies/engine.js";
+import { PolicyDeniedError } from "./policies/types.js";
+import { recordSpend, getSpendSummary } from "./spend/tracker.js";
+import { TempoConnector } from "./connectors/tempo.js";
+import { BaseConnector } from "./connectors/base.js";
+import { SolanaConnector } from "./connectors/solana.js";
+export class Operator {
+    config;
+    connectors = new Map();
+    notifications;
+    dailySummaryInterval = null;
+    constructor(config) {
+        this.config = config;
+        this.notifications = new NotificationEngine();
+        this.initConnectors();
+        this.initNotifications();
+    }
+    initConnectors() {
+        const connectorInstances = {
+            tempo: new TempoConnector(),
+            base: new BaseConnector(),
+            solana: new SolanaConnector(),
+        };
+        // register only the connectors that wallets actually use
+        const neededChains = new Set();
+        for (const wallet of Object.values(this.config.wallets)) {
+            for (const chain of wallet.chains) {
+                neededChains.add(chain);
+            }
+        }
+        for (const chain of neededChains) {
+            const connector = connectorInstances[chain];
+            if (!connector) {
+                throw new Error(`No built-in connector for chain '${chain}'`);
+            }
+            this.connectors.set(chain, connector);
+        }
+    }
+    initNotifications() {
+        for (const [walletName, wallet] of Object.entries(this.config.wallets)) {
+            const provider = this.createProvider(wallet);
+            this.notifications.registerProvider(walletName, provider);
+        }
+    }
+    createProvider(wallet) {
+        const { provider, ...rest } = wallet.notifications;
+        switch (provider) {
+            case "telegram":
+                return new TelegramProvider({
+                    botToken: rest.botToken,
+                    chatId: rest.chatId,
+                    approvalTimeout: rest.approvalTimeout,
+                });
+            default:
+                throw new Error(`Unknown notification provider '${provider}'`);
+        }
+    }
+    async start() {
+        await this.notifications.startAll();
+        this.startDailySummary();
+    }
+    async shutdown() {
+        if (this.dailySummaryInterval) {
+            clearInterval(this.dailySummaryInterval);
+            this.dailySummaryInterval = null;
+        }
+        await this.notifications.stopAll();
+    }
+    async pay(walletName, params) {
+        const wallet = this.getWalletConfig(walletName);
+        const connector = this.getConnector(walletName, params.chain);
+        const provider = this.notifications.getProvider(walletName);
+        const alerts = wallet.notifications.alerts;
+        // run policy checks
+        try {
+            await runPolicyChecks({
+                walletName,
+                walletId: wallet.walletId,
+                service: params.service,
+                chain: params.chain,
+                maxBudget: params.maxBudget,
+                policies: wallet.policies,
+                alerts,
+                connector,
+                provider,
+            });
+        }
+        catch (err) {
+            if (err instanceof PolicyDeniedError && alerts.policyDenied) {
+                await this.notifications.notify(walletName, {
+                    type: "policy_denied",
+                    walletName,
+                    chain: params.chain,
+                    data: {
+                        reason: err.reason,
+                        details: err.details,
+                    },
+                    timestamp: new Date().toISOString(),
+                }, alerts).catch(() => { });
+            }
+            throw err;
+        }
+        // notify session opened
+        if (alerts.sessionOpened) {
+            await this.notifications.notify(walletName, {
+                type: "session_opened",
+                walletName,
+                chain: params.chain,
+                data: {
+                    service: params.service,
+                    maxBudget: params.maxBudget,
+                },
+                timestamp: new Date().toISOString(),
+            }, alerts).catch(() => { });
+        }
+        // open session via connector
+        const session = await connector.openSession({
+            service: params.service,
+            maxBudget: params.maxBudget,
+            walletId: wallet.walletId,
+        });
+        // close session and record spend
+        const result = await connector.closeSession(session.sessionId);
+        recordSpend(walletName, params.service, params.chain, result.totalSpent);
+        return result;
+    }
+    async getBalance(walletName, chain) {
+        const wallet = this.getWalletConfig(walletName);
+        const connector = this.getConnector(walletName, chain);
+        return connector.getBalance(wallet.walletId);
+    }
+    async closeSession(walletName, sessionId) {
+        // find the connector that has this session
+        // try all connectors for this wallet
+        const wallet = this.getWalletConfig(walletName);
+        for (const chain of wallet.chains) {
+            const connector = this.connectors.get(chain);
+            if (!connector)
+                continue;
+            try {
+                const result = await connector.closeSession(sessionId);
+                recordSpend(walletName, "", chain, result.totalSpent);
+                return result;
+            }
+            catch {
+                // session not found on this connector, try next
+            }
+        }
+        throw new Error(`Session '${sessionId}' not found on any connector for wallet '${walletName}'`);
+    }
+    getWalletNames() {
+        return Object.keys(this.config.wallets);
+    }
+    getWalletConfig(walletName) {
+        const wallet = this.config.wallets[walletName];
+        if (!wallet) {
+            throw new Error(`Wallet '${walletName}' not found in config. Available: ${Object.keys(this.config.wallets).join(", ")}`);
+        }
+        return wallet;
+    }
+    getConnector(walletName, chain) {
+        const wallet = this.getWalletConfig(walletName);
+        if (!wallet.chains.includes(chain)) {
+            throw new Error(`Wallet '${walletName}' is not configured for chain '${chain}'. Available: ${wallet.chains.join(", ")}`);
+        }
+        const connector = this.connectors.get(chain);
+        if (!connector) {
+            throw new Error(`No connector found for chain '${chain}'`);
+        }
+        return connector;
+    }
+    startDailySummary() {
+        // fire daily summary every 24h
+        this.dailySummaryInterval = setInterval(async () => {
+            for (const [walletName, wallet] of Object.entries(this.config.wallets)) {
+                const alerts = wallet.notifications.alerts;
+                if (!alerts.dailySummary)
+                    continue;
+                const summary = getSpendSummary(walletName);
+                const balances = {};
+                for (const chain of wallet.chains) {
+                    try {
+                        const balance = await this.getBalance(walletName, chain);
+                        balances[chain] = balance.amount;
+                    }
+                    catch {
+                        balances[chain] = -1;
+                    }
+                }
+                await this.notifications.notify(walletName, {
+                    type: "daily_summary",
+                    walletName,
+                    data: {
+                        spent: summary.spent,
+                        dailyLimit: wallet.policies.dailyLimit,
+                        sessionCount: summary.sessionCount,
+                        balance: balances,
+                    },
+                    timestamp: new Date().toISOString(),
+                }, alerts).catch(() => { });
+            }
+        }, 24 * 60 * 60 * 1000);
+    }
+}

package/dist/policies/daily-limit.d.ts

@@ -0,0 +1 @@
+export declare function checkDailyLimit(walletName: string, maxBudget: number, dailyLimit?: number): void;

package/dist/policies/daily-limit.js

@@ -0,0 +1,15 @@
+import { getTodaySpend } from "../spend/tracker.js";
+import { PolicyDeniedError } from "./types.js";
+export function checkDailyLimit(walletName, maxBudget, dailyLimit) {
+    if (dailyLimit === undefined)
+        return;
+    const spent = getTodaySpend(walletName);
+    if (spent + maxBudget > dailyLimit) {
+        throw new PolicyDeniedError("daily_limit", {
+            attempted: maxBudget,
+            dailyLimit,
+            spent,
+            remaining: Math.max(0, dailyLimit - spent),
+        });
+    }
+}

package/dist/policies/engine.d.ts

@@ -0,0 +1,16 @@
+import type { PoliciesConfig } from "./types.js";
+import type { Connector } from "../connectors/types.js";
+import type { NotificationProvider } from "../notifications/types.js";
+import type { AlertsConfig } from "../notifications/types.js";
+export interface PolicyCheckParams {
+    walletName: string;
+    walletId: string;
+    service: string;
+    chain: string;
+    maxBudget: number;
+    policies: PoliciesConfig;
+    alerts: AlertsConfig;
+    connector: Connector;
+    provider: NotificationProvider;
+}
+export declare function runPolicyChecks(params: PolicyCheckParams): Promise<void>;

package/dist/policies/engine.js

@@ -0,0 +1,24 @@
+import { checkSessionCap } from "./session-cap.js";
+import { checkDailyLimit } from "./daily-limit.js";
+import { checkHighValue } from "./high-value-gate.js";
+import { checkNewCounterparty } from "./new-counterparty.js";
+import { checkLowBalance } from "./low-balance.js";
+export async function runPolicyChecks(params) {
+    const { walletName, walletId, service, chain, maxBudget, policies, alerts, connector, provider } = params;
+    // 1. session cap — fast, synchronous
+    checkSessionCap(maxBudget, policies.sessionCap);
+    // 2. daily limit — reads local spend file
+    checkDailyLimit(walletName, maxBudget, policies.dailyLimit);
+    // 3. high value gate — may block for approval
+    if (alerts.highValueTx) {
+        await checkHighValue(walletName, chain, service, maxBudget, policies.highValueThreshold, provider);
+    }
+    // 4. new counterparty hold — may block for approval
+    if (alerts.newCounterparty) {
+        await checkNewCounterparty(walletName, chain, service, maxBudget, policies.newCounterpartyHold, provider);
+    }
+    // 5. low balance — non-blocking alert
+    if (alerts.lowBalance) {
+        await checkLowBalance(walletName, walletId, chain, policies.lowBalanceThreshold, connector, provider);
+    }
+}

package/dist/policies/high-value-gate.d.ts

@@ -0,0 +1,2 @@
+import type { NotificationProvider } from "../notifications/types.js";
+export declare function checkHighValue(walletName: string, chain: string, service: string, maxBudget: number, highValueThreshold: number | undefined, provider: NotificationProvider): Promise<void>;

package/dist/policies/high-value-gate.js

@@ -0,0 +1,28 @@
+import { randomUUID } from "node:crypto";
+import { PolicyDeniedError } from "./types.js";
+export async function checkHighValue(walletName, chain, service, maxBudget, highValueThreshold, provider) {
+    if (highValueThreshold === undefined)
+        return;
+    if (maxBudget <= highValueThreshold)
+        return;
+    const approvalId = randomUUID();
+    const result = await provider.sendWithApproval({
+        type: "high_value_tx",
+        walletName,
+        chain,
+        approvalId,
+        data: {
+            service,
+            amount: maxBudget,
+            threshold: highValueThreshold,
+        },
+        timestamp: new Date().toISOString(),
+    });
+    if (!result.approved) {
+        throw new PolicyDeniedError("high_value_rejected", {
+            attempted: maxBudget,
+            highValueThreshold,
+            service,
+        });
+    }
+}

package/dist/policies/low-balance.d.ts

@@ -0,0 +1,3 @@
+import type { Connector } from "../connectors/types.js";
+import type { NotificationProvider } from "../notifications/types.js";
+export declare function checkLowBalance(walletName: string, walletId: string, chain: string, lowBalanceThreshold: number | undefined, connector: Connector, provider: NotificationProvider): Promise<void>;

package/dist/policies/low-balance.js

@@ -0,0 +1,23 @@
+export async function checkLowBalance(walletName, walletId, chain, lowBalanceThreshold, connector, provider) {
+    if (lowBalanceThreshold === undefined)
+        return;
+    try {
+        const balance = await connector.getBalance(walletId);
+        if (balance.amount < lowBalanceThreshold) {
+            await provider.send({
+                type: "low_balance",
+                walletName,
+                chain,
+                data: {
+                    balance: balance.amount,
+                    currency: balance.currency,
+                    threshold: lowBalanceThreshold,
+                },
+                timestamp: new Date().toISOString(),
+            }).catch(() => { });
+        }
+    }
+    catch {
+        // non-blocking — don't fail the payment over a balance check
+    }
+}

package/dist/policies/new-counterparty.d.ts

@@ -0,0 +1,2 @@
+import type { NotificationProvider } from "../notifications/types.js";
+export declare function checkNewCounterparty(walletName: string, chain: string, service: string, maxBudget: number, newCounterpartyHold: boolean | undefined, provider: NotificationProvider): Promise<void>;

package/dist/policies/new-counterparty.js

@@ -0,0 +1,29 @@
+import { randomUUID } from "node:crypto";
+import { getCounterparties, addCounterparty } from "../spend/tracker.js";
+import { PolicyDeniedError } from "./types.js";
+export async function checkNewCounterparty(walletName, chain, service, maxBudget, newCounterpartyHold, provider) {
+    if (!newCounterpartyHold)
+        return;
+    const known = getCounterparties(walletName);
+    if (known.includes(service))
+        return;
+    const approvalId = randomUUID();
+    const result = await provider.sendWithApproval({
+        type: "new_counterparty",
+        walletName,
+        chain,
+        approvalId,
+        data: {
+            service,
+            maxBudget,
+        },
+        timestamp: new Date().toISOString(),
+    });
+    if (!result.approved) {
+        throw new PolicyDeniedError("new_counterparty_rejected", {
+            service,
+            maxBudget,
+        });
+    }
+    addCounterparty(walletName, service);
+}

package/dist/policies/session-cap.d.ts

@@ -0,0 +1 @@
+export declare function checkSessionCap(maxBudget: number, sessionCap?: number): void;

package/dist/policies/session-cap.js

@@ -0,0 +1,11 @@
+import { PolicyDeniedError } from "./types.js";
+export function checkSessionCap(maxBudget, sessionCap) {
+    if (sessionCap === undefined)
+        return;
+    if (maxBudget > sessionCap) {
+        throw new PolicyDeniedError("session_cap", {
+            attempted: maxBudget,
+            sessionCap,
+        });
+    }
+}

package/dist/policies/types.d.ts

@@ -0,0 +1,18 @@
+export interface PoliciesConfig {
+    dailyLimit?: number;
+    sessionCap?: number;
+    newCounterpartyHold?: boolean;
+    lowBalanceThreshold?: number;
+    highValueThreshold?: number;
+}
+export type PolicyDenialReason = "daily_limit" | "session_cap" | "high_value_rejected" | "new_counterparty_rejected";
+export declare class PolicyDeniedError extends Error {
+    readonly reason: PolicyDenialReason;
+    readonly details: Record<string, unknown>;
+    constructor(reason: PolicyDenialReason, details: Record<string, unknown>);
+}
+export declare class ConnectorError extends Error {
+    readonly chain: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, chain: string, cause?: Error | undefined);
+}

package/dist/policies/types.js

@@ -0,0 +1,20 @@
+export class PolicyDeniedError extends Error {
+    reason;
+    details;
+    constructor(reason, details) {
+        super(`Policy denied: ${reason}`);
+        this.reason = reason;
+        this.details = details;
+        this.name = "PolicyDeniedError";
+    }
+}
+export class ConnectorError extends Error {
+    chain;
+    cause;
+    constructor(message, chain, cause) {
+        super(message);
+        this.chain = chain;
+        this.cause = cause;
+        this.name = "ConnectorError";
+    }
+}

package/dist/spend/tracker.d.ts

@@ -0,0 +1,17 @@
+interface SessionEntry {
+    service: string;
+    chain: string;
+    amount: number;
+    ts: string;
+}
+export declare function getTodaySpend(walletName: string): number;
+export declare function getTodaySessions(walletName: string): SessionEntry[];
+export declare function recordSpend(walletName: string, service: string, chain: string, amount: number): void;
+export declare function getCounterparties(walletName: string): string[];
+export declare function addCounterparty(walletName: string, service: string): void;
+export declare function getSpendSummary(walletName: string): {
+    spent: number;
+    sessionCount: number;
+    sessions: SessionEntry[];
+};
+export {};

package/dist/spend/tracker.js

@@ -0,0 +1,101 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const SPEND_DIR = join(homedir(), ".agent-operator");
+const SPEND_FILE = join(SPEND_DIR, "spend.json");
+function today() {
+    return new Date().toISOString().split("T")[0];
+}
+function ensureDir() {
+    if (!existsSync(SPEND_DIR)) {
+        mkdirSync(SPEND_DIR, { recursive: true });
+    }
+}
+function readSpendFile() {
+    ensureDir();
+    if (!existsSync(SPEND_FILE)) {
+        return {};
+    }
+    try {
+        return JSON.parse(readFileSync(SPEND_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeSpendFile(data) {
+    ensureDir();
+    writeFileSync(SPEND_FILE, JSON.stringify(data, null, 2));
+}
+function ensureWallet(data, walletName) {
+    if (!data[walletName]) {
+        data[walletName] = { days: {}, counterparties: [] };
+    }
+}
+function ensureToday(data, walletName) {
+    const date = today();
+    if (!data[walletName].days[date]) {
+        data[walletName].days[date] = { spent: 0, sessions: [] };
+    }
+}
+function cleanOldDates(data, walletName) {
+    const date = today();
+    const days = data[walletName].days;
+    for (const key of Object.keys(days)) {
+        if (key !== date) {
+            delete days[key];
+        }
+    }
+}
+export function getTodaySpend(walletName) {
+    const data = readSpendFile();
+    ensureWallet(data, walletName);
+    const date = today();
+    return data[walletName].days[date]?.spent ?? 0;
+}
+export function getTodaySessions(walletName) {
+    const data = readSpendFile();
+    ensureWallet(data, walletName);
+    const date = today();
+    return data[walletName].days[date]?.sessions ?? [];
+}
+export function recordSpend(walletName, service, chain, amount) {
+    const data = readSpendFile();
+    ensureWallet(data, walletName);
+    cleanOldDates(data, walletName);
+    ensureToday(data, walletName);
+    const date = today();
+    const dayData = data[walletName].days[date];
+    dayData.spent += amount;
+    dayData.sessions.push({
+        service,
+        chain,
+        amount,
+        ts: new Date().toISOString(),
+    });
+    writeSpendFile(data);
+}
+export function getCounterparties(walletName) {
+    const data = readSpendFile();
+    ensureWallet(data, walletName);
+    return data[walletName].counterparties ?? [];
+}
+export function addCounterparty(walletName, service) {
+    const data = readSpendFile();
+    ensureWallet(data, walletName);
+    if (!data[walletName].counterparties.includes(service)) {
+        data[walletName].counterparties.push(service);
+    }
+    writeSpendFile(data);
+}
+export function getSpendSummary(walletName) {
+    const data = readSpendFile();
+    ensureWallet(data, walletName);
+    const date = today();
+    const dayData = data[walletName].days[date];
+    return {
+        spent: dayData?.spent ?? 0,
+        sessionCount: dayData?.sessions.length ?? 0,
+        sessions: dayData?.sessions ?? [],
+    };
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "agent-operator",
+  "version": "0.1.0",
+  "description": "Drop-in toolkit for governed, observable AI agent payments",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agent-operator": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "payments",
+    "mpp",
+    "ows",
+    "wallet",
+    "solana",
+    "tempo",
+    "base"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentrDev/agent-operator"
+  },
+  "dependencies": {
+    "@open-wallet-standard/core": "*",
+    "@solana/mpp": "^0.2.0",
+    "@solana/spl-token": "^0.4.14",
+    "@solana/web3.js": "^1.98.4",
+    "grammy": "^1.42.0",
+    "mppx": "*",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/prompts": "^2.4.9",
+    "typescript": "^5.5.0"
+  }
+}