@rubicon-caliga/agent-sdk 0.1.2 → 0.1.4

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.
@@ -128,6 +126,25 @@ export class CircleAgentWalletEngine implements AgentPaymentEngine {
       paymentPayload: await this.x402.createPaymentPayload(session.paymentRequired as never),
     };
   }
+
+  async createChunkPayment(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest> {
+    if (!session.paymentRequired) {
+      throw new Error("Session did not include an x402 payment requirement");
+    }
+    await this.signer.ensureAddress();
+    const amountAtomic = BigInt(session.wordPaymentAtomic) * BigInt(input.maxWords);
+    return {
+      paymentPayload: await this.x402.createPaymentPayload(
+        withChunkRequirement(session.paymentRequired, {
+          amountAtomic: `${amountAtomic}`,
+          maxWords: input.maxWords,
+          nextSequence: input.nextSequence,
+          sessionId: session.sessionId,
+        }) as never,
+      ),
+      maxWords: input.maxWords,
+    };
+  }
 }
 
 /**
@@ -208,3 +225,29 @@ function isEip712Field(field: unknown): field is { name: string; type: string }
     typeof (field as { type?: unknown }).type === "string"
   );
 }
+
+function withChunkRequirement(
+  paymentRequired: unknown,
+  chunk: { amountAtomic: `${bigint}`; maxWords: number; nextSequence: number; sessionId: string },
+): unknown {
+  const source = paymentRequired as { accepts?: Array<Record<string, unknown>> };
+  if (!Array.isArray(source.accepts)) {
+    return paymentRequired;
+  }
+  return {
+    ...(paymentRequired as Record<string, unknown>),
+    accepts: source.accepts.map((accept) => ({
+      ...accept,
+      amount: chunk.amountAtomic,
+      extra: {
+        ...((accept.extra as Record<string, unknown> | undefined) ?? {}),
+        amountAtomic: chunk.amountAtomic,
+        maxWords: chunk.maxWords,
+        sequence: chunk.nextSequence,
+        authorizationMode: "chunk",
+        nonce: `${chunk.sessionId}:${chunk.nextSequence}:${chunk.maxWords}`,
+        idempotencyKey: `${chunk.sessionId}:${chunk.nextSequence}:${chunk.maxWords}`,
+      },
+    })),
+  };
+}

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

@@ -49,10 +49,10 @@ interface TypedDataRequest {
 }
 
 /**
- * Circle CLI / Agent Wallet payment engine. It creates the one-word x402
- * payment payload for Rubicon's session-first flow and delegates EIP-712
- * signing to `circle wallet sign typed-data`, so agents never need raw private
- * keys or hand-built x402 payloads.
+ * Circle CLI / Agent Wallet payment engine. It delegates EIP-712 signing to
+ * `circle wallet sign typed-data`, so agents never need raw private keys or
+ * hand-built Circle / Arc payloads. Current gateways may call the legacy
+ * one-word method as a chunk-compatibility path.
  */
 export class CircleCliGatewayPaymentEngine implements AgentPaymentEngine {
   private readonly x402 = new x402Client();
@@ -74,13 +74,32 @@ export class CircleCliGatewayPaymentEngine 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");
     }
     await this.signer.ensureAddress();
     return {
       paymentPayload: await this.x402.createPaymentPayload(session.paymentRequired as never),
     };
   }
+
+  async createChunkPayment(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest> {
+    if (!session.paymentRequired) {
+      throw new Error("Session did not include an x402 payment requirement");
+    }
+    await this.signer.ensureAddress();
+    const amountAtomic = BigInt(session.wordPaymentAtomic) * BigInt(input.maxWords);
+    return {
+      paymentPayload: await this.x402.createPaymentPayload(
+        withChunkRequirement(session.paymentRequired, {
+          amountAtomic: `${amountAtomic}`,
+          maxWords: input.maxWords,
+          nextSequence: input.nextSequence,
+          sessionId: session.sessionId,
+        }) as never,
+      ),
+      maxWords: input.maxWords,
+    };
+  }
 }
 
 export class CircleCliGatewaySigner {
@@ -263,6 +282,32 @@ function findString(value: unknown, keys: string[]): string | undefined {
   return undefined;
 }
 
+function withChunkRequirement(
+  paymentRequired: unknown,
+  chunk: { amountAtomic: `${bigint}`; maxWords: number; nextSequence: number; sessionId: string },
+): unknown {
+  const source = paymentRequired as { accepts?: Array<Record<string, unknown>> };
+  if (!Array.isArray(source.accepts)) {
+    return paymentRequired;
+  }
+  return {
+    ...(paymentRequired as Record<string, unknown>),
+    accepts: source.accepts.map((accept) => ({
+      ...accept,
+      amount: chunk.amountAtomic,
+      extra: {
+        ...((accept.extra as Record<string, unknown> | undefined) ?? {}),
+        amountAtomic: chunk.amountAtomic,
+        maxWords: chunk.maxWords,
+        sequence: chunk.nextSequence,
+        authorizationMode: "chunk",
+        nonce: `${chunk.sessionId}:${chunk.nextSequence}:${chunk.maxWords}`,
+        idempotencyKey: `${chunk.sessionId}:${chunk.nextSequence}:${chunk.maxWords}`,
+      },
+    })),
+  };
+}
+
 function parseJson(value: string): unknown {
   try {
     return JSON.parse(value);

package/src/payment-engine.ts

@@ -1,20 +1,54 @@
-import type { StartSessionResponse, StreamPaymentRequest } from "@rubicon-caliga/core";
+import type { StartSessionResponse, StreamAuthorizationRequest, StreamPaymentRequest } from "@rubicon-caliga/core";
 
 /**
- * Produces the payment payload for exactly one word. Called once per word by the
- * SDK's read loop — application developers never assemble payments themselves.
+ * Produces Circle / Arc authorization payloads for Rubicon reads. Preferred
+ * engines authorize a whole session once; fallback engines authorize chunks.
+ * Legacy one-word payloads remain supported for older gateways and tests.
  */
 export interface AgentPaymentEngine {
+  createSessionAuthorization?(session: StartSessionResponse): Promise<StreamAuthorizationRequest>;
+  createChunkPayment?(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest>;
+  /** @deprecated Compatibility path for one-word x402 gateways. */
   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.
+ * Development engine. Declares the authorized 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 createSessionAuthorization(session: StartSessionResponse): Promise<StreamAuthorizationRequest> {
+    return {
+      authorizationPayload: {
+        scheme: "development-static",
+        network: this.network,
+        sessionId: session.sessionId,
+        amountAtomic: session.authorizationRequired?.maxAuthorizedAtomic ?? session.maxArticlePriceAtomic,
+        meteringUnit: "word",
+        authorizationMode: "session",
+      },
+    };
+  }
+
+  async createChunkPayment(session: StartSessionResponse, input: { nextSequence: number; maxWords: number }): Promise<StreamPaymentRequest> {
+    const amountAtomic = BigInt(session.wordPaymentAtomic) * BigInt(input.maxWords);
+    return {
+      paymentPayload: {
+        scheme: "development-static",
+        network: this.network,
+        sessionId: session.sessionId,
+        amountAtomic: `${amountAtomic}`,
+        meteringUnit: "word",
+        authorizationMode: "chunk",
+        maxWords: input.maxWords,
+        nextSequence: input.nextSequence,
+      },
+      maxWords: input.maxWords,
+    };
+  }
+
   async createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest> {
     return {
       paymentPayload: {