@stablechain/agent-wallet-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# Agent wallet CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `agent-wallet` executable manages the local agent signer, grants, payments, and recovery on Stable Testnet. Wallet protocol code comes from its declared `@stablechain/agent-wallet-sdk` dependency.
+
+Install with Node.js 22 or newer:
+
+```sh
+npm install --global @stablechain/agent-wallet-cli@0.1.0
+agent-wallet --help
+```
+
+Or run directly:
+
+```sh
+npx --yes --package=@stablechain/agent-wallet-cli@0.1.0 agent-wallet --help
+```
+
+Each agent initializes its own signer and imports owner-provided public wallet settings. Set `WALLET_STATE_DIR` to a persistent private directory, especially in containers:
+
+```sh
+agent-wallet init --json
+agent-wallet config import --file ./wallet-config.json --json
+agent-wallet whoami --json
+agent-wallet grants link --recipient "$RECIPIENT" --budget 0.01 --expires-in 24h --json
+```
+
+The owner reviews the approval link, authorizes the grant, and funds the agent's gas through the approval UI. The CLI does not activate the owner's account or read the owner's key. Payments require a stable payment ID; recover an uncertain submission by reusing that ID and its saved journal. See the [CLI reference](https://github.com/stablelabs/agentic.stable.xyz/blob/main/docs/cli.md) for the command surface, JSON output, permissions, and recovery workflow.
+
+For repository development:
+
+```sh
+npm run build:sdk
+npm run build --workspace @stablechain/agent-wallet-cli
+npm run wallet -- --help
+npm run test --workspace @stablechain/agent-wallet-cli
+```
+
+The package compiles its own `src` into `dist`, exposes `dist/main.js` as the executable, and exports Node-only services through `@stablechain/agent-wallet-cli/agent` for the repository's compatibility scripts. It does not copy SDK source or bundle private signing state.
+
+The public npm package includes compiled JavaScript, declarations, this README, and its manifest. The prepack hook rebuilds the package before packing or publishing. The SDK is a separate public dependency; React and the repository's build tools are not runtime dependencies.

package/dist/agent/context.d.ts

@@ -0,0 +1,37 @@
+import type { Hex } from 'viem';
+import { type WalletConfig, type PublicClient } from '@stablechain/agent-wallet-sdk/protocol';
+import { StateStore } from './state.js';
+export declare class AgentContext {
+    readonly state: StateStore;
+    constructor(directory?: string);
+    config(): Promise<WalletConfig>;
+    public(): Promise<{
+        config: WalletConfig;
+        client: PublicClient;
+    }>;
+    verify(client: PublicClient, config: WalletConfig): Promise<void>;
+    identity(): Promise<`0x${string}`>;
+    account(): Promise<{
+        address: import("viem").Address;
+        nonceManager?: import("viem").NonceManager | undefined;
+        sign: (parameters: {
+            hash: import("viem").Hash;
+        }) => Promise<Hex>;
+        signAuthorization: (parameters: import("viem").AuthorizationRequest) => Promise<import("viem/accounts").SignAuthorizationReturnType>;
+        signMessage: ({ message }: {
+            message: import("viem").SignableMessage;
+        }) => Promise<Hex>;
+        signTransaction: <serializer extends import("viem").SerializeTransactionFn<import("viem").TransactionSerializable> = import("viem").SerializeTransactionFn<import("viem").TransactionSerializable>, transaction extends Parameters<serializer>[0] = Parameters<serializer>[0]>(transaction: transaction, options?: {
+            serializer?: serializer | undefined;
+        } | undefined) => Promise<Hex>;
+        signTypedData: <const typedData extends import("viem").TypedData | Record<string, unknown>, primaryType extends keyof typedData | "EIP712Domain" = keyof typedData>(parameters: import("viem").TypedDataDefinition<typedData, primaryType>) => Promise<Hex>;
+        publicKey: Hex;
+        source: "privateKey";
+        type: "local";
+    }>;
+    init(): Promise<{
+        address: `0x${string}`;
+        retained: boolean;
+        stateDir: string;
+    }>;
+}

package/dist/agent/context.js

@@ -0,0 +1,66 @@
+import { resolve } from 'node:path';
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import { address, validateConfig, publicClient, verifyAccount, WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+import { StateStore } from './state.js';
+export class AgentContext {
+    state;
+    constructor(directory = process.env.WALLET_STATE_DIR || resolve(process.cwd(), '.agent-wallet')) { this.state = new StateStore(directory); }
+    async config() {
+        if (!await this.state.has('config.json'))
+            throw new WalletError('CONFIG_REQUIRED', 'Import operator-provided public settings with config import --file FILE.');
+        try {
+            return validateConfig(await this.state.read('config.json'));
+        }
+        catch (error) {
+            if (error instanceof WalletError)
+                throw error;
+            throw new WalletError('INVALID_CONFIG', 'Invalid wallet configuration.');
+        }
+    }
+    async public() { const config = await this.config(); return { config, client: publicClient(config.rpcUrl) }; }
+    async verify(client, config) {
+        try {
+            await verifyAccount(client, config);
+        }
+        catch (error) {
+            if (error instanceof Error && error.constructor === Error)
+                throw new WalletError('ACCOUNT_NOT_VERIFIED', error.message);
+            throw error;
+        }
+    }
+    async identity() {
+        if (!await this.state.has('agent-key.json'))
+            throw new WalletError('AGENT_REQUIRED', 'Run agent-wallet init first.');
+        const record = await this.state.read('agent-key.json');
+        try {
+            return address(record.address, 'agent address');
+        }
+        catch {
+            throw new WalletError('INVALID_KEY_RECORD', 'Agent key record has no valid public address.');
+        }
+    }
+    async account() {
+        const record = await this.state.read('agent-key.json');
+        try {
+            if (!/^0x[0-9a-fA-F]{64}$/.test(record.privateKey))
+                throw new Error();
+            const account = privateKeyToAccount(record.privateKey);
+            if (account.address !== record.address)
+                throw new Error();
+            return account;
+        }
+        catch {
+            throw new WalletError('INVALID_KEY_RECORD', 'Agent key record is invalid or its address differs. Retain it for recovery.');
+        }
+    }
+    async init() {
+        return this.state.lock(async () => {
+            if (await this.state.has('agent-key.json'))
+                return { address: (await this.account()).address, retained: true, stateDir: this.state.directory };
+            const privateKey = generatePrivateKey();
+            const account = privateKeyToAccount(privateKey);
+            await this.state.write('agent-key.json', { privateKey, address: account.address, createdAt: new Date().toISOString() });
+            return { address: account.address, retained: false, stateDir: this.state.directory };
+        });
+    }
+}

package/dist/agent/grants.d.ts

@@ -0,0 +1,17 @@
+import { type GrantDraft } from '@stablechain/agent-wallet-sdk/protocol';
+import type { AgentContext } from './context.js';
+export declare function grantLink(ctx: AgentContext, opt: Record<string, string | boolean | undefined>): Promise<{
+    grantId: `0x${string}`;
+    approvalUrl: string;
+    terms: GrantDraft;
+    status: string;
+    submitted: boolean;
+}>;
+export declare function waitGrant(ctx: AgentContext, idText: string, timeout?: number): Promise<{
+    id: `0x${string}`;
+    grant: import("@stablechain/agent-wallet-sdk/protocol").Grant;
+    status: string;
+    remainingBudget: bigint;
+    block: bigint;
+    timestamp: bigint;
+}>;

package/dist/agent/grants.js

@@ -0,0 +1,55 @@
+import { formatAmount, address, identifier, parseGrantDraft, readGrant, duration, input, WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+import { newId } from './state.js';
+export async function grantLink(ctx, opt) {
+    return ctx.state.lock(async () => {
+        const config = await ctx.config();
+        const id = input(() => identifier(String(opt['grant-id'] || newId())));
+        const path = `grant-draft-${id}.json`;
+        const previous = await ctx.state.has(path) ? await ctx.state.read(path) : undefined;
+        if (Boolean(opt.expires) === Boolean(opt['expires-in']))
+            throw new WalletError('INVALID_INPUT', 'Supply exactly one of --expires or --expires-in.', 2);
+        if (!opt.recipient || !opt.budget)
+            throw new WalletError('INVALID_INPUT', '--recipient and --budget are required.', 2);
+        const expiresIn = opt['expires-in'] ? String(opt['expires-in']) : undefined;
+        const expires = opt.expires ? String(opt.expires) : previous && previous.expiresIn === expiresIn ? previous.draft.expires : new Date(Date.now() + duration(expiresIn, 'expiry duration')).toISOString().replace(/\.\d{3}Z$/, 'Z');
+        const agent = opt.agent ? input(() => address(String(opt.agent))) : await ctx.identity();
+        const draft = { id, agent, recipient: String(opt.recipient), budget: String(opt.budget), expires };
+        const terms = input(() => parseGrantDraft(draft, config.alice, previous ? 0n : BigInt(Math.floor(Date.now() / 1000))));
+        draft.agent = terms.agent;
+        draft.recipient = terms.recipient;
+        draft.budget = formatAmount(terms.budget);
+        if (previous && (previous.alice !== config.alice || JSON.stringify(previous.draft) !== JSON.stringify(draft) || previous.expiresIn !== expiresIn))
+            throw new WalletError('GRANT_DRAFT_MISMATCH', 'Grant ID is already bound to different terms.', 2);
+        if (!previous)
+            await ctx.state.write(path, { schemaVersion: 1, alice: config.alice, draft, ...(expiresIn ? { expiresIn } : {}) });
+        const link = new URL(config.approvalUrl);
+        for (const [key, value] of Object.entries({ newGrant: id, agent: draft.agent, recipient: draft.recipient, budget: draft.budget, expires: draft.expires }))
+            link.searchParams.set(key, value);
+        return { grantId: id, approvalUrl: link.href, terms: draft, status: 'awaiting_owner', submitted: false };
+    });
+}
+export async function waitGrant(ctx, idText, timeout = 300_000) {
+    const id = input(() => identifier(idText));
+    const { config, client } = await ctx.public();
+    await ctx.verify(client, config);
+    const saved = await ctx.state.has(`grant-draft-${id}.json`) ? await ctx.state.read(`grant-draft-${id}.json`) : undefined;
+    const deadline = Date.now() + timeout;
+    while (true) {
+        const row = await readGrant(client, config, id);
+        if (row.grant.status !== 0 && saved) {
+            const terms = input(() => parseGrantDraft(saved.draft, config.alice, 0n)), g = row.grant;
+            if (saved.alice !== config.alice || terms.agent !== g.agent || terms.recipient !== g.recipient || terms.budget !== g.budget || terms.expiresAt !== g.expiresAt)
+                throw new WalletError('GRANT_TERMS_MISMATCH', 'Onchain grant differs from the saved approval terms.', 4, row);
+        }
+        if (row.status === 'Active') {
+            if (row.grant.agent !== await ctx.identity())
+                throw new WalletError('WRONG_SIGNER', 'Grant belongs to a different agent.', 4, row);
+            return row;
+        }
+        if (!['Unknown', 'Pending'].includes(row.status))
+            throw new WalletError('GRANT_NOT_PAYABLE', `Grant is ${row.status}.`, 4, row);
+        if (Date.now() >= deadline)
+            throw new WalletError('GRANT_WAIT_TIMEOUT', 'Authorization is still pending. Check the same grant ID later.', 6, row);
+        await new Promise(resolve => setTimeout(resolve, Math.min(1000, deadline - Date.now())));
+    }
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,5 @@
+export * from './context.js';
+export * from './state.js';
+export * from './grants.js';
+export * from './payments.js';
+export { publicError, json } from '../output.js';

package/dist/agent/index.js

@@ -0,0 +1,6 @@
+// Node-only services shared with the repository's compatibility/operator adapters.
+export * from './context.js';
+export * from './state.js';
+export * from './grants.js';
+export * from './payments.js';
+export { publicError, json } from '../output.js';

package/dist/agent/payments.d.ts

@@ -0,0 +1,138 @@
+import { type Hex } from 'viem';
+import { type WaitOptions } from '@stablechain/agent-wallet-sdk/protocol';
+import type { AgentContext } from './context.js';
+export type PaymentJournal = {
+    schemaVersion?: 1;
+    kind: 'payment';
+    id: Hex;
+    intent: Record<string, string>;
+    context?: {
+        chainId: 2201;
+        token: string;
+        implementation: string;
+        implementationCodeHash: string;
+    };
+    raw?: Hex;
+    hash?: Hex;
+    confirmedHash?: Hex;
+    nonce?: string;
+    status: 'created' | 'signed' | 'submitted' | 'confirmed' | 'reverted' | 'rejected';
+    block?: string;
+    feeAtomic?: string;
+};
+export type PaymentInput = {
+    paymentId?: string;
+    grant?: string;
+    recipient?: string;
+    amount?: string;
+};
+export declare const paymentFilename: (id: string) => string;
+export declare function paymentView(j: PaymentJournal): {
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    status: "submitted" | "created" | "signed" | "confirmed" | "reverted" | "rejected";
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    block: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+};
+export declare function loadPayment(ctx: AgentContext, id: string): Promise<PaymentJournal>;
+export declare function preparePayment(ctx: AgentContext, options: PaymentInput): Promise<{
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    status: "submitted" | "created" | "signed" | "confirmed" | "reverted" | "rejected";
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    block: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+}>;
+export declare function waitPayment(ctx: AgentContext, id: string, options?: WaitOptions): Promise<{
+    success: boolean;
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    status: "submitted" | "created" | "signed" | "confirmed" | "reverted" | "rejected";
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    block: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+} | {
+    status: string;
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    block: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+}>;
+export declare function pay(ctx: AgentContext, options: PaymentInput & {
+    dryRun?: boolean;
+    noWait?: boolean;
+    timeout?: number;
+}): Promise<{
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    status: "submitted" | "created" | "signed" | "confirmed" | "reverted" | "rejected";
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    block: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+} | {
+    signed: boolean;
+    submitted: boolean;
+    to: `0x${string}`;
+    data: `0x${string}`;
+    gas: bigint;
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
+    block: bigint;
+    status: string;
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+}>;
+export declare function listPayments(ctx: AgentContext): Promise<{
+    paymentId: `0x${string}`;
+    intent: Record<string, string>;
+    amount: string;
+    amountAtomic: string;
+    tokenDecimals: number;
+    status: "submitted" | "created" | "signed" | "confirmed" | "reverted" | "rejected";
+    transactionHash: `0x${string}` | undefined;
+    nonce: string | undefined;
+    block: string | undefined;
+    feeAtomic: string | undefined;
+    nativeDecimals: number;
+    explorer: string | undefined;
+}[]>;

package/dist/agent/payments.js

@@ -0,0 +1,236 @@
+import { BaseError, ContractFunctionRevertedError, createWalletClient, encodeFunctionData, formatUnits, http, keccak256, parseTransaction, recoverTransactionAddress } from 'viem';
+import { walletAbi, tokenAbi, address, chain, CHAIN_ID, identifier, TOKEN, formatAmount, parseAmount, paymentCheck, trackTransaction, verifyNetwork, input, WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+import { newId } from './state.js';
+export const paymentFilename = (id) => `payment-${input(() => identifier(id))}.json`;
+const paymentData = (j) => encodeFunctionData({ abi: walletAbi, functionName: 'pay', args: [identifier(j.intent.grantId), j.id, address(j.intent.recipient), BigInt(j.intent.amount)] });
+const check = (j) => paymentCheck(address(j.intent.alice), identifier(j.intent.grantId), j.id, address(j.intent.recipient), BigInt(j.intent.amount));
+export function paymentView(j) {
+    return { paymentId: j.id, intent: j.intent, amount: formatAmount(BigInt(j.intent.amount)), amountAtomic: j.intent.amount, tokenDecimals: 6, status: j.status, transactionHash: j.confirmedHash ?? j.hash, nonce: j.nonce, block: j.block, feeAtomic: j.feeAtomic, nativeDecimals: 18, explorer: j.hash ? `${chain.blockExplorers.default.url}/tx/${j.confirmedHash ?? j.hash}` : undefined };
+}
+export async function loadPayment(ctx, id) {
+    const filename = paymentFilename(id);
+    if (!await ctx.state.has(filename))
+        throw new WalletError('PAYMENT_NOT_FOUND', 'No saved payment with this ID. Retain existing journals for recovery.');
+    const j = await ctx.state.read(filename);
+    try {
+        if (j.kind !== 'payment' || j.id !== identifier(id) || j.schemaVersion !== undefined && j.schemaVersion !== 1 || !['created', 'signed', 'submitted', 'confirmed', 'reverted', 'rejected'].includes(j.status))
+            throw new Error();
+        address(j.intent.alice);
+        address(j.intent.agent);
+        identifier(j.intent.grantId);
+        address(j.intent.recipient);
+        if (!/^\d+$/.test(j.intent.amount) || BigInt(j.intent.amount) <= 0n || BigInt(j.intent.amount) >= 2n ** 256n)
+            throw new Error();
+        if (j.confirmedHash)
+            identifier(j.confirmedHash);
+        if (j.raw) {
+            const tx = parseTransaction(j.raw);
+            if (keccak256(j.raw) !== j.hash || tx.chainId !== CHAIN_ID || tx.to?.toLowerCase() !== j.intent.alice.toLowerCase() || tx.data !== paymentData(j) || (tx.value ?? 0n) !== 0n || (await recoverTransactionAddress({ serializedTransaction: j.raw })).toLowerCase() !== j.intent.agent.toLowerCase())
+                throw new Error();
+            if (j.nonce !== undefined && j.nonce !== String(tx.nonce))
+                throw new Error();
+            j.nonce = String(tx.nonce);
+        }
+        else if (j.hash || j.confirmedHash || ['signed', 'submitted', 'confirmed', 'reverted'].includes(j.status))
+            throw new Error();
+    }
+    catch {
+        throw new WalletError('INVALID_PAYMENT_JOURNAL', 'Payment journal or signed transaction differs from its saved intent. Retain it for inspection.');
+    }
+    return j;
+}
+async function intent(ctx, options, persist) {
+    const config = await ctx.config(), agent = await ctx.identity();
+    const id = input(() => identifier(options.paymentId || newId()));
+    const old = await ctx.state.has(paymentFilename(id)) ? await loadPayment(ctx, id) : undefined;
+    const grantId = options.grant ? input(() => identifier(options.grant)) : old?.intent.grantId;
+    const recipient = options.recipient ? input(() => address(options.recipient)) : old?.intent.recipient;
+    const amount = options.amount ? String(input(() => parseAmount(options.amount))) : old?.intent.amount;
+    if (!grantId || !recipient || !amount)
+        throw new WalletError('INVALID_INPUT', 'An unsaved payment requires --grant, --recipient, and --amount.', 2);
+    const normalized = { alice: config.alice, agent, grantId, recipient, amount };
+    if (old && (Object.entries(normalized).some(([key, value]) => old.intent[key] !== value) || old.context && (old.context.chainId !== CHAIN_ID || old.context.token !== TOKEN || old.context.implementation !== config.implementation || old.context.implementationCodeHash !== config.implementationCodeHash)))
+        throw new WalletError('PAYMENT_TERMS_MISMATCH', 'Payment ID is already bound to different terms or account configuration.', 2);
+    const j = old ?? { schemaVersion: 1, kind: 'payment', id, intent: normalized, context: { chainId: CHAIN_ID, token: TOKEN, implementation: config.implementation, implementationCodeHash: config.implementationCodeHash }, status: 'created' };
+    if (!old && persist)
+        await ctx.state.write(paymentFilename(id), j);
+    return { journal: j, config };
+}
+export async function preparePayment(ctx, options) {
+    return ctx.state.lock(async () => paymentView((await intent(ctx, options, true)).journal));
+}
+async function preflight(ctx, client, config, j) {
+    await ctx.verify(client, config);
+    if (await client.readContract({ address: config.alice, abi: walletAbi, functionName: 'paymentUsed', args: [j.id] }))
+        throw new WalletError('PAYMENT_ID_CONSUMED_UNVERIFIED', 'Payment ID has already been consumed. A matching receipt is required to prove its terms.', 4, paymentView(j));
+    const agent = address(j.intent.agent), recipient = address(j.intent.recipient), amount = BigInt(j.intent.amount);
+    const [tokenBalance, nativeBalance] = await Promise.all([
+        client.readContract({ address: TOKEN, abi: tokenAbi, functionName: 'balanceOf', args: [config.alice] }),
+        client.getBalance({ address: agent }),
+    ]);
+    if (tokenBalance < amount)
+        throw new WalletError('INSUFFICIENT_PAYMENT_FUNDS', 'Alice has insufficient USDT0 for this payment.', 4, paymentView(j));
+    try {
+        await client.simulateContract({ account: agent, address: config.alice, abi: walletAbi, functionName: 'pay', args: [identifier(j.intent.grantId), j.id, recipient, amount] });
+    }
+    catch (error) {
+        const revert = error instanceof BaseError ? error.walk(e => e instanceof ContractFunctionRevertedError) : undefined;
+        if (revert instanceof ContractFunctionRevertedError)
+            throw new WalletError(revert.data?.errorName ?? 'PAYMENT_REJECTED', 'Payment rejected by the grant rules before submission.', 4, paymentView(j));
+        throw error;
+    }
+    const block = await client.getBlock();
+    const gasEstimate = await client.estimateGas({ account: agent, to: config.alice, data: paymentData(j) });
+    const gas = gasEstimate + gasEstimate / 5n;
+    const maxFeePerGas = (block.baseFeePerGas ?? await client.getGasPrice()) * 2n;
+    if (nativeBalance < gas * maxFeePerGas)
+        throw new WalletError('INSUFFICIENT_GAS', `Gas payer ${agent} has ${formatUnits(nativeBalance, 18)} native USDT0. Fund this signer separately, then retry the same saved ID.`, 4, paymentView(j));
+    return { to: config.alice, data: paymentData(j), gas, maxFeePerGas, maxPriorityFeePerGas: 0n, block: block.number };
+}
+async function observe(ctx, client, j, options = {}, locked = true) {
+    try {
+        const result = await trackTransaction(client, j.confirmedHash ?? j.hash, check(j), options);
+        j.confirmedHash = result.hash;
+        j.status = result.success ? 'confirmed' : 'reverted';
+        j.block = result.block;
+        j.feeAtomic = result.feeAtomic;
+        if (locked)
+            await ctx.state.write(paymentFilename(j.id), j);
+        else
+            await ctx.state.lock(async () => {
+                const current = await loadPayment(ctx, j.id);
+                if (current.raw !== j.raw)
+                    throw new WalletError('INVALID_PAYMENT_JOURNAL', 'Signed payment changed during observation.');
+                await ctx.state.write(paymentFilename(j.id), j);
+            });
+        if (!result.success)
+            throw new WalletError('PAYMENT_REVERTED', 'Transaction reverted onchain. No payment was committed; network fees may apply.', 7, paymentView(j));
+        return { ...paymentView(j), success: true };
+    }
+    catch (error) {
+        if (error instanceof WalletError)
+            throw error;
+        if (error instanceof Error && error.constructor === Error)
+            throw new WalletError('PAYMENT_UNVERIFIED', error.message, 7, paymentView(j));
+        throw new WalletError('PAYMENT_OUTCOME_UNKNOWN', 'Payment confirmation is unknown. Check or resume the same saved ID.', 6, { ...paymentView(j), status: 'unknown' });
+    }
+}
+async function hasReceipt(client, j) {
+    try {
+        return await client.getTransactionReceipt({ hash: j.confirmedHash ?? j.hash });
+    }
+    catch (error) {
+        if (error.name === 'TransactionReceiptNotFoundError')
+            return undefined;
+        throw error;
+    }
+}
+export async function waitPayment(ctx, id, options = {}) {
+    // Do not hold a mutation lock while polling. Only commit the verified observation.
+    const j = await loadPayment(ctx, id);
+    if (!j.raw)
+        return { ...paymentView(j), status: 'not_submitted' };
+    const { client } = await ctx.public();
+    try {
+        await verifyNetwork(client);
+        return await observe(ctx, client, j, options, false);
+    }
+    catch (error) {
+        if (error instanceof WalletError)
+            throw error;
+        throw new WalletError('PAYMENT_OUTCOME_UNKNOWN', 'Cannot observe the saved transaction. Check the same ID later.', 6, { ...paymentView(j), status: 'unknown' });
+    }
+}
+async function reconcileSigner(ctx, client, j) {
+    for (const filename of await ctx.state.files('payment-')) {
+        const id = filename.slice(8, -5);
+        if (id === j.id)
+            continue;
+        const other = await loadPayment(ctx, id);
+        if (!other.raw || ['confirmed', 'reverted'].includes(other.status) || other.intent.agent !== j.intent.agent)
+            continue;
+        if (await hasReceipt(client, other)) {
+            try {
+                await observe(ctx, client, other);
+            }
+            catch (e) {
+                if (!(e instanceof WalletError) || e.code !== 'PAYMENT_REVERTED')
+                    throw e;
+            }
+        }
+        else
+            throw new WalletError('UNRESOLVED_PAYMENT', 'Resolve the previous signed payment before signing another transaction.', 6, paymentView(other));
+    }
+}
+export async function pay(ctx, options) {
+    if (!options.paymentId)
+        throw new WalletError('PAYMENT_ID_REQUIRED', 'Use --payment-id, or save a new ID with payments prepare first.', 2);
+    const execute = async () => {
+        const { journal: j, config } = await intent(ctx, options, !options.dryRun);
+        const { client } = await ctx.public();
+        if (options.dryRun) {
+            const result = await preflight(ctx, client, config, j);
+            return { ...paymentView(j), status: 'simulated', ...result, signed: false, submitted: false };
+        }
+        if (j.raw) {
+            await verifyNetwork(client);
+            if (await hasReceipt(client, j))
+                return observe(ctx, client, j, { timeout: options.timeout });
+            if (j.status === 'reverted' || j.status === 'confirmed')
+                throw new WalletError('PAYMENT_OUTCOME_UNKNOWN', 'Saved receipt is no longer available. Check the same payment; do not submit a new intent.', 6, paymentView(j));
+        }
+        else {
+            await reconcileSigner(ctx, client, j);
+            let request;
+            try {
+                request = await preflight(ctx, client, config, j);
+            }
+            catch (error) {
+                if (error instanceof WalletError && error.exitCode === 4) {
+                    j.status = 'rejected';
+                    await ctx.state.write(paymentFilename(j.id), j);
+                }
+                throw error;
+            }
+            const account = await ctx.account();
+            const wallet = createWalletClient({ account, chain, transport: http(config.rpcUrl) });
+            const prepared = await wallet.prepareTransactionRequest({ account, chain, to: request.to, data: request.data, gas: request.gas, maxFeePerGas: request.maxFeePerGas, maxPriorityFeePerGas: 0n, nonce: await client.getTransactionCount({ address: account.address, blockTag: 'pending' }) });
+            j.raw = await wallet.signTransaction(prepared);
+            j.hash = keccak256(j.raw);
+            j.nonce = String(prepared.nonce);
+            j.status = 'signed';
+            await ctx.state.write(paymentFilename(j.id), j);
+        }
+        await ctx.verify(client, config);
+        try {
+            await client.sendRawTransaction({ serializedTransaction: j.raw });
+        }
+        catch {
+            try {
+                await client.getTransaction({ hash: j.hash });
+            }
+            catch {
+                throw new WalletError('PAYMENT_OUTCOME_UNKNOWN', 'Submission outcome is unknown. Check or resume the same saved ID.', 6, { ...paymentView(j), status: 'unknown' });
+            }
+        }
+        j.status = 'submitted';
+        await ctx.state.write(paymentFilename(j.id), j);
+        if (options.noWait)
+            return paymentView(j);
+        return observe(ctx, client, j, { timeout: options.timeout });
+    };
+    try {
+        return await (options.dryRun ? execute() : ctx.state.lock(execute));
+    }
+    catch (error) {
+        if (error instanceof WalletError || options.dryRun)
+            throw error;
+        const saved = await ctx.state.has(paymentFilename(options.paymentId)) ? await loadPayment(ctx, options.paymentId) : undefined;
+        if (saved?.raw)
+            throw new WalletError('PAYMENT_OUTCOME_UNKNOWN', 'The signed payment is recoverable. Check or resume the same saved ID.', 6, { ...paymentView(saved), status: 'unknown' });
+        throw error;
+    }
+}
+export async function listPayments(ctx) {
+    return Promise.all((await ctx.state.files('payment-')).map(async (filename) => paymentView(await loadPayment(ctx, filename.slice(8, -5)))));
+}

package/dist/agent/state.d.ts

@@ -0,0 +1,15 @@
+export declare const newId: () => `0x${string}`;
+export declare function exists(path: string): Promise<boolean>;
+export declare function secureDir(path: string, create?: boolean): Promise<void>;
+export declare function readJson<T>(path: string): Promise<T>;
+export declare function saveJson(path: string, value: unknown, publicMetadata?: boolean): Promise<void>;
+export declare class StateStore {
+    readonly directory: string;
+    constructor(directory: string);
+    path(name: string): string;
+    read<T>(name: string): Promise<T>;
+    has(name: string): Promise<boolean>;
+    write(name: string, value: unknown): Promise<void>;
+    files(prefix: string): Promise<string[]>;
+    lock<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/agent/state.js

@@ -0,0 +1,97 @@
+import { lstat, mkdir, open, readFile, readdir, rename, unlink } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+export const newId = () => `0x${randomBytes(32).toString('hex')}`;
+export async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return false;
+        throw e;
+    }
+}
+export async function secureDir(path, create = true) {
+    if (create)
+        await mkdir(path, { recursive: true, mode: 0o700 });
+    const info = await lstat(path);
+    if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o077))
+        throw new WalletError('UNSAFE_STATE', `State directory must be private (chmod 700): ${path}`);
+}
+export async function readJson(path) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o077))
+        throw new WalletError('UNSAFE_STATE', `Local state must be a private regular file (chmod 600): ${path}`);
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new WalletError('INVALID_STATE', `Invalid JSON in ${path}. Retain this file for recovery.`);
+    }
+}
+export async function saveJson(path, value, publicMetadata = false) {
+    if (await exists(path)) {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || (!publicMetadata && (info.mode & 0o077)))
+            throw new WalletError('UNSAFE_STATE', `Refusing to replace unsafe local state: ${path}`);
+    }
+    const temp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+    const file = await open(temp, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value, null, 2) + '\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temp, path);
+    const dir = await open(dirname(path), 'r');
+    try {
+        await dir.sync();
+    }
+    finally {
+        await dir.close();
+    }
+}
+export class StateStore {
+    directory;
+    constructor(directory) { this.directory = resolve(directory); }
+    path(name) {
+        if (!/^[a-zA-Z0-9._-]+$/.test(name))
+            throw new WalletError('INVALID_INPUT', 'Invalid state filename.', 2);
+        return resolve(this.directory, name);
+    }
+    async read(name) { await secureDir(this.directory, false); return readJson(this.path(name)); }
+    async has(name) { return exists(this.path(name)); }
+    async write(name, value) { await secureDir(this.directory, false); await saveJson(this.path(name), value); }
+    async files(prefix) {
+        if (!await exists(this.directory))
+            return [];
+        await secureDir(this.directory, false);
+        return (await readdir(this.directory)).filter(name => name.startsWith(prefix) && name.endsWith('.json')).sort();
+    }
+    async lock(fn) {
+        await secureDir(this.directory);
+        const path = this.path('command.lock');
+        let lock;
+        try {
+            lock = await open(path, 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                throw new WalletError('STATE_LOCKED', `Another wallet command holds ${path}. Verify its process stopped before removing a stale lock.`, 8);
+            throw error;
+        }
+        try {
+            await lock.writeFile(String(process.pid));
+            return await fn();
+        }
+        finally {
+            await lock.close();
+            await unlink(path);
+        }
+    }
+}

package/dist/main.d.ts

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

package/dist/main.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { address, identifier, validateConfig, listGrants, readBalances, readGrant, parseAmount, fundingSuggestion, paymentGasReserve, duration, input, WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+import { AgentContext } from './agent/context.js';
+import { grantLink, waitGrant } from './agent/grants.js';
+import { listPayments, loadPayment, pay, paymentView, preparePayment, waitPayment } from './agent/payments.js';
+import { publicError, render } from './output.js';
+const help = `agent-wallet — Stable Testnet agent payments
+
+  init                              Create or verify a private agent signer
+  whoami                            Show the public agent address
+  config import --file FILE         Import operator-provided public settings
+  config show                       Show public settings
+  status                            Account, balances and unresolved payments
+  doctor                            Diagnose local state and account setup
+  grants link --recipient ADDRESS --budget AMOUNT (--expires UTC | --expires-in 24h)
+              [--agent ADDRESS] [--grant-id ID]
+  grants list [--all-agents] [--status STATUS] [--limit 20] [--cursor CURSOR]
+  grants show ID                    Grant terms and remaining budget
+  grants wait ID [--timeout 300s]    Wait for exact saved authorization
+  gas check --grant ID              Agent gas reserve and funding suggestion
+  payments prepare --grant ID --recipient ADDRESS --amount AMOUNT [--payment-id ID]
+  pay --payment-id ID [--grant ID --recipient ADDRESS --amount AMOUNT]
+      [--dry-run | --no-wait] [--timeout 120s]
+  payments list                     Local payment journals
+  payments show ID                  Inspect without broadcasting
+  payments wait ID [--timeout 120s]  Observe without broadcasting
+  payments resume ID [--no-wait] [--timeout 120s]
+
+Global: --json  --state-dir DIR  --help  --version
+Alice authorizes grants and funds gas through the approval UI.
+`;
+const allowed = {
+    init: [], whoami: [], status: [], doctor: [], 'config show': [], 'config import': ['file'],
+    'grants link': ['recipient', 'budget', 'expires', 'expires-in', 'agent', 'grant-id'],
+    'grants list': ['all-agents', 'status', 'limit', 'cursor'], 'grants show': [], 'grants wait': ['timeout'],
+    'gas check': ['grant'], 'payments prepare': ['grant', 'recipient', 'amount', 'payment-id'],
+    pay: ['grant', 'recipient', 'amount', 'payment-id', 'dry-run', 'no-wait', 'timeout'],
+    'payments list': [], 'payments show': [], 'payments wait': ['timeout'], 'payments resume': ['no-wait', 'timeout'],
+};
+const globalFlags = ['json', 'state-dir', 'help', 'version'];
+const booleans = new Set(['json', 'help', 'version', 'all-agents', 'dry-run', 'no-wait']);
+let command = 'agent-wallet';
+let asJson = process.argv.slice(2).includes('--json');
+try {
+    const names = [...new Set([...globalFlags, ...Object.values(allowed).flat()])];
+    const parsed = input(() => parseArgs({ options: Object.fromEntries(names.map(name => [name, { type: booleans.has(name) ? 'boolean' : 'string' }])), allowPositionals: true, strict: true }));
+    const opt = parsed.values;
+    asJson = Boolean(opt.json);
+    if (opt.help || opt.version || parsed.positionals.length === 0) {
+        const data = opt.version
+            ? JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version
+            : help;
+        render(opt.version ? 'version' : 'help', data, asJson);
+    }
+    else {
+        const positions = [...parsed.positionals];
+        command = positions.shift();
+        if (['config', 'grants', 'gas', 'payments'].includes(command))
+            command += ` ${positions.shift() || ''}`;
+        if (!(command in allowed))
+            throw new WalletError('UNKNOWN_COMMAND', `Unknown command: ${command}. Use --help.`, 2);
+        const positionalCount = ['grants show', 'grants wait', 'payments show', 'payments wait', 'payments resume'].includes(command) ? 1 : 0;
+        if (positions.length !== positionalCount)
+            throw new WalletError('INVALID_INPUT', positionalCount ? 'Supply exactly one full ID.' : 'Unexpected positional argument.', 2);
+        for (const name of Object.keys(opt))
+            if (!globalFlags.includes(name) && !allowed[command].includes(name))
+                throw new WalletError('INVALID_INPUT', `--${name} is not supported by ${command}.`, 2);
+        if (opt['dry-run'] && opt['no-wait'])
+            throw new WalletError('INVALID_INPUT', '--dry-run and --no-wait cannot be combined.', 2);
+        const value = (name) => typeof opt[name] === 'string' ? String(opt[name]) : undefined;
+        const required = (name) => { const result = value(name); if (!result)
+            throw new WalletError('INVALID_INPUT', `Missing --${name}.`, 2); return result; };
+        // Reject syntax and scalar validation errors before creating private state.
+        for (const name of ['grant', 'grant-id', 'payment-id'])
+            if (opt[name])
+                input(() => identifier(required(name)));
+        for (const name of ['recipient', 'agent'])
+            if (opt[name])
+                input(() => address(required(name)));
+        for (const name of ['amount', 'budget'])
+            if (opt[name])
+                input(() => parseAmount(required(name)));
+        if (positionalCount)
+            input(() => identifier(positions[0]));
+        if (command === 'payments prepare')
+            for (const name of ['grant', 'recipient', 'amount'])
+                required(name);
+        if (command === 'grants link') {
+            required('recipient');
+            required('budget');
+            if (Boolean(opt.expires) === Boolean(opt['expires-in']))
+                throw new WalletError('INVALID_INPUT', 'Supply exactly one of --expires or --expires-in.', 2);
+            if (opt['expires-in'])
+                duration(required('expires-in'), 'expiry duration');
+            if (opt.expires)
+                input(() => {
+                    const expiry = required('expires');
+                    if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/.test(expiry) || new Date(expiry).toISOString().replace('.000Z', 'Z') !== expiry)
+                        throw new Error('Expiry must be a valid UTC timestamp.');
+                });
+        }
+        const ctx = new AgentContext(value('state-dir'));
+        const timeout = opt.timeout ? duration(required('timeout'), 'timeout') : undefined;
+        const paymentOptions = { paymentId: value('payment-id'), grant: value('grant'), recipient: value('recipient'), amount: value('amount') };
+        let data;
+        switch (command) {
+            case 'init':
+                data = await ctx.init();
+                break;
+            case 'whoami':
+                data = { address: await ctx.identity(), stateDir: ctx.state.directory };
+                break;
+            case 'config show':
+                data = await ctx.config();
+                break;
+            case 'config import': {
+                const text = await readFile(required('file'), 'utf8');
+                let raw;
+                try {
+                    raw = JSON.parse(text);
+                }
+                catch {
+                    throw new WalletError('INVALID_INPUT', 'Configuration must contain valid public wallet JSON.', 2);
+                }
+                const config = input(() => validateConfig(raw));
+                data = await ctx.state.lock(async () => {
+                    if ((await ctx.state.files('payment-')).length && await ctx.state.has('config.json')) {
+                        const previous = await ctx.config();
+                        if (previous.alice !== config.alice || previous.implementation !== config.implementation || previous.implementationCodeHash !== config.implementationCodeHash || previous.rpcUrl !== config.rpcUrl)
+                            throw new WalletError('CONFIG_IN_USE', 'Payment records bind this directory to its account and RPC. Use a separate state directory.');
+                    }
+                    const { publicClient } = await import('@stablechain/agent-wallet-sdk/protocol');
+                    await ctx.verify(publicClient(config.rpcUrl), config);
+                    await ctx.state.write('config.json', config);
+                    return config;
+                });
+                break;
+            }
+            case 'doctor': {
+                const checks = [];
+                for (const [name, check] of [
+                    ['agent', () => ctx.account()],
+                    ['payments', () => listPayments(ctx)],
+                    ['account', async () => { const { config, client } = await ctx.public(); await ctx.verify(client, config); }],
+                    ['lock', async () => { if (await ctx.state.has('command.lock'))
+                            throw new WalletError('STATE_LOCKED', 'A command lock exists. Verify its process before removing a stale lock.', 8); }],
+                ]) {
+                    try {
+                        await check();
+                        checks.push({ name, ok: true });
+                    }
+                    catch (error) {
+                        const e = publicError(error);
+                        checks.push({ name, ok: false, code: e.code, message: e.message });
+                    }
+                }
+                data = { checks, ready: checks.every(check => check.ok), stateDir: ctx.state.directory };
+                break;
+            }
+            case 'status': {
+                const payments = await listPayments(ctx);
+                const identity = await ctx.state.has('agent-key.json') ? await ctx.identity() : undefined;
+                if (!await ctx.state.has('config.json')) {
+                    data = { configured: false, agent: identity, stateDir: ctx.state.directory, payments };
+                    break;
+                }
+                const { config, client } = await ctx.public();
+                await ctx.verify(client, config);
+                data = { configured: true, verified: true, ...(await readBalances(client, config, identity)), unresolvedPayments: payments.filter(j => !['confirmed', 'reverted', 'rejected'].includes(j.status)), stateDir: ctx.state.directory };
+                break;
+            }
+            case 'grants link':
+                data = await grantLink(ctx, opt);
+                break;
+            case 'grants wait':
+                data = await waitGrant(ctx, positions[0], timeout);
+                break;
+            case 'grants list': {
+                const { config, client } = await ctx.public();
+                await ctx.verify(client, config);
+                if (opt.status && !['unknown', 'pending', 'active', 'rejected', 'revoked', 'expired', 'exhausted'].includes(required('status').toLowerCase()))
+                    throw new WalletError('INVALID_INPUT', 'Unknown grant status.', 2);
+                data = await listGrants(client, config, { agent: opt['all-agents'] ? undefined : await ctx.identity(), limit: opt.limit ? Number(required('limit')) : undefined, cursor: value('cursor'), status: value('status') });
+                break;
+            }
+            case 'grants show': {
+                const id = input(() => identifier(positions[0]));
+                const { config, client } = await ctx.public();
+                await ctx.verify(client, config);
+                const row = await readGrant(client, config, id);
+                data = { ...row, matchesAgent: await ctx.state.has('agent-key.json') ? row.grant.agent === await ctx.identity() : false };
+                break;
+            }
+            case 'gas check': {
+                const id = input(() => identifier(required('grant')));
+                const { config, client } = await ctx.public();
+                await ctx.verify(client, config);
+                const row = await readGrant(client, config, id);
+                const approval = new URL(config.approvalUrl);
+                approval.searchParams.set('grant', id);
+                const balance = await client.getBalance({ address: row.grant.agent });
+                try {
+                    const reserve = await paymentGasReserve(client, config, id, row.grant);
+                    data = { agent: row.grant.agent, balance, reserve, suggestedTopUp: fundingSuggestion(balance, reserve), ready: balance >= reserve, available: true, decimals: 18, approvalUrl: approval.href };
+                }
+                catch {
+                    data = { agent: row.grant.agent, balance, ready: false, available: false, decimals: 18, approvalUrl: approval.href };
+                }
+                break;
+            }
+            case 'payments prepare':
+                data = await preparePayment(ctx, paymentOptions);
+                break;
+            case 'pay':
+                data = await pay(ctx, { ...paymentOptions, dryRun: Boolean(opt['dry-run']), noWait: Boolean(opt['no-wait']), timeout });
+                break;
+            case 'payments list':
+                data = await listPayments(ctx);
+                break;
+            case 'payments show':
+                data = paymentView(await loadPayment(ctx, positions[0]));
+                break;
+            case 'payments wait':
+                data = await waitPayment(ctx, positions[0], { timeout });
+                break;
+            case 'payments resume':
+                data = await pay(ctx, { paymentId: positions[0], noWait: Boolean(opt['no-wait']), timeout });
+                break;
+        }
+        render(command, data, asJson);
+    }
+}
+catch (error) {
+    const e = publicError(error);
+    render(command, undefined, asJson, e);
+    process.exitCode = e.exitCode;
+}

package/dist/output.d.ts

@@ -0,0 +1,4 @@
+import { WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+export declare const json: (value: unknown) => string;
+export declare function publicError(error: unknown): WalletError;
+export declare function render(command: string, data: unknown, asJson: boolean, error?: WalletError): void;

package/dist/output.js

@@ -0,0 +1,30 @@
+import { BaseError } from 'viem';
+import { WalletError } from '@stablechain/agent-wallet-sdk/protocol';
+export const json = (value) => JSON.stringify(value, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2);
+export function publicError(error) {
+    if (error instanceof WalletError)
+        return error;
+    if (error instanceof BaseError)
+        return new WalletError('RPC_UNAVAILABLE', 'RPC request failed. Retry a status check; preserve saved payment IDs.', 5);
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+        return new WalletError('STATE_REQUIRED', 'Required local state is missing. Run init and import public configuration.');
+    return new WalletError('COMMAND_FAILED', 'Wallet command failed. Retain local state for inspection.');
+}
+export function render(command, data, asJson, error) {
+    const result = {
+        schemaVersion: 1, ok: !error, command,
+        ...(error ? { error: { code: error.code, message: error.message } } : {}),
+        data: error ? error.data ?? null : data,
+        ...(error?.exitCode === 6 ? { recovery: { action: command.startsWith('grants') ? 'grants wait' : 'payments wait', ...(error.data && typeof error.data === 'object' && 'paymentId' in error.data ? { paymentId: error.data.paymentId } : {}) } } : {}),
+    };
+    if (asJson)
+        process.stdout.write(json(result) + '\n');
+    else if (error)
+        process.stderr.write(`${error.code}: ${error.message}\n${error.data ? json(error.data) + '\n' : ''}`);
+    else if (data && typeof data === 'object' && 'paymentId' in data && 'intent' in data && 'status' in data) {
+        const payment = data;
+        process.stdout.write(`Payment ${payment.status}\n  Payment ID      ${payment.paymentId}\n  Grant ID        ${payment.intent.grantId}\n  Amount          ${payment.amount} USDT0\n  Payment source  Alice: ${payment.intent.alice}\n  Gas payer       Agent: ${payment.intent.agent}\n${payment.explorer ? `  Transaction     ${payment.explorer}\n` : ''}`);
+    }
+    else
+        process.stdout.write(typeof data === 'string' ? data + '\n' : json(data) + '\n');
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@stablechain/agent-wallet-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "agent-wallet": "./dist/main.js"
+  },
+  "exports": {
+    "./agent": {
+      "types": "./dist/agent/index.d.ts",
+      "import": "./dist/agent/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@stablechain/agent-wallet-sdk": "0.1.0",
+    "viem": "^2.38.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/executable.mjs",
+    "wallet": "node dist/main.js",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "prepack": "npm run build"
+  },
+  "description": "Agent signer, grant discovery, bounded payments, and recovery for Agent Wallet on Stable Testnet.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stablelabs/agentic.stable.xyz.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/stablelabs/agentic.stable.xyz/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/stablelabs/agentic.stable.xyz/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "stablechain",
+    "agent-wallet",
+    "eip-7702",
+    "payments",
+    "testnet",
+    "cli"
+  ]
+}