@rubicon-caliga/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rubicon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @rubicon-caliga/agent-sdk
+
+Buyer-agent SDK for Rubicon. The agent opens a budgeted reading session and pays
+for **every individual word** it receives via x402. A high-level `read()` loop
+runs the whole seller conversation → session → one-word payment → word → usage
+cycle until a stop condition is met, so you never send a payment per word by
+hand. The buyer can stop the moment it has enough information and pays for
+exactly the words it received.
+
+## Quick Start
+
+```ts
+import Rubicon, { CircleGatewayPaymentEngine, StaticPaymentEngine } from "@rubicon-caliga/agent-sdk";
+
+const privateKey = process.env.CIRCLE_PRIVATE_KEY as `0x${string}` | undefined;
+
+const rubicon = new Rubicon({
+  paymentEngine: privateKey
+    ? new CircleGatewayPaymentEngine({ chain: "arcTestnet", privateKey, rpcUrl: process.env.CIRCLE_RPC_URL })
+    : new StaticPaymentEngine(),
+});
+
+const receipt = await rubicon.run({
+  articleId: "live-article-id-from-repository",
+  goal: "Find the resale-fee clause",
+  maxSpendAtomic: "20000",
+  stopWhen: ({ text, wordsRead, amountPaid }) => wordsRead > 50 || /resale fee/i.test(text),
+  onWord: (word) => {
+    process.stdout.write(`${word} `);
+  },
+});
+
+console.log("\nreceipt:", receipt);
+```
+
+`baseUrl` defaults to `http://localhost:8787`. In development, omitting
+`paymentEngine` uses `StaticPaymentEngine`, which works against a dev-mode
+gateway. For real settlement, pass `CircleGatewayPaymentEngine`.
+
+## `run(options)`
+
+Runs the whole seller conversation → session → one-word payment → word → usage
+cycle and returns a final receipt. Use `onWord` or `onEvent` when you want live
+progress.
+
+## `read(options)`
+
+Yields `session.started`, `seller.message`, `article.word`, `article.usage`,
+`article.completed` (with a final receipt), and `article.error`. It handles:
+
+- seller-agent conversation and starting-section selection
+- session creation and one-word payment creation/submission
+- word receipt and running usage
+- retry idempotency (per-word idempotency keys)
+- budget enforcement (`maxSpendAtomic` / `budget`)
+- early stopping (`stopWhen`, `maxWords`)
+- stream abortion and a final receipt
+
+## Lower-level methods
+
+`getRepository`, `getNavigation`, `startConversation`, `sendConversationMessage`,
+`startSession`, `payForWord`, `abort`, and `streamEvents` (raw SSE) are available
+for custom flows.
+
+## Payment engines
+
+- `StaticPaymentEngine` — no-money development engine for a dev-mode gateway.
+- `CircleGatewayPaymentEngine` — signs the gateway's one-word x402 terms; Circle
+  may batch settlement internally, but each payload corresponds to one word.
+
+## Local Run
+
+```bash
+pnpm dev:gateway
+pnpm dev:agent
+```

package/dist/agent-client.d.ts

@@ -0,0 +1,124 @@
+import type { ArticleSummary, Budget, GatewayEvent, SendConversationMessageResponse, StartConversationResponse, StartSessionRequest, StartSessionResponse, StreamPaymentRequest, StreamPaymentResponse, WordPaymentReceipt } from "@rubicon-caliga/core";
+import { type AgentPaymentEngine } from "./payment-engine.js";
+export interface RubiconClientOptions {
+    baseUrl?: string;
+    paymentEngine?: AgentPaymentEngine;
+    /** Optional auth header value for the public agent API, e.g. "Bearer <token>". */
+    authorization?: string;
+    fetch?: typeof fetch;
+}
+export interface RepositoryResponse {
+    repository: "articles";
+    articles: ArticleSummary[];
+}
+export interface NavigationResponse {
+    article: ArticleSummary;
+    navigation: StartSessionResponse["navigation"];
+}
+export interface ReadReceipt {
+    sessionId: string;
+    articleId: string;
+    conversationId: string;
+    wordsRead: number;
+    amountPaidAtomic: `${bigint}`;
+    payments: WordPaymentReceipt[];
+    transactionHashes: string[];
+    text: string;
+    completed: boolean;
+    stopReason: "article_completed" | "stop_condition" | "budget_reached" | "max_words" | "aborted";
+}
+export type RubiconReadEvent = {
+    type: "session.started";
+    session: StartSessionResponse;
+} | {
+    type: "seller.message";
+    content: string;
+    recommendedSectionId?: string;
+} | {
+    type: "article.word";
+    sequence: number;
+    word: string;
+    priceAtomic: `${bigint}`;
+    wordsRead: number;
+    amountPaidAtomic: `${bigint}`;
+    transactionHash?: string;
+    transactionHashes?: string[];
+    payment?: WordPaymentReceipt;
+    text: string;
+} | {
+    type: "article.usage";
+    wordsPaid: number;
+    wordsDelivered: number;
+    paidAtomic: `${bigint}`;
+} | {
+    type: "article.completed";
+    receipt: ReadReceipt;
+} | {
+    type: "article.error";
+    message: string;
+};
+export interface ReadOptions {
+    articleId: string;
+    goal?: string;
+    sectionId?: string;
+    conversationId?: string;
+    /** Hard spend ceiling in atomic USDC. Equivalent to budget.maxAmountAtomic. */
+    maxSpendAtomic?: `${bigint}`;
+    budget?: Budget;
+    maxWords?: number;
+    /** Return true to stop reading once enough information has been collected. */
+    stopWhen?: (state: {
+        text: string;
+        wordsRead: number;
+        amountPaid: bigint;
+    }) => boolean | Promise<boolean>;
+    metadata?: Record<string, unknown>;
+}
+export interface RunOptions extends ReadOptions {
+    onEvent?: (event: RubiconReadEvent) => void | Promise<void>;
+    onWord?: (word: string, state: {
+        text: string;
+        wordsRead: number;
+        amountPaidAtomic: `${bigint}`;
+    }) => void | Promise<void>;
+}
+/**
+ * High-level buyer-agent client for Rubicon. `read()` runs the entire
+ * pay -> word -> usage loop one word at a time until a stop condition is met,
+ * so application developers never send a payment for every word themselves.
+ */
+export declare class RubiconClient {
+    private readonly options;
+    private readonly fetcher;
+    private readonly baseUrl;
+    private readonly paymentEngine;
+    constructor(options: RubiconClientOptions);
+    getRepository(): Promise<RepositoryResponse>;
+    getNavigation(articleId: string, goal?: string): Promise<NavigationResponse>;
+    startConversation(input: {
+        articleId: string;
+        goal?: string;
+        message?: string;
+    }): Promise<StartConversationResponse>;
+    sendConversationMessage(conversationId: string, message: string): Promise<SendConversationMessageResponse>;
+    startSession(request: StartSessionRequest): Promise<StartSessionResponse>;
+    payForWord(sessionId: string, payment: StreamPaymentRequest): Promise<StreamPaymentResponse>;
+    abort(sessionId: string, reason?: string): Promise<void>;
+    /** Subscribe to raw word-level server-sent events for observation/logging. */
+    streamEvents(sessionId: string, onEvent: (event: GatewayEvent) => void): () => void;
+    /**
+     * Simplest path for agents: run the whole paid read and return the receipt.
+     * Use callbacks only when the caller wants live progress.
+     */
+    run(options: RunOptions): Promise<ReadReceipt>;
+    /**
+     * Read an article one paid word at a time. Yields seller messages, paid words,
+     * running usage, and a final completion event carrying the receipt.
+     */
+    read(options: ReadOptions): AsyncGenerator<RubiconReadEvent, ReadReceipt>;
+    private headers;
+    private readJson;
+}
+/** Backwards-compatible alias. */
+export declare const AgentClient: typeof RubiconClient;
+//# sourceMappingURL=agent-client.d.ts.map

package/dist/agent-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.d.ts","sourceRoot":"","sources":["../src/agent-client.ts"],"names":[],"mappings":"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"}

package/dist/agent-client.js

@@ -0,0 +1,258 @@
+import { EventSource } from "eventsource";
+import { StaticPaymentEngine } from "./payment-engine.js";
+/**
+ * High-level buyer-agent client for Rubicon. `read()` runs the entire
+ * pay -> word -> usage loop one word at a time until a stop condition is met,
+ * so application developers never send a payment for every word themselves.
+ */
+export class RubiconClient {
+    options;
+    fetcher;
+    baseUrl;
+    paymentEngine;
+    constructor(options) {
+        this.options = options;
+        this.fetcher = options.fetch ?? fetch;
+        this.baseUrl = options.baseUrl ?? "http://localhost:8787";
+        this.paymentEngine = options.paymentEngine ?? new StaticPaymentEngine();
+    }
+    async getRepository() {
+        return this.readJson(await this.fetcher(`${this.baseUrl}/v1/repository`, { headers: this.headers() }));
+    }
+    async getNavigation(articleId, goal) {
+        const url = new URL(`${this.baseUrl}/v1/articles/${articleId}/navigation`);
+        if (goal) {
+            url.searchParams.set("goal", goal);
+        }
+        return this.readJson(await this.fetcher(url.toString(), { headers: this.headers() }));
+    }
+    async startConversation(input) {
+        return this.readJson(await this.fetcher(`${this.baseUrl}/v1/seller-agent/conversations`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(input),
+        }));
+    }
+    async sendConversationMessage(conversationId, message) {
+        return this.readJson(await this.fetcher(`${this.baseUrl}/v1/seller-agent/conversations/${conversationId}/messages`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ message }),
+        }));
+    }
+    async startSession(request) {
+        return this.readJson(await this.fetcher(`${this.baseUrl}/v1/sessions`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(request),
+        }));
+    }
+    async payForWord(sessionId, payment) {
+        const response = await this.fetcher(`${this.baseUrl}/v1/sessions/${sessionId}/payments`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(payment),
+        });
+        if (!response.ok) {
+            throw new Error(`Word payment rejected: ${response.status} ${await response.text()}`);
+        }
+        return response.json();
+    }
+    async abort(sessionId, reason = "agent_cancelled") {
+        await this.fetcher(`${this.baseUrl}/v1/sessions/${sessionId}/abort`, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify({ reason }),
+        });
+    }
+    /** Subscribe to raw word-level server-sent events for observation/logging. */
+    streamEvents(sessionId, onEvent) {
+        const headers = this.headers();
+        const source = new EventSource(`${this.baseUrl}/v1/sessions/${sessionId}/events`, {
+            fetch: (input, init) => this.fetcher(input, {
+                ...init,
+                headers: {
+                    ...Object.fromEntries(new Headers(init?.headers).entries()),
+                    ...headers,
+                },
+            }),
+        });
+        source.onmessage = (message) => onEvent(JSON.parse(message.data));
+        source.onerror = () => source.close();
+        return () => source.close();
+    }
+    /**
+     * Simplest path for agents: run the whole paid read and return the receipt.
+     * Use callbacks only when the caller wants live progress.
+     */
+    async run(options) {
+        let receipt;
+        for await (const event of this.read(options)) {
+            await options.onEvent?.(event);
+            if (event.type === "article.word") {
+                await options.onWord?.(event.word, {
+                    text: event.text,
+                    wordsRead: event.wordsRead,
+                    amountPaidAtomic: event.amountPaidAtomic,
+                });
+            }
+            if (event.type === "article.completed") {
+                receipt = event.receipt;
+            }
+        }
+        if (!receipt) {
+            throw new Error("Rubicon read finished without a receipt");
+        }
+        return receipt;
+    }
+    /**
+     * Read an article one paid word at a time. Yields seller messages, paid words,
+     * running usage, and a final completion event carrying the receipt.
+     */
+    async *read(options) {
+        const budget = options.budget ??
+            (options.maxSpendAtomic
+                ? { currency: "USDC", maxAmountAtomic: options.maxSpendAtomic }
+                : (() => {
+                    throw new Error("read() requires maxSpendAtomic or budget");
+                })());
+        const budgetAtomic = BigInt(budget.maxAmountAtomic);
+        // Let the seller agent recommend a starting section if the buyer has a goal
+        // and did not pick one explicitly.
+        let conversationId = options.conversationId;
+        let sectionId = options.sectionId;
+        if (options.goal && !conversationId) {
+            const conversation = await this.startConversation({
+                articleId: options.articleId,
+                goal: options.goal,
+                message: options.goal,
+            });
+            conversationId = conversation.conversationId;
+            const seller = conversation.messages.find((message) => message.role === "seller");
+            if (seller) {
+                yield {
+                    type: "seller.message",
+                    content: seller.content,
+                    recommendedSectionId: seller.recommendedSectionId,
+                };
+                sectionId = sectionId ?? seller.recommendedSectionId;
+            }
+        }
+        const session = await this.startSession({
+            articleId: options.articleId,
+            goal: options.goal,
+            conversationId,
+            sectionId,
+            budget,
+            metadata: options.metadata,
+        });
+        yield { type: "session.started", session };
+        const wordPaymentAtomic = BigInt(session.wordPaymentAtomic);
+        let text = "";
+        let wordsRead = 0;
+        let amountPaid = 0n;
+        const transactionHashes = [];
+        const payments = [];
+        let stopReason = "article_completed";
+        let completed = false;
+        const makeReceipt = () => ({
+            sessionId: session.sessionId,
+            articleId: session.article.articleId,
+            conversationId: session.conversationId,
+            wordsRead,
+            amountPaidAtomic: `${amountPaid}`,
+            payments: [...payments],
+            transactionHashes: [...transactionHashes],
+            text,
+            completed,
+            stopReason,
+        });
+        while (true) {
+            if (options.maxWords !== undefined && wordsRead >= options.maxWords) {
+                stopReason = "max_words";
+                break;
+            }
+            if (amountPaid + wordPaymentAtomic > budgetAtomic) {
+                stopReason = "budget_reached";
+                break;
+            }
+            if (await options.stopWhen?.({ text, wordsRead, amountPaid })) {
+                stopReason = "stop_condition";
+                break;
+            }
+            const payment = await this.paymentEngine.createWordPayment(session);
+            // Idempotency key ties this payment to the specific next word; safe retries.
+            const idempotencyKey = `${session.sessionId}:${wordsRead}`;
+            let result;
+            try {
+                result = await this.payForWord(session.sessionId, { ...payment, idempotencyKey });
+            }
+            catch (error) {
+                yield { type: "article.error", message: error instanceof Error ? error.message : String(error) };
+                stopReason = "aborted";
+                break;
+            }
+            if (result.completed && result.word === "") {
+                // Article exhausted with no further word to deliver.
+                completed = true;
+                stopReason = "article_completed";
+                const receipt = makeReceipt();
+                yield { type: "article.completed", receipt };
+                return receipt;
+            }
+            wordsRead = result.wordsDelivered;
+            amountPaid = BigInt(result.paidAtomic);
+            if (result.payment) {
+                payments.push(result.payment);
+            }
+            transactionHashes.push(...(result.transactionHashes ?? (result.transactionHash ? [result.transactionHash] : [])));
+            text = text ? `${text} ${result.word}` : result.word;
+            yield {
+                type: "article.word",
+                sequence: result.sequence,
+                word: result.word,
+                priceAtomic: result.priceAtomic,
+                wordsRead,
+                amountPaidAtomic: `${amountPaid}`,
+                transactionHash: result.transactionHash,
+                transactionHashes: result.transactionHashes,
+                payment: result.payment,
+                text,
+            };
+            yield {
+                type: "article.usage",
+                wordsPaid: result.wordsPaid,
+                wordsDelivered: result.wordsDelivered,
+                paidAtomic: result.paidAtomic,
+            };
+            if (result.completed) {
+                completed = true;
+                stopReason = "article_completed";
+                const receipt = makeReceipt();
+                yield { type: "article.completed", receipt };
+                return receipt;
+            }
+        }
+        // Stopped early by the buyer: abort the session so no further words are owed.
+        await this.abort(session.sessionId, stopReason).catch(() => { });
+        const receipt = makeReceipt();
+        yield { type: "article.completed", receipt };
+        return receipt;
+    }
+    headers(extra = {}) {
+        const headers = { ...extra };
+        if (this.options.authorization) {
+            headers.authorization = this.options.authorization;
+        }
+        return headers;
+    }
+    async readJson(response) {
+        if (!response.ok) {
+            throw new Error(`Gateway request failed: ${response.status} ${await response.text()}`);
+        }
+        return response.json();
+    }
+}
+/** Backwards-compatible alias. */
+export const AgentClient = RubiconClient;
+//# sourceMappingURL=agent-client.js.map

package/dist/agent-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.js","sourceRoot":"","sources":["../src/agent-client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./agent-client.js";
+export * from "./payment-engine.js";
+export { RubiconClient as Rubicon, RubiconClient as default } from "./agent-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./agent-client.js";
+export * from "./payment-engine.js";
+export { RubiconClient as Rubicon, RubiconClient as default } from "./agent-client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/payment-engine.d.ts

@@ -0,0 +1,32 @@
+import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
+import { type GatewayClientConfig } from "@circle-fin/x402-batching/client";
+/**
+ * Produces the payment payload for exactly one word. Called once per word by the
+ * SDK's read loop — application developers never assemble payments themselves.
+ */
+export interface AgentPaymentEngine {
+    createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest>;
+}
+/**
+ * Development engine. Declares the one-word amount without settling real funds,
+ * for use against a dev-mode gateway. NOT for production.
+ */
+export declare class StaticPaymentEngine implements AgentPaymentEngine {
+    private readonly network;
+    constructor(network?: string);
+    createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest>;
+}
+export type CircleGatewayPaymentEngineOptions = GatewayClientConfig;
+/**
+ * Circle/x402 engine. Signs the gateway's one-word `paymentRequired` terms.
+ * Circle may batch settlement internally, but each signed payload corresponds to
+ * exactly one word.
+ */
+export declare class CircleGatewayPaymentEngine implements AgentPaymentEngine {
+    private readonly options;
+    private readonly client;
+    private readonly account;
+    constructor(options: CircleGatewayPaymentEngineOptions);
+    createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest>;
+}
+//# sourceMappingURL=payment-engine.d.ts.map

package/dist/payment-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-engine.d.ts","sourceRoot":"","sources":["../src/payment-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEvF,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAIjG;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACjF;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,SAAmB;IAEjD,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAWtF;AAED,MAAM,MAAM,iCAAiC,GAAG,mBAAmB,CAAC;AAEpE;;;;GAIG;AACH,qBAAa,0BAA2B,YAAW,kBAAkB;IAIvD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;gBAEpC,OAAO,EAAE,iCAAiC;IAajE,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAQtF"}

package/dist/payment-engine.js

@@ -0,0 +1,57 @@
+import { x402Client } from "@x402/core/client";
+import { registerBatchScheme } from "@circle-fin/x402-batching/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+/**
+ * Development engine. Declares the one-word amount without settling real funds,
+ * for use against a dev-mode gateway. NOT for production.
+ */
+export class StaticPaymentEngine {
+    network;
+    constructor(network = "eip155:5042002") {
+        this.network = network;
+    }
+    async createWordPayment(session) {
+        return {
+            paymentPayload: {
+                scheme: "development-static",
+                network: this.network,
+                sessionId: session.sessionId,
+                amountAtomic: session.wordPaymentAtomic,
+                meteringUnit: "word",
+            },
+        };
+    }
+}
+/**
+ * Circle/x402 engine. Signs the gateway's one-word `paymentRequired` terms.
+ * Circle may batch settlement internally, but each signed payload corresponds to
+ * exactly one word.
+ */
+export class CircleGatewayPaymentEngine {
+    options;
+    client = new x402Client();
+    account;
+    constructor(options) {
+        this.options = options;
+        this.account = privateKeyToAccount(this.options.privateKey);
+        // Recommended buyer integration (Circle x402 buyer how-to): register the
+        // gasless batched scheme with an `exact` fallback. `registerBatchScheme`
+        // wires a CompositeEvmScheme that uses Gateway batching when the seller
+        // supports it and falls back to a standard EIP-3009 `exact` payment
+        // otherwise — no per-request routing logic needed.
+        registerBatchScheme(this.client, {
+            signer: this.account,
+            fallbackScheme: new ExactEvmScheme(this.account),
+        });
+    }
+    async createWordPayment(session) {
+        if (!session.paymentRequired) {
+            throw new Error("Session did not include an x402 one-word payment requirement");
+        }
+        return {
+            paymentPayload: await this.client.createPaymentPayload(session.paymentRequired),
+        };
+    }
+}
+//# sourceMappingURL=payment-engine.js.map

package/dist/payment-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-engine.js","sourceRoot":"","sources":["../src/payment-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAA4B,MAAM,kCAAkC,CAAC;AACjG,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAUpD;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IACD;IAA7B,YAA6B,UAAU,gBAAgB;QAA1B,YAAO,GAAP,OAAO,CAAmB;IAAG,CAAC;IAE3D,KAAK,CAAC,iBAAiB,CAAC,OAA6B;QACnD,OAAO;YACL,cAAc,EAAE;gBACd,MAAM,EAAE,oBAAoB;gBAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,YAAY,EAAE,OAAO,CAAC,iBAAiB;gBACvC,YAAY,EAAE,MAAM;aACrB;SACF,CAAC;IACJ,CAAC;CACF;AAID;;;;GAIG;AACH,MAAM,OAAO,0BAA0B;IAIR;IAHZ,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;IAC1B,OAAO,CAAyC;IAEjE,YAA6B,OAA0C;QAA1C,YAAO,GAAP,OAAO,CAAmC;QACrE,IAAI,CAAC,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAC5D,yEAAyE;QACzE,yEAAyE;QACzE,wEAAwE;QACxE,oEAAoE;QACpE,mDAAmD;QACnD,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE;YAC/B,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,cAAc,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;SACjD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,OAA6B;QACnD,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAClF,CAAC;QACD,OAAO;YACL,cAAc,EAAE,MAAM,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,OAAO,CAAC,eAAwB,CAAC;SACzF,CAAC;IACJ,CAAC;CACF"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@rubicon-caliga/agent-sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for autonomous agents consuming per-word article streams via Rubicon x402.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaelzoub/rubicon.git",
+    "directory": "packages/agent-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/**/*.test.js",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@rubicon-caliga/core": "^0.1.0",
+    "@circle-fin/x402-batching": "^3.1.2",
+    "@x402/core": "^2.15.0",
+    "@x402/evm": "^2.15.0",
+    "eventsource": "^4.0.0",
+    "viem": "^2.52.2"
+  }
+}

package/src/agent-client.ts

@@ -0,0 +1,383 @@
+import { EventSource } from "eventsource";
+import type {
+  ArticleSummary,
+  Budget,
+  GatewayEvent,
+  SendConversationMessageResponse,
+  StartConversationResponse,
+  StartSessionRequest,
+  StartSessionResponse,
+  StreamPaymentRequest,
+  StreamPaymentResponse,
+  WordPaymentReceipt,
+} from "@rubicon-caliga/core";
+import { StaticPaymentEngine, type AgentPaymentEngine } from "./payment-engine.js";
+
+export interface RubiconClientOptions {
+  baseUrl?: string;
+  paymentEngine?: AgentPaymentEngine;
+  /** Optional auth header value for the public agent API, e.g. "Bearer <token>". */
+  authorization?: string;
+  fetch?: typeof fetch;
+}
+
+export interface RepositoryResponse {
+  repository: "articles";
+  articles: ArticleSummary[];
+}
+
+export interface NavigationResponse {
+  article: ArticleSummary;
+  navigation: StartSessionResponse["navigation"];
+}
+
+export interface ReadReceipt {
+  sessionId: string;
+  articleId: string;
+  conversationId: string;
+  wordsRead: number;
+  amountPaidAtomic: `${bigint}`;
+  payments: WordPaymentReceipt[];
+  transactionHashes: string[];
+  text: string;
+  completed: boolean;
+  stopReason: "article_completed" | "stop_condition" | "budget_reached" | "max_words" | "aborted";
+}
+
+export type RubiconReadEvent =
+  | { type: "session.started"; session: StartSessionResponse }
+  | { type: "seller.message"; content: string; recommendedSectionId?: string }
+  | {
+      type: "article.word";
+      sequence: number;
+      word: string;
+      priceAtomic: `${bigint}`;
+      wordsRead: number;
+      amountPaidAtomic: `${bigint}`;
+      transactionHash?: string;
+      transactionHashes?: string[];
+      payment?: WordPaymentReceipt;
+      text: string;
+    }
+  | { type: "article.usage"; wordsPaid: number; wordsDelivered: number; paidAtomic: `${bigint}` }
+  | { type: "article.completed"; receipt: ReadReceipt }
+  | { type: "article.error"; message: string };
+
+export interface ReadOptions {
+  articleId: string;
+  goal?: string;
+  sectionId?: string;
+  conversationId?: string;
+  /** Hard spend ceiling in atomic USDC. Equivalent to budget.maxAmountAtomic. */
+  maxSpendAtomic?: `${bigint}`;
+  budget?: Budget;
+  maxWords?: number;
+  /** Return true to stop reading once enough information has been collected. */
+  stopWhen?: (state: {
+    text: string;
+    wordsRead: number;
+    amountPaid: bigint;
+  }) => boolean | Promise<boolean>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RunOptions extends ReadOptions {
+  onEvent?: (event: RubiconReadEvent) => void | Promise<void>;
+  onWord?: (word: string, state: { text: string; wordsRead: number; amountPaidAtomic: `${bigint}` }) => void | Promise<void>;
+}
+
+/**
+ * High-level buyer-agent client for Rubicon. `read()` runs the entire
+ * pay -> word -> usage loop one word at a time until a stop condition is met,
+ * so application developers never send a payment for every word themselves.
+ */
+export class RubiconClient {
+  private readonly fetcher: typeof fetch;
+  private readonly baseUrl: string;
+  private readonly paymentEngine: AgentPaymentEngine;
+
+  constructor(private readonly options: RubiconClientOptions) {
+    this.fetcher = options.fetch ?? fetch;
+    this.baseUrl = options.baseUrl ?? "http://localhost:8787";
+    this.paymentEngine = options.paymentEngine ?? new StaticPaymentEngine();
+  }
+
+  async getRepository(): Promise<RepositoryResponse> {
+    return this.readJson(await this.fetcher(`${this.baseUrl}/v1/repository`, { headers: this.headers() }));
+  }
+
+  async getNavigation(articleId: string, goal?: string): Promise<NavigationResponse> {
+    const url = new URL(`${this.baseUrl}/v1/articles/${articleId}/navigation`);
+    if (goal) {
+      url.searchParams.set("goal", goal);
+    }
+    return this.readJson(await this.fetcher(url.toString(), { headers: this.headers() }));
+  }
+
+  async startConversation(input: {
+    articleId: string;
+    goal?: string;
+    message?: string;
+  }): Promise<StartConversationResponse> {
+    return this.readJson(
+      await this.fetcher(`${this.baseUrl}/v1/seller-agent/conversations`, {
+        method: "POST",
+        headers: this.headers({ "content-type": "application/json" }),
+        body: JSON.stringify(input),
+      }),
+    );
+  }
+
+  async sendConversationMessage(
+    conversationId: string,
+    message: string,
+  ): Promise<SendConversationMessageResponse> {
+    return this.readJson(
+      await this.fetcher(
+        `${this.baseUrl}/v1/seller-agent/conversations/${conversationId}/messages`,
+        {
+          method: "POST",
+          headers: this.headers({ "content-type": "application/json" }),
+          body: JSON.stringify({ message }),
+        },
+      ),
+    );
+  }
+
+  async startSession(request: StartSessionRequest): Promise<StartSessionResponse> {
+    return this.readJson(
+      await this.fetcher(`${this.baseUrl}/v1/sessions`, {
+        method: "POST",
+        headers: this.headers({ "content-type": "application/json" }),
+        body: JSON.stringify(request),
+      }),
+    );
+  }
+
+  async payForWord(sessionId: string, payment: StreamPaymentRequest): Promise<StreamPaymentResponse> {
+    const response = await this.fetcher(`${this.baseUrl}/v1/sessions/${sessionId}/payments`, {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify(payment),
+    });
+    if (!response.ok) {
+      throw new Error(`Word payment rejected: ${response.status} ${await response.text()}`);
+    }
+    return response.json() as Promise<StreamPaymentResponse>;
+  }
+
+  async abort(sessionId: string, reason = "agent_cancelled"): Promise<void> {
+    await this.fetcher(`${this.baseUrl}/v1/sessions/${sessionId}/abort`, {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify({ reason }),
+    });
+  }
+
+  /** Subscribe to raw word-level server-sent events for observation/logging. */
+  streamEvents(sessionId: string, onEvent: (event: GatewayEvent) => void): () => void {
+    const headers = this.headers();
+    const source = new EventSource(`${this.baseUrl}/v1/sessions/${sessionId}/events`, {
+      fetch: (input, init) =>
+        this.fetcher(input, {
+          ...init,
+          headers: {
+            ...Object.fromEntries(new Headers(init?.headers).entries()),
+            ...headers,
+          },
+        }),
+    });
+    source.onmessage = (message) => onEvent(JSON.parse(message.data) as GatewayEvent);
+    source.onerror = () => source.close();
+    return () => source.close();
+  }
+
+  /**
+   * Simplest path for agents: run the whole paid read and return the receipt.
+   * Use callbacks only when the caller wants live progress.
+   */
+  async run(options: RunOptions): Promise<ReadReceipt> {
+    let receipt: ReadReceipt | undefined;
+    for await (const event of this.read(options)) {
+      await options.onEvent?.(event);
+      if (event.type === "article.word") {
+        await options.onWord?.(event.word, {
+          text: event.text,
+          wordsRead: event.wordsRead,
+          amountPaidAtomic: event.amountPaidAtomic,
+        });
+      }
+      if (event.type === "article.completed") {
+        receipt = event.receipt;
+      }
+    }
+    if (!receipt) {
+      throw new Error("Rubicon read finished without a receipt");
+    }
+    return receipt;
+  }
+
+  /**
+   * Read an article one paid word at a time. Yields seller messages, paid words,
+   * running usage, and a final completion event carrying the receipt.
+   */
+  async *read(options: ReadOptions): AsyncGenerator<RubiconReadEvent, ReadReceipt> {
+    const budget: Budget =
+      options.budget ??
+      (options.maxSpendAtomic
+        ? { currency: "USDC", maxAmountAtomic: options.maxSpendAtomic }
+        : (() => {
+            throw new Error("read() requires maxSpendAtomic or budget");
+          })());
+    const budgetAtomic = BigInt(budget.maxAmountAtomic);
+
+    // Let the seller agent recommend a starting section if the buyer has a goal
+    // and did not pick one explicitly.
+    let conversationId = options.conversationId;
+    let sectionId = options.sectionId;
+    if (options.goal && !conversationId) {
+      const conversation = await this.startConversation({
+        articleId: options.articleId,
+        goal: options.goal,
+        message: options.goal,
+      });
+      conversationId = conversation.conversationId;
+      const seller = conversation.messages.find((message) => message.role === "seller");
+      if (seller) {
+        yield {
+          type: "seller.message",
+          content: seller.content,
+          recommendedSectionId: seller.recommendedSectionId,
+        };
+        sectionId = sectionId ?? seller.recommendedSectionId;
+      }
+    }
+
+    const session = await this.startSession({
+      articleId: options.articleId,
+      goal: options.goal,
+      conversationId,
+      sectionId,
+      budget,
+      metadata: options.metadata,
+    });
+    yield { type: "session.started", session };
+
+    const wordPaymentAtomic = BigInt(session.wordPaymentAtomic);
+    let text = "";
+    let wordsRead = 0;
+    let amountPaid = 0n;
+    const transactionHashes: string[] = [];
+    const payments: WordPaymentReceipt[] = [];
+    let stopReason: ReadReceipt["stopReason"] = "article_completed";
+    let completed = false;
+
+    const makeReceipt = (): ReadReceipt => ({
+      sessionId: session.sessionId,
+      articleId: session.article.articleId,
+      conversationId: session.conversationId,
+      wordsRead,
+      amountPaidAtomic: `${amountPaid}`,
+      payments: [...payments],
+      transactionHashes: [...transactionHashes],
+      text,
+      completed,
+      stopReason,
+    });
+
+    while (true) {
+      if (options.maxWords !== undefined && wordsRead >= options.maxWords) {
+        stopReason = "max_words";
+        break;
+      }
+      if (amountPaid + wordPaymentAtomic > budgetAtomic) {
+        stopReason = "budget_reached";
+        break;
+      }
+      if (await options.stopWhen?.({ text, wordsRead, amountPaid })) {
+        stopReason = "stop_condition";
+        break;
+      }
+
+      const payment = await this.paymentEngine.createWordPayment(session);
+      // Idempotency key ties this payment to the specific next word; safe retries.
+      const idempotencyKey = `${session.sessionId}:${wordsRead}`;
+      let result: StreamPaymentResponse;
+      try {
+        result = await this.payForWord(session.sessionId, { ...payment, idempotencyKey });
+      } catch (error) {
+        yield { type: "article.error", message: error instanceof Error ? error.message : String(error) };
+        stopReason = "aborted";
+        break;
+      }
+
+      if (result.completed && result.word === "") {
+        // Article exhausted with no further word to deliver.
+        completed = true;
+        stopReason = "article_completed";
+        const receipt = makeReceipt();
+        yield { type: "article.completed", receipt };
+        return receipt;
+      }
+
+      wordsRead = result.wordsDelivered;
+      amountPaid = BigInt(result.paidAtomic);
+      if (result.payment) {
+        payments.push(result.payment);
+      }
+      transactionHashes.push(...(result.transactionHashes ?? (result.transactionHash ? [result.transactionHash] : [])));
+      text = text ? `${text} ${result.word}` : result.word;
+
+      yield {
+        type: "article.word",
+        sequence: result.sequence,
+        word: result.word,
+        priceAtomic: result.priceAtomic,
+        wordsRead,
+        amountPaidAtomic: `${amountPaid}`,
+        transactionHash: result.transactionHash,
+        transactionHashes: result.transactionHashes,
+        payment: result.payment,
+        text,
+      };
+      yield {
+        type: "article.usage",
+        wordsPaid: result.wordsPaid,
+        wordsDelivered: result.wordsDelivered,
+        paidAtomic: result.paidAtomic,
+      };
+
+      if (result.completed) {
+        completed = true;
+        stopReason = "article_completed";
+        const receipt = makeReceipt();
+        yield { type: "article.completed", receipt };
+        return receipt;
+      }
+    }
+
+    // Stopped early by the buyer: abort the session so no further words are owed.
+    await this.abort(session.sessionId, stopReason).catch(() => {});
+    const receipt = makeReceipt();
+    yield { type: "article.completed", receipt };
+    return receipt;
+  }
+
+  private headers(extra: Record<string, string> = {}): Record<string, string> {
+    const headers: Record<string, string> = { ...extra };
+    if (this.options.authorization) {
+      headers.authorization = this.options.authorization;
+    }
+    return headers;
+  }
+
+  private async readJson<T>(response: Response): Promise<T> {
+    if (!response.ok) {
+      throw new Error(`Gateway request failed: ${response.status} ${await response.text()}`);
+    }
+    return response.json() as Promise<T>;
+  }
+}
+
+/** Backwards-compatible alias. */
+export const AgentClient = RubiconClient;

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./agent-client.js";
+export * from "./payment-engine.js";
+export { RubiconClient as Rubicon, RubiconClient as default } from "./agent-client.js";

package/src/payment-engine.ts

@@ -0,0 +1,67 @@
+import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
+import { x402Client } from "@x402/core/client";
+import { registerBatchScheme, type GatewayClientConfig } from "@circle-fin/x402-batching/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+/**
+ * Produces the payment payload for exactly one word. Called once per word by the
+ * SDK's read loop — application developers never assemble payments themselves.
+ */
+export interface AgentPaymentEngine {
+  createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest>;
+}
+
+/**
+ * Development engine. Declares the one-word amount without settling real funds,
+ * for use against a dev-mode gateway. NOT for production.
+ */
+export class StaticPaymentEngine implements AgentPaymentEngine {
+  constructor(private readonly network = "eip155:5042002") {}
+
+  async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
+    return {
+      paymentPayload: {
+        scheme: "development-static",
+        network: this.network,
+        sessionId: session.sessionId,
+        amountAtomic: session.wordPaymentAtomic,
+        meteringUnit: "word",
+      },
+    };
+  }
+}
+
+export type CircleGatewayPaymentEngineOptions = GatewayClientConfig;
+
+/**
+ * Circle/x402 engine. Signs the gateway's one-word `paymentRequired` terms.
+ * Circle may batch settlement internally, but each signed payload corresponds to
+ * exactly one word.
+ */
+export class CircleGatewayPaymentEngine implements AgentPaymentEngine {
+  private readonly client = new x402Client();
+  private readonly account: ReturnType<typeof privateKeyToAccount>;
+
+  constructor(private readonly options: CircleGatewayPaymentEngineOptions) {
+    this.account = privateKeyToAccount(this.options.privateKey);
+    // Recommended buyer integration (Circle x402 buyer how-to): register the
+    // gasless batched scheme with an `exact` fallback. `registerBatchScheme`
+    // wires a CompositeEvmScheme that uses Gateway batching when the seller
+    // supports it and falls back to a standard EIP-3009 `exact` payment
+    // otherwise — no per-request routing logic needed.
+    registerBatchScheme(this.client, {
+      signer: this.account,
+      fallbackScheme: new ExactEvmScheme(this.account),
+    });
+  }
+
+  async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
+    if (!session.paymentRequired) {
+      throw new Error("Session did not include an x402 one-word payment requirement");
+    }
+    return {
+      paymentPayload: await this.client.createPaymentPayload(session.paymentRequired as never),
+    };
+  }
+}