agent-operator 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# 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
+
+```bash
+npm install agent-operator
+```
+
+## Quick Start
+
+```bash
+# interactive setup — creates agent-operator.json
+npx agent-operator init
+```
+
+```typescript
+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:
+
+```json
+{
+  "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](https://grammy.dev) 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
+
+```typescript
+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
+
+```bash
+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
+
+```typescript
+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
+
+| Package | Role |
+|---------|------|
+| `@open-wallet-standard/core` | Wallet management, signing, policies |
+| `mppx` | MPP protocol client (Tempo built-in) |
+| `@solana/mpp` | Solana MPP implementation |
+| `grammy` | Telegram bot for notifications |

package/dist/cli/add-wallet.d.ts

@@ -0,0 +1 @@
+export declare function addWallet(): Promise<void>;

package/dist/cli/add-wallet.js

@@ -0,0 +1,15 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const CONFIG_FILE = "agent-operator.json";
+export async function addWallet() {
+    const configPath = resolve(process.cwd(), CONFIG_FILE);
+    if (!existsSync(configPath)) {
+        console.log(`No ${CONFIG_FILE} found. Run 'agent-operator init' first.`);
+        process.exit(1);
+    }
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    // re-use the init wallet prompt flow
+    const { init } = await import("./init.js");
+    // the init flow handles adding to existing config
+    await init();
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+const command = process.argv[2];
+async function main() {
+    switch (command) {
+        case "init": {
+            const { init } = await import("./init.js");
+            await init();
+            break;
+        }
+        case "add-wallet": {
+            const { addWallet } = await import("./add-wallet.js");
+            await addWallet();
+            break;
+        }
+        case "status": {
+            const { status } = await import("./status.js");
+            await status();
+            break;
+        }
+        default:
+            console.log(`agent-operator - governed AI agent payments\n`);
+            console.log(`Commands:`);
+            console.log(`  init         Interactive setup — creates agent-operator.json`);
+            console.log(`  add-wallet   Add a wallet to existing config`);
+            console.log(`  status       Show all wallets, balances, today's spend`);
+            console.log(`\nUsage: npx agent-operator <command>`);
+            break;
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+export {};

package/dist/cli/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/cli/init.js

@@ -0,0 +1,200 @@
+import prompts from "prompts";
+import { writeFileSync, existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+const CONFIG_FILE = "agent-operator.json";
+async function promptWallet() {
+    const { name } = await prompts({
+        type: "text",
+        name: "name",
+        message: "Wallet name",
+        validate: (v) => (v.length > 0 ? true : "Name is required"),
+    });
+    if (!name)
+        return null;
+    const { chains } = await prompts({
+        type: "multiselect",
+        name: "chains",
+        message: "Chains (space to select)",
+        choices: [
+            { title: "base", value: "base" },
+            { title: "solana", value: "solana" },
+            { title: "tempo", value: "tempo" },
+        ],
+        min: 1,
+    });
+    if (!chains || chains.length === 0)
+        return null;
+    const policies = await prompts([
+        {
+            type: "number",
+            name: "dailyLimit",
+            message: "Daily spend limit ($)",
+            initial: 50,
+        },
+        {
+            type: "number",
+            name: "sessionCap",
+            message: "Session cap ($)",
+            initial: 5,
+        },
+        {
+            type: "confirm",
+            name: "newCounterpartyHold",
+            message: "Hold new counterparties for approval?",
+            initial: true,
+        },
+        {
+            type: "number",
+            name: "lowBalanceThreshold",
+            message: "Low balance threshold ($)",
+            initial: 10,
+        },
+        {
+            type: "number",
+            name: "highValueThreshold",
+            message: "High value threshold ($)",
+            initial: 200,
+        },
+    ]);
+    const { provider } = await prompts({
+        type: "select",
+        name: "provider",
+        message: "Notification provider",
+        choices: [
+            { title: "Telegram", value: "telegram" },
+            { title: "Webhook", value: "webhook" },
+        ],
+    });
+    if (provider === undefined)
+        return null;
+    let notifications;
+    if (provider === "telegram") {
+        const tg = await prompts([
+            {
+                type: "password",
+                name: "botToken",
+                message: "Telegram bot token",
+            },
+            {
+                type: "text",
+                name: "chatId",
+                message: "Telegram chat ID",
+            },
+        ]);
+        notifications = {
+            provider: "telegram",
+            botToken: tg.botToken,
+            chatId: tg.chatId,
+        };
+    }
+    else {
+        const wh = await prompts([
+            {
+                type: "text",
+                name: "url",
+                message: "Webhook URL",
+            },
+            {
+                type: "password",
+                name: "secret",
+                message: "Webhook secret (optional)",
+            },
+        ]);
+        notifications = {
+            provider: "webhook",
+            url: wh.url,
+            secret: wh.secret || undefined,
+        };
+    }
+    // try to create/find OWS wallet
+    let walletId = "";
+    try {
+        const ows = await import("@open-wallet-standard/core");
+        console.log(`\nChecking for OWS wallet "${name}"...`);
+        try {
+            const existing = ows.getWallet(name);
+            walletId = existing.id;
+            console.log(`  → Found existing wallet: ${walletId}`);
+        }
+        catch {
+            console.log(`  → Not found. Creating wallet via OWS...`);
+            const created = ows.createWallet(name);
+            walletId = created.id;
+            console.log(`  ✅ Wallet created: ${name} (id: ${walletId})`);
+            // generate API key
+            try {
+                const apiKey = ows.createApiKey(name, [walletId], [], "");
+                console.log(`  ✅ API key generated: ${apiKey.id}`);
+            }
+            catch {
+                console.log(`  ⚠️  Could not generate API key — set up manually`);
+            }
+        }
+    }
+    catch {
+        console.log(`\n⚠️  OWS not available. Enter wallet ID manually.`);
+        const { id } = await prompts({
+            type: "text",
+            name: "id",
+            message: "OWS wallet ID",
+        });
+        walletId = id || "PLACEHOLDER";
+    }
+    return {
+        name,
+        wallet: {
+            walletId,
+            chains,
+            policies: {
+                dailyLimit: policies.dailyLimit,
+                sessionCap: policies.sessionCap,
+                newCounterpartyHold: policies.newCounterpartyHold,
+                lowBalanceThreshold: policies.lowBalanceThreshold,
+                highValueThreshold: policies.highValueThreshold,
+            },
+            notifications,
+        },
+    };
+}
+export async function init() {
+    console.log("\nWelcome to agent-operator setup.\n");
+    const configPath = resolve(process.cwd(), CONFIG_FILE);
+    let config = { wallets: {} };
+    if (existsSync(configPath)) {
+        const { action } = await prompts({
+            type: "select",
+            name: "action",
+            message: `${CONFIG_FILE} already exists`,
+            choices: [
+                { title: "Overwrite", value: "overwrite" },
+                { title: "Add wallet to existing", value: "add" },
+                { title: "Cancel", value: "cancel" },
+            ],
+        });
+        if (action === "cancel")
+            return;
+        if (action === "add") {
+            config = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+    }
+    let addMore = true;
+    while (addMore) {
+        const result = await promptWallet();
+        if (!result)
+            break;
+        config.wallets[result.name] = result.wallet;
+        const { more } = await prompts({
+            type: "confirm",
+            name: "more",
+            message: "Add another wallet?",
+            initial: false,
+        });
+        addMore = more;
+    }
+    if (Object.keys(config.wallets).length === 0) {
+        console.log("\nNo wallets configured. Exiting.");
+        return;
+    }
+    writeFileSync(configPath, JSON.stringify(config, null, 2));
+    console.log(`\n✅ Config written: ${configPath}`);
+}

package/dist/cli/status.d.ts

@@ -0,0 +1 @@
+export declare function status(): Promise<void>;

package/dist/cli/status.js

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getSpendSummary, getCounterparties } from "../spend/tracker.js";
+const CONFIG_FILE = "agent-operator.json";
+export async function status() {
+    const configPath = resolve(process.cwd(), CONFIG_FILE);
+    if (!existsSync(configPath)) {
+        console.log(`No ${CONFIG_FILE} found. Run 'agent-operator init' first.`);
+        process.exit(1);
+    }
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    console.log("\n📊 agent-operator status\n");
+    for (const [name, wallet] of Object.entries(config.wallets)) {
+        const summary = getSpendSummary(name);
+        const counterparties = getCounterparties(name);
+        console.log(`  ${name}`);
+        console.log(`  ├── wallet: ${wallet.walletId}`);
+        console.log(`  ├── chains: ${wallet.chains.join(", ")}`);
+        console.log(`  ├── spent today: $${summary.spent.toFixed(2)}${wallet.policies.dailyLimit ? ` / $${wallet.policies.dailyLimit}` : ""}`);
+        console.log(`  ├── sessions today: ${summary.sessionCount}`);
+        console.log(`  ├── known counterparties: ${counterparties.length > 0 ? counterparties.join(", ") : "none"}`);
+        console.log(`  └── notification: ${wallet.notifications.provider}`);
+        console.log();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+import type { PoliciesConfig } from "./policies/types.js";
+import type { AlertsConfig } from "./notifications/types.js";
+export interface WalletConfig {
+    walletId: string;
+    chains: string[];
+    policies: PoliciesConfig;
+    notifications: NotificationConfig;
+}
+export interface NotificationConfig {
+    provider: string;
+    alerts?: AlertsConfig;
+    [key: string]: unknown;
+}
+export interface OperatorConfig {
+    wallets: Record<string, WalletConfig>;
+    connectors?: Record<string, string>;
+}
+export declare function loadConfig(configPath?: string): OperatorConfig;

package/dist/config.js

@@ -0,0 +1,57 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+const DEFAULT_ALERTS = {
+    lowBalance: true,
+    highValueTx: true,
+    newCounterparty: true,
+    policyDenied: true,
+    dailySummary: true,
+    sessionOpened: false,
+};
+export function loadConfig(configPath) {
+    const filePath = configPath ?? resolve(process.cwd(), "agent-operator.json");
+    if (!existsSync(filePath)) {
+        throw new Error(`Config not found at ${filePath}. Run 'npx agent-operator init' to create one.`);
+    }
+    const raw = readFileSync(filePath, "utf-8");
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in ${filePath}`);
+    }
+    validateConfig(config);
+    applyDefaults(config);
+    return config;
+}
+function validateConfig(config) {
+    if (!config.wallets || typeof config.wallets !== "object") {
+        throw new Error("Config must have a 'wallets' object");
+    }
+    const validChains = ["base", "solana", "tempo"];
+    for (const [name, wallet] of Object.entries(config.wallets)) {
+        if (!wallet.walletId) {
+            throw new Error(`Wallet '${name}' is missing 'walletId'`);
+        }
+        if (!Array.isArray(wallet.chains) || wallet.chains.length === 0) {
+            throw new Error(`Wallet '${name}' must have at least one chain`);
+        }
+        for (const chain of wallet.chains) {
+            if (!validChains.includes(chain)) {
+                throw new Error(`Wallet '${name}' has unknown chain '${chain}'. Valid: ${validChains.join(", ")}`);
+            }
+        }
+        if (!wallet.notifications?.provider) {
+            throw new Error(`Wallet '${name}' is missing notification provider`);
+        }
+    }
+}
+function applyDefaults(config) {
+    for (const wallet of Object.values(config.wallets)) {
+        wallet.notifications.alerts = {
+            ...DEFAULT_ALERTS,
+            ...wallet.notifications.alerts,
+        };
+    }
+}

package/dist/connectors/base.d.ts

@@ -0,0 +1,12 @@
+import type { Connector, Session, SessionResult, Balance } from "./types.js";
+export declare class BaseConnector 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/base.js

@@ -0,0 +1,119 @@
+import { Mppx } from "mppx/client";
+import { Method, Credential } from "mppx";
+import { signTransaction, getWallet } from "@open-wallet-standard/core";
+// Base chain ID for EIP-155
+const BASE_CHAIN_ID = "eip155:8453";
+export class BaseConnector {
+    chain = "base";
+    sessions = new Map();
+    async openSession(params) {
+        const { service, maxBudget, walletId } = params;
+        const wallet = getWallet(walletId);
+        const baseAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155"));
+        if (!baseAccount) {
+            throw new Error(`Wallet '${walletId}' has no EVM account for Base`);
+        }
+        // define a custom charge method for Base
+        const baseChargeMethod = Method.from({
+            name: "base",
+            intent: "charge",
+            schema: {
+                credential: {
+                    payload: {
+                        "~standard": { version: 1 },
+                        parse: (v) => v,
+                    },
+                },
+                request: {
+                    "~standard": { version: 1 },
+                    parse: (v) => v,
+                },
+            },
+        });
+        const clientMethod = Method.toClient(baseChargeMethod, {
+            async createCredential({ challenge }) {
+                // sign the payment via OWS (policies enforced here)
+                const txData = JSON.stringify({
+                    challengeId: challenge.id,
+                    from: baseAccount.address,
+                    amount: challenge.request?.amount,
+                    chain: "base",
+                });
+                const result = signTransaction(walletId, BASE_CHAIN_ID, txData);
+                return Credential.serialize({
+                    challenge,
+                    payload: { signature: result.signature },
+                    source: `did:pkh:eip155:8453:${baseAccount.address}`,
+                });
+            },
+        });
+        const mppxClient = Mppx.create({
+            methods: [clientMethod],
+        });
+        // initiate the 402 flow
+        const response = await mppxClient.fetch(service, {
+            headers: { "X-Max-Budget": String(maxBudget) },
+        });
+        const sessionId = crypto.randomUUID();
+        this.sessions.set(sessionId, {
+            sessionId,
+            service,
+            maxBudget,
+            spent: 0,
+            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.spent,
+            refund: session.maxBudget - session.spent,
+        };
+    }
+    async getBalance(walletId) {
+        const wallet = getWallet(walletId);
+        const baseAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155"));
+        if (!baseAccount) {
+            return { chain: this.chain, amount: 0, currency: "USDC" };
+        }
+        try {
+            const { createPublicClient, http, parseAbi, formatUnits } = await import("viem");
+            const { base } = await import("viem/chains");
+            const client = createPublicClient({
+                chain: base,
+                transport: http(),
+            });
+            // USDC on Base
+            const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+            const balance = await client.readContract({
+                address: USDC_ADDRESS,
+                abi: parseAbi([
+                    "function balanceOf(address) view returns (uint256)",
+                ]),
+                functionName: "balanceOf",
+                args: [baseAccount.address],
+            });
+            return {
+                chain: this.chain,
+                amount: Number(formatUnits(balance, 6)),
+                currency: "USDC",
+            };
+        }
+        catch {
+            return { chain: this.chain, amount: 0, currency: "USDC" };
+        }
+    }
+}

package/dist/connectors/solana.d.ts

@@ -0,0 +1,12 @@
+import type { Connector, Session, SessionResult, Balance } from "./types.js";
+export declare class SolanaConnector 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>;
+}