agent-operator

Drop-in toolkit for governed, observable AI agent payments.

MPP for payments via chain connectors. OWS for authorization + policies. Pluggable notifications for human oversight.

Install

npm install agent-operator

Quick Start

# interactive setup — creates agent-operator.json
npx agent-operator init

import { createOperator } from "agent-operator"

const operator = await createOperator()

await operator.pay("my-agent", {
  service: "https://api.example.com",
  chain: "base",
  maxBudget: 2,
})

await operator.shutdown()

Config

All configuration lives in agent-operator.json. The CLI generates it, or create it manually:

{
  "wallets": {
    "my-agent": {
      "walletId": "ows-wallet-id",
      "chains": ["base", "solana", "tempo"],
      "policies": {
        "dailyLimit": 50,
        "sessionCap": 5,
        "newCounterpartyHold": true,
        "lowBalanceThreshold": 10,
        "highValueThreshold": 200
      },
      "notifications": {
        "provider": "telegram",
        "botToken": "YOUR_BOT_TOKEN",
        "chatId": "YOUR_CHAT_ID",
        "alerts": {
          "lowBalance": true,
          "highValueTx": true,
          "newCounterparty": true,
          "policyDenied": true,
          "dailySummary": true,
          "sessionOpened": false
        }
      }
    }
  }
}

One agent-operator instance manages multiple wallets. Each wallet has its own chains, policies, and notification provider.

Connectors

Each connector wraps MPP for a specific chain. Built-in:

• Tempo — uses built-in mppx session method
• Base — custom MPPX method with OWS EVM signing, USDC balance via RPC
• Solana — wraps @solana/mpp with OWS Ed25519 signing, USDC balance via RPC

Connectors are resolved automatically from the wallet's chains array.

Policies

The policy engine runs before every pay() call, in order:

1. Session cap — reject if maxBudget > sessionCap
2. Daily limit — reject if today's spend + maxBudget > dailyLimit
3. High value gate — if above threshold, request human approval via notification
4. New counterparty hold — if first-time service, request human approval
5. Low balance alert — non-blocking notification if below threshold

Spend is tracked locally in ~/.agent-operator/spend.json.

Notifications

Pluggable provider system. Each wallet can use a different provider.

TelegramProvider (built-in)

Uses grammy with long-polling for approval flows. Included as a dependency — no extra install needed.

Approval messages show inline buttons. First response wins. Timeout (default 5 min) = rejected.

Custom Provider

import { NotificationProvider, AgentEvent, ApprovalEvent, ApprovalResult } from "agent-operator"

class MyProvider implements NotificationProvider {
  name = "my-platform"
  async start() {}
  async stop() {}
  async send(event: AgentEvent) { /* fire-and-forget alert */ }
  async sendWithApproval(event: ApprovalEvent): Promise<ApprovalResult> {
    const approved = await askUser(event)
    return { approved, approvalId: event.approvalId }
  }
}

CLI

npx agent-operator init          # interactive setup
npx agent-operator add-wallet    # add wallet to existing config
npx agent-operator status        # show wallets, balances, today's spend

API

const operator = await createOperator()        // reads ./agent-operator.json
const operator = await createOperator(path)    // custom config path

await operator.pay(walletName, { service, chain, maxBudget })
await operator.getBalance(walletName, chain)
await operator.closeSession(walletName, sessionId)
operator.getWalletNames()
await operator.shutdown()

How It Works

agent code
    |
    v
agent-operator SDK (in-process)
    +-- Connectors
    |     +-- TempoConnector   (mppx session + OWS signing)
    |     +-- BaseConnector    (custom mppx method + OWS EVM signing)
    |     +-- SolanaConnector  (@solana/mpp + OWS Ed25519 signing)
    |
    +-- Policy Engine
    |     +-- daily-limit, session-cap, high-value-gate
    |     +-- new-counterparty-hold, low-balance-alert
    |
    +-- Notification Engine
          +-- TelegramProvider (grammy long-polling)
          +-- [custom providers]

No server. No KV. No separate process.

Dependencies