@rubicon-caliga/agent-sdk 0.1.1 → 0.1.3

package/src/agent-client.test.ts

@@ -0,0 +1,205 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { RubiconClient } from "./agent-client.js";
+import type { AgentPaymentEngine } from "./payment-engine.js";
+
+const paymentEngine: AgentPaymentEngine = {
+  async createWordPayment() {
+    return { paymentPayload: { ok: true } };
+  },
+};
+
+const chunkPaymentEngine: AgentPaymentEngine = {
+  async createWordPayment() {
+    throw new Error("word fallback should not be used");
+  },
+  async createChunkPayment(_session, input) {
+    return {
+      paymentPayload: { amountAtomic: `${input.maxWords}` },
+      maxWords: input.maxWords,
+    };
+  },
+};
+
+test("run receipt preserves Gateway settlement receipt fields", async () => {
+  const fetcher = (async (input: Parameters<typeof fetch>[0]) => {
+    const url = String(input);
+    if (url.endsWith("/v1/sessions")) {
+      return jsonResponse({
+        sessionId: "session_1",
+        state: "active",
+        article: article(),
+        navigation: navigation(),
+        pricePerWordAtomic: "1",
+        maxArticlePriceAtomic: "10",
+        conversationId: "conversation_1",
+        wordPaymentAtomic: "1",
+        gatewayFeeBps: 0,
+        paymentRequired: { scheme: "exact" },
+        expiresAt: "2026-06-18T12:00:00.000Z",
+        wordsPaid: 0,
+        wordsDelivered: 0,
+        paidAtomic: "0",
+      });
+    }
+    if (url.endsWith("/v1/sessions/session_1/payments")) {
+      return jsonResponse({
+        accepted: true,
+        sequence: 0,
+        word: "Rubicon",
+        priceAtomic: "1",
+        wordsPaid: 1,
+        wordsDelivered: 1,
+        paidAtomic: "1",
+        completed: true,
+        transactionHashes: [],
+        settlementIds: ["settlement_1"],
+        payment: {
+          paymentId: "payment_1",
+          sessionId: "session_1",
+          articleId: "article_1",
+          sequence: 0,
+          meteringUnit: "word",
+          amountAtomic: "1",
+          currency: "USDC",
+          network: "eip155:5042002",
+          payTo: "0x3333333333333333333333333333333333333333",
+          transactionHashes: [],
+          settlementIds: ["settlement_1"],
+          buyerWalletAddress: "0x2222222222222222222222222222222222222222",
+          settledAt: "2026-06-18T12:00:00.000Z",
+        },
+      });
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  }) as typeof fetch;
+
+  const client = new RubiconClient({
+    baseUrl: "http://rubicon.test",
+    paymentEngine,
+    fetch: fetcher,
+  });
+
+  const receipt = await client.run({
+    articleId: "article_1",
+    maxSpendAtomic: "10",
+  });
+
+  assert.deepEqual(receipt.transactionHashes, []);
+  assert.deepEqual(receipt.settlementIds, ["settlement_1"]);
+  assert.equal(receipt.buyerWalletAddress, "0x2222222222222222222222222222222222222222");
+  assert.equal(receipt.sellerPayTo, "0x3333333333333333333333333333333333333333");
+  assert.equal(receipt.network, "eip155:5042002");
+});
+
+test("run can consume chunk stream while preserving per-word receipt fields", async () => {
+  const fetcher = (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    const url = String(input);
+    if (url.endsWith("/v1/sessions")) {
+      return jsonResponse({
+        sessionId: "session_1",
+        state: "active",
+        article: article(),
+        navigation: navigation(),
+        pricePerWordAtomic: "1",
+        maxArticlePriceAtomic: "10",
+        conversationId: "conversation_1",
+        wordPaymentAtomic: "1",
+        gatewayFeeBps: 0,
+        paymentRequired: { accepts: [{ amount: "1" }] },
+        expiresAt: "2026-06-18T12:00:00.000Z",
+        wordsPaid: 0,
+        wordsDelivered: 0,
+        paidAtomic: "0",
+      });
+    }
+    if (url.endsWith("/v1/sessions/session_1/stream")) {
+      const body = JSON.parse(String(init?.body)) as { maxWords: number };
+      assert.equal(body.maxWords, 3);
+      return jsonResponse({
+        accepted: true,
+        words: [
+          { sequence: 0, word: "Rubicon", priceAtomic: "1", payment: payment(0, "Rubicon") },
+          { sequence: 1, word: "streams", priceAtomic: "1", payment: payment(1, "streams") },
+          { sequence: 2, word: "chunks", priceAtomic: "1", payment: payment(2, "chunks") },
+        ],
+        text: "Rubicon streams chunks",
+        wordsPaid: 3,
+        wordsDelivered: 3,
+        paidAtomic: "3",
+        completed: true,
+        settlementIds: ["settlement_chunk"],
+      });
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  }) as typeof fetch;
+
+  const client = new RubiconClient({
+    baseUrl: "http://rubicon.test",
+    paymentEngine: chunkPaymentEngine,
+    fetch: fetcher,
+  });
+
+  const receipt = await client.run({
+    articleId: "article_1",
+    maxSpendAtomic: "10",
+    chunkWords: 3,
+  });
+
+  assert.equal(receipt.text, "Rubicon streams chunks");
+  assert.equal(receipt.wordsRead, 3);
+  assert.equal(receipt.amountPaidAtomic, "3");
+  assert.equal(receipt.payments.length, 3);
+  assert.deepEqual(receipt.settlementIds, ["settlement_chunk"]);
+});
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function article() {
+  return {
+    articleId: "article_1",
+    creatorId: "creator_1",
+    creatorUsername: "creator",
+    title: "Title",
+    author: "Author",
+    state: "published",
+    totalWords: 1,
+    pricePerWordAtomic: "1",
+    maxArticlePriceAtomic: "1",
+    sections: [],
+  };
+}
+
+function navigation() {
+  return {
+    articleId: "article_1",
+    sections: [],
+    sellerAgent: {
+      recommendedSectionId: "intro",
+      alternativeSectionIds: [],
+      rationale: "",
+      safeHints: [],
+      withheld: [],
+    },
+    stopConditions: [],
+  };
+}
+
+function payment(sequence: number, word: string) {
+  return {
+    paymentId: `payment_${sequence}`,
+    sessionId: "session_1",
+    articleId: "article_1",
+    sequence,
+    meteringUnit: "word",
+    amountAtomic: "1",
+    currency: "USDC",
+    settledAt: "2026-06-18T12:00:00.000Z",
+    word,
+  };
+}

package/src/agent-client.ts

@@ -7,6 +7,7 @@ import type {
   StartConversationResponse,
   StartSessionRequest,
   StartSessionResponse,
+  StreamChunkResponse,
   StreamPaymentRequest,
   StreamPaymentResponse,
   WordPaymentReceipt,
@@ -63,6 +64,14 @@ export type RubiconReadEvent =
       payment?: WordPaymentReceipt;
       text: string;
     }
+  | {
+      type: "article.chunk";
+      words: Array<{ sequence: number; word: string; priceAtomic: `${bigint}`; payment?: WordPaymentReceipt }>;
+      text: string;
+      wordsRead: number;
+      amountPaidAtomic: `${bigint}`;
+      completed: boolean;
+    }
   | { type: "article.usage"; wordsPaid: number; wordsDelivered: number; paidAtomic: `${bigint}` }
   | { type: "article.completed"; receipt: ReadReceipt }
   | { type: "article.error"; message: string };
@@ -76,6 +85,8 @@ export interface ReadOptions {
   maxSpendAtomic?: `${bigint}`;
   budget?: Budget;
   maxWords?: number;
+  /** Number of words to authorize and deliver per gateway round trip when supported. */
+  chunkWords?: number;
   /** Return true to stop reading once enough information has been collected. */
   stopWhen?: (state: {
     text: string;
@@ -92,8 +103,8 @@ export interface RunOptions extends ReadOptions {
 
 /**
  * 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.
+ * authorize -> word -> usage loop until a stop condition is met, so application
+ * developers never drive a payment flow for every word themselves.
  */
 export class RubiconClient {
   private readonly fetcher: typeof fetch;
@@ -170,6 +181,18 @@ export class RubiconClient {
     return response.json() as Promise<StreamPaymentResponse>;
   }
 
+  async streamChunk(sessionId: string, payment: StreamPaymentRequest): Promise<StreamChunkResponse> {
+    const response = await this.fetcher(`${this.baseUrl}/v1/sessions/${sessionId}/stream`, {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify(payment),
+    });
+    if (!response.ok) {
+      throw new Error(`Chunk stream rejected: ${response.status} ${await response.text()}`);
+    }
+    return response.json() as Promise<StreamChunkResponse>;
+  }
+
   async abort(sessionId: string, reason = "agent_cancelled"): Promise<void> {
     await this.fetcher(`${this.baseUrl}/v1/sessions/${sessionId}/abort`, {
       method: "POST",
@@ -222,8 +245,8 @@ export class RubiconClient {
   }
 
   /**
-   * 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 an article with word-level metering. 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 =
@@ -274,6 +297,8 @@ export class RubiconClient {
     const transactionHashes: string[] = [];
     const settlementIds: string[] = [];
     const payments: WordPaymentReceipt[] = [];
+    const chunkWords = normalizeChunkWords(options.chunkWords);
+    const useChunks = chunkWords > 1 && typeof this.paymentEngine.createChunkPayment === "function";
     let stopReason: ReadReceipt["stopReason"] = "article_completed";
     let completed = false;
 
@@ -308,6 +333,64 @@ export class RubiconClient {
         break;
       }
 
+      if (useChunks) {
+        const remainingWords = options.maxWords === undefined ? chunkWords : Math.max(0, options.maxWords - wordsRead);
+        const affordableWords = Number((budgetAtomic - amountPaid) / wordPaymentAtomic);
+        const maxWords = Math.max(1, Math.min(chunkWords, remainingWords || chunkWords, affordableWords));
+        const payment = await this.paymentEngine.createChunkPayment!(session, {
+          nextSequence: wordsRead,
+          maxWords,
+        });
+        const idempotencyKey = `${session.sessionId}:${wordsRead}:${maxWords}`;
+        let result: StreamChunkResponse;
+        try {
+          result = await this.streamChunk(session.sessionId, { ...payment, idempotencyKey, maxWords });
+        } catch (error) {
+          yield { type: "article.error", message: error instanceof Error ? error.message : String(error) };
+          stopReason = "aborted";
+          break;
+        }
+        if (result.words.length === 0 && result.completed) {
+          completed = true;
+          stopReason = "article_completed";
+          const receipt = makeReceipt();
+          yield { type: "article.completed", receipt };
+          return receipt;
+        }
+        for (const entry of result.words) {
+          if (entry.payment) {
+            payments.push(entry.payment);
+          }
+          text = text ? `${text} ${entry.word}` : entry.word;
+        }
+        wordsRead = result.wordsDelivered;
+        amountPaid = BigInt(result.paidAtomic);
+        transactionHashes.push(...(result.transactionHashes ?? (result.transactionHash ? [result.transactionHash] : [])));
+        settlementIds.push(...(result.settlementIds ?? (result.settlementId ? [result.settlementId] : [])));
+        yield {
+          type: "article.chunk",
+          words: result.words,
+          text,
+          wordsRead,
+          amountPaidAtomic: `${amountPaid}`,
+          completed: result.completed,
+        };
+        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;
+        }
+        continue;
+      }
+
       const payment = await this.paymentEngine.createWordPayment(session);
       // Idempotency key ties this payment to the specific next word; safe retries.
       const idempotencyKey = `${session.sessionId}:${wordsRead}`;
@@ -391,3 +474,9 @@ export class RubiconClient {
 
 /** Backwards-compatible alias. */
 export const AgentClient = RubiconClient;
+
+function normalizeChunkWords(chunkWords: number | undefined): number {
+  if (chunkWords === undefined) return 1;
+  if (!Number.isInteger(chunkWords) || chunkWords < 1) return 1;
+  return Math.min(chunkWords, 256);
+}

package/src/circle-agent-wallet.ts

@@ -2,10 +2,8 @@ import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga
 import { x402Client } from "@x402/core/client";
 import { registerBatchScheme } from "@circle-fin/x402-batching/client";
 import { ExactEvmScheme } from "@x402/evm/exact/client";
-import {
-  initiateDeveloperControlledWalletsClient,
-  type CircleDeveloperControlledWalletsClient,
-} from "@circle-fin/developer-controlled-wallets";
+import * as CircleWallets from "@circle-fin/developer-controlled-wallets";
+import type { CircleDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
 import type { AgentPaymentEngine } from "./payment-engine.js";
 
 export interface CircleAgentWalletEngineOptions {
@@ -13,7 +11,7 @@ export interface CircleAgentWalletEngineOptions {
   apiKey: string;
   /** Entity secret registered for the Circle developer account. */
   entitySecret: string;
-  /** The Agent Wallet that holds USDC and signs each one-word payment. */
+  /** The Agent Wallet that holds USDC and signs Circle / Arc authorizations. */
   walletId: string;
   /**
    * The wallet's on-chain address. Optional — when omitted it is resolved once
@@ -80,7 +78,7 @@ class CircleAgentWalletSigner {
     const res = await this.client.signTypedData({
       walletId: this.walletId,
       data: serializeTypedData(toEip712Payload(typed)),
-      memo: "Rubicon one-word payment",
+      memo: "Rubicon reading authorization",
     });
     const signature = res.data?.signature;
     if (!signature) {
@@ -91,10 +89,10 @@ class CircleAgentWalletSigner {
 }
 
 /**
- * Circle Agent Wallet engine. Signs the gateway's one-word x402 terms with a
- * custodial Circle Agent Wallet — the recommended buyer setup — so the agent
- * never handles a local signing key. Settlement may be batched by Circle, but
- * each signed payload still corresponds to exactly one word.
+ * Circle Agent Wallet engine. Signs gateway authorization terms with a
+ * custodial Circle Agent Wallet so the buyer agent never handles a local
+ * signing key. Current gateways may still call the legacy one-word method as a
+ * chunk-compatibility path.
  */
 export class CircleAgentWalletEngine implements AgentPaymentEngine {
   private readonly x402 = new x402Client();
@@ -103,7 +101,7 @@ export class CircleAgentWalletEngine implements AgentPaymentEngine {
   constructor(options: CircleAgentWalletEngineOptions) {
     const client =
       options.client ??
-      initiateDeveloperControlledWalletsClient({
+      CircleWallets.initiateDeveloperControlledWalletsClient({
         apiKey: options.apiKey,
         entitySecret: options.entitySecret,
         ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
@@ -119,7 +117,7 @@ export class CircleAgentWalletEngine implements AgentPaymentEngine {
 
   async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
     if (!session.paymentRequired) {
-      throw new Error("Session did not include an x402 one-word payment requirement");
+      throw new Error("Session did not include a legacy x402 payment requirement");
     }
     // Resolve the wallet address up front so the synchronous `address` read
     // inside createPaymentPayload sees a real value.

package/src/circle-cli-gateway-payment.test.ts

@@ -1,6 +1,8 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
+  CircleCliGatewaySigner,
+  parseCircleGatewayBackingEOA,
   parseCircleCliSignature,
   parseCircleCliWalletAddress,
 } from "./circle-cli-gateway-payment.js";
@@ -37,6 +39,133 @@ test("parses a sole wallet address from Circle CLI list output", () => {
   );
 });
 
+test("parses backing EOA from Circle Gateway balance output", () => {
+  assert.equal(
+    parseCircleGatewayBackingEOA(
+      JSON.stringify({
+        data: {
+          backingEOA: "0x2222222222222222222222222222222222222222",
+        },
+      }),
+    ),
+    "0x2222222222222222222222222222222222222222",
+  );
+});
+
+test("separates Circle CLI Agent Wallet address from x402 backing EOA", async () => {
+  const calls: string[][] = [];
+  const signer = new CircleCliGatewaySigner({
+    agentWalletAddress: "0x1111111111111111111111111111111111111111",
+    chain: "ARC-TESTNET",
+    command: "circle",
+    runner: async (_command, args) => {
+      calls.push(args);
+      assert.deepEqual(args, [
+        "gateway",
+        "balance",
+        "--address",
+        "0x1111111111111111111111111111111111111111",
+        "--chain",
+        "ARC-TESTNET",
+        "--output",
+        "json",
+      ]);
+      return JSON.stringify({
+        data: {
+          backingEOA: "0x2222222222222222222222222222222222222222",
+        },
+      });
+    },
+  });
+
+  await signer.ensureAddress();
+
+  assert.equal(signer.agentWalletAddress, "0x1111111111111111111111111111111111111111");
+  assert.equal(signer.address, "0x2222222222222222222222222222222222222222");
+  assert.equal(calls.length, 1);
+});
+
+test("discovers sole Agent Wallet and then its Gateway backing EOA", async () => {
+  const calls: string[][] = [];
+  const signer = new CircleCliGatewaySigner({
+    chain: "ARC-TESTNET",
+    command: "circle",
+    runner: async (_command, args) => {
+      calls.push(args);
+      if (args[0] === "wallet") {
+        return JSON.stringify({
+          data: {
+            wallets: [{ address: "0x1111111111111111111111111111111111111111" }],
+          },
+        });
+      }
+      return JSON.stringify({
+        data: {
+          backingEOA: "0x2222222222222222222222222222222222222222",
+        },
+      });
+    },
+  });
+
+  await signer.ensureAddress();
+
+  assert.equal(signer.agentWalletAddress, "0x1111111111111111111111111111111111111111");
+  assert.equal(signer.address, "0x2222222222222222222222222222222222222222");
+  assert.deepEqual(calls, [
+    ["wallet", "list", "--chain", "ARC-TESTNET", "--type", "agent", "--output", "json"],
+    [
+      "gateway",
+      "balance",
+      "--address",
+      "0x1111111111111111111111111111111111111111",
+      "--chain",
+      "ARC-TESTNET",
+      "--output",
+      "json",
+    ],
+  ]);
+});
+
+test("typed data message.from uses backing EOA while CLI signs with Agent Wallet", async () => {
+  let signedPayload: Record<string, unknown> | undefined;
+  const signer = new CircleCliGatewaySigner({
+    agentWalletAddress: "0x1111111111111111111111111111111111111111",
+    buyerWalletAddress: "0x2222222222222222222222222222222222222222",
+    chain: "ARC-TESTNET",
+    command: "circle",
+    runner: async (_command, args) => {
+      const addressFlag = args.indexOf("--address");
+      assert.equal(args[addressFlag + 1], "0x1111111111111111111111111111111111111111");
+      signedPayload = JSON.parse(args[3] ?? "{}") as Record<string, unknown>;
+      return "0xabc123";
+    },
+  });
+  await signer.ensureAddress();
+  assert.equal(signer.address, "0x2222222222222222222222222222222222222222");
+
+  await signer.signTypedData({
+    domain: { name: "USD Coin", version: "2", chainId: 5042002 },
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+      ],
+    },
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: signer.address,
+      to: "0x3333333333333333333333333333333333333333",
+      value: 1n,
+    },
+  });
+
+  assert.equal(
+    (signedPayload?.message as Record<string, unknown>).from,
+    "0x2222222222222222222222222222222222222222",
+  );
+});
+
 test("requires explicit wallet address when multiple Agent Wallets are present", () => {
   assert.throws(
     () =>