@rubicon-caliga/agent-sdk 0.1.2 → 0.1.4

package/dist/payment-engine.d.ts

@@ -1,18 +1,30 @@
-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 declare class StaticPaymentEngine implements AgentPaymentEngine {
     private readonly network;
     constructor(network?: string);
+    createSessionAuthorization(session: StartSessionResponse): Promise<StreamAuthorizationRequest>;
+    createChunkPayment(session: StartSessionResponse, input: {
+        nextSequence: number;
+        maxWords: number;
+    }): Promise<StreamPaymentRequest>;
     createWordPayment(session: StartSessionResponse): Promise<StreamPaymentRequest>;
 }
 //# sourceMappingURL=payment-engine.d.ts.map

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

@@ -1 +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;;;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"}
+{"version":3,"file":"payment-engine.d.ts","sourceRoot":"","sources":["../src/payment-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEnH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B,CAAC,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAChG,kBAAkB,CAAC,CAAC,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrI,iEAAiE;IACjE,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,0BAA0B,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAa9F,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiBnI,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAWtF"}

package/dist/payment-engine.js

@@ -1,12 +1,40 @@
 /**
- * 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 {
     network;
     constructor(network = "eip155:5042002") {
         this.network = network;
     }
+    async createSessionAuthorization(session) {
+        return {
+            authorizationPayload: {
+                scheme: "development-static",
+                network: this.network,
+                sessionId: session.sessionId,
+                amountAtomic: session.authorizationRequired?.maxAuthorizedAtomic ?? session.maxArticlePriceAtomic,
+                meteringUnit: "word",
+                authorizationMode: "session",
+            },
+        };
+    }
+    async createChunkPayment(session, input) {
+        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) {
         return {
             paymentPayload: {

package/dist/payment-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-engine.js","sourceRoot":"","sources":["../src/payment-engine.ts"],"names":[],"mappings":"AAUA;;;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"}
+{"version":3,"file":"payment-engine.js","sourceRoot":"","sources":["../src/payment-engine.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IACD;IAA7B,YAA6B,UAAU,gBAAgB;QAA1B,YAAO,GAAP,OAAO,CAAmB;IAAG,CAAC;IAE3D,KAAK,CAAC,0BAA0B,CAAC,OAA6B;QAC5D,OAAO;YACL,oBAAoB,EAAE;gBACpB,MAAM,EAAE,oBAAoB;gBAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,YAAY,EAAE,OAAO,CAAC,qBAAqB,EAAE,mBAAmB,IAAI,OAAO,CAAC,qBAAqB;gBACjG,YAAY,EAAE,MAAM;gBACpB,iBAAiB,EAAE,SAAS;aAC7B;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,OAA6B,EAAE,KAAiD;QACvG,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChF,OAAO;YACL,cAAc,EAAE;gBACd,MAAM,EAAE,oBAAoB;gBAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,YAAY,EAAE,GAAG,YAAY,EAAE;gBAC/B,YAAY,EAAE,MAAM;gBACpB,iBAAiB,EAAE,OAAO;gBAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,YAAY,EAAE,KAAK,CAAC,YAAY;aACjC;YACD,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACzB,CAAC;IACJ,CAAC;IAED,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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubicon-caliga/agent-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Client SDK for autonomous agents consuming per-word article streams via Rubicon x402.",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "@x402/evm": "^2.15.0",
     "eventsource": "^4.0.0",
     "viem": "^2.52.2",
-    "@rubicon-caliga/core": "0.1.0"
+    "@rubicon-caliga/core": "0.1.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-client.test.ts

@@ -9,6 +9,18 @@ const paymentEngine: AgentPaymentEngine = {
   },
 };
 
+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);
@@ -80,6 +92,218 @@ test("run receipt preserves Gateway settlement receipt fields", async () => {
   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(3),
+        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" },
+          { sequence: 1, word: "streams", priceAtomic: "1" },
+          { sequence: 2, word: "chunks", priceAtomic: "1" },
+        ],
+        text: "Rubicon streams chunks",
+        wordsPaid: 3,
+        wordsDelivered: 3,
+        paidAtomic: "3",
+        completed: true,
+        settlementIds: ["settlement_chunk"],
+        payment: {
+          ...payment(0, "Rubicon streams chunks"),
+          amountAtomic: "3",
+          bundleSequence: 0,
+          wordsDelivered: 3,
+          pricePerWordAtomic: "1",
+          text: "Rubicon streams chunks",
+        },
+      });
+    }
+    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, 1);
+  assert.equal(receipt.payments[0]?.amountAtomic, "3");
+  assert.equal(receipt.payments[0]?.wordsDelivered, 3);
+  assert.deepEqual(receipt.settlementIds, ["settlement_chunk"]);
+});
+
+test("read defaults to bundled mode and clamps bundle size to remaining article words", 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(15),
+        navigation: navigation(),
+        pricePerWordAtomic: "1",
+        maxArticlePriceAtomic: "15",
+        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, 15);
+      return jsonResponse({
+        accepted: true,
+        words: Array.from({ length: 15 }, (_, sequence) => ({ sequence, word: `w${sequence + 1}`, priceAtomic: "1" })),
+        text: Array.from({ length: 15 }, (_, index) => `w${index + 1}`).join(" "),
+        wordsPaid: 15,
+        wordsDelivered: 15,
+        paidAtomic: "15",
+        completed: true,
+        payment: { ...payment(0, "bundle"), amountAtomic: "15", wordsDelivered: 15, pricePerWordAtomic: "1" },
+      });
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  }) as typeof fetch;
+
+  const client = new RubiconClient({ baseUrl: "http://rubicon.test", paymentEngine: { ...chunkPaymentEngine, createWordPayment: paymentEngine.createWordPayment }, fetch: fetcher });
+  const events = [];
+  for await (const event of client.read({ articleId: "article_1", maxSpendAtomic: "100" })) {
+    events.push(event.type);
+  }
+  assert.deepEqual(events, ["session.started", "article.bundle", "article.usage", "article.completed"]);
+});
+
+test("bundled mode clamps bundle size to budget and max words", async () => {
+  const seenMaxWords: number[] = [];
+  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(100),
+        navigation: navigation(),
+        pricePerWordAtomic: "2",
+        maxArticlePriceAtomic: "200",
+        conversationId: "conversation_1",
+        wordPaymentAtomic: "2",
+        gatewayFeeBps: 0,
+        paymentRequired: { accepts: [{ amount: "2" }] },
+        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 };
+      seenMaxWords.push(body.maxWords);
+      return jsonResponse({
+        accepted: true,
+        words: Array.from({ length: body.maxWords }, (_, sequence) => ({ sequence, word: `w${sequence + 1}`, priceAtomic: "2" })),
+        text: "ok",
+        wordsPaid: body.maxWords,
+        wordsDelivered: body.maxWords,
+        paidAtomic: `${body.maxWords * 2}`,
+        completed: true,
+      });
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  }) as typeof fetch;
+
+  const client = new RubiconClient({
+    baseUrl: "http://rubicon.test",
+    paymentEngine: { ...chunkPaymentEngine, createWordPayment: paymentEngine.createWordPayment },
+    fetch: fetcher,
+  });
+  await client.run({ articleId: "article_1", maxSpendAtomic: "12", maxWords: 10 });
+  assert.deepEqual(seenMaxWords, [6]);
+});
+
+test("explicit word stream mode keeps legacy word events", 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(1),
+        navigation: navigation(),
+        pricePerWordAtomic: "1",
+        maxArticlePriceAtomic: "1",
+        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/payments")) {
+      return jsonResponse({
+        accepted: true,
+        sequence: 0,
+        word: "Rubicon",
+        priceAtomic: "1",
+        wordsPaid: 1,
+        wordsDelivered: 1,
+        paidAtomic: "1",
+        completed: true,
+      });
+    }
+    throw new Error(`Unexpected fetch: ${url}`);
+  }) as typeof fetch;
+
+  const client = new RubiconClient({
+    baseUrl: "http://rubicon.test",
+    paymentEngine: { ...chunkPaymentEngine, createWordPayment: paymentEngine.createWordPayment },
+    fetch: fetcher,
+  });
+  const events = [];
+  for await (const event of client.read({ articleId: "article_1", maxSpendAtomic: "10", streamMode: "word" })) {
+    events.push(event.type);
+  }
+  assert.deepEqual(events, ["session.started", "article.word", "article.usage", "article.completed"]);
+});
+
 function jsonResponse(body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status: 200,
@@ -87,7 +311,7 @@ function jsonResponse(body: unknown): Response {
   });
 }
 
-function article() {
+function article(totalWords = 1) {
   return {
     articleId: "article_1",
     creatorId: "creator_1",
@@ -95,9 +319,9 @@ function article() {
     title: "Title",
     author: "Author",
     state: "published",
-    totalWords: 1,
+    totalWords,
     pricePerWordAtomic: "1",
-    maxArticlePriceAtomic: "1",
+    maxArticlePriceAtomic: `${totalWords}`,
     sections: [],
   };
 }
@@ -116,3 +340,17 @@ function navigation() {
     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,8 @@ import type {
   StartConversationResponse,
   StartSessionRequest,
   StartSessionResponse,
+  StreamChunkResponse,
+  StreamMode,
   StreamPaymentRequest,
   StreamPaymentResponse,
   WordPaymentReceipt,
@@ -63,6 +65,28 @@ export type RubiconReadEvent =
       payment?: WordPaymentReceipt;
       text: string;
     }
+  | {
+      type: "article.bundle";
+      bundleSequence: number;
+      words: Array<{ sequence: number; word: string; priceAtomic: `${bigint}`; payment?: WordPaymentReceipt }>;
+      text: string;
+      bundleText: string;
+      wordCount: number;
+      amountAtomic: `${bigint}`;
+      payment?: WordPaymentReceipt;
+      wordsRead: number;
+      amountPaidAtomic: `${bigint}`;
+      completed: boolean;
+    }
+  /** @deprecated Use article.bundle. */
+  | {
+      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 +100,10 @@ export interface ReadOptions {
   maxSpendAtomic?: `${bigint}`;
   budget?: Budget;
   maxWords?: number;
+  /** Number of words to authorize and deliver per gateway round trip when supported. */
+  chunkWords?: number;
+  /** Default is bundled. Use word for legacy one-word events/payments. */
+  streamMode?: StreamMode;
   /** Return true to stop reading once enough information has been collected. */
   stopWhen?: (state: {
     text: string;
@@ -92,8 +120,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 +198,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",
@@ -210,6 +250,14 @@ export class RubiconClient {
           wordsRead: event.wordsRead,
           amountPaidAtomic: event.amountPaidAtomic,
         });
+      } else if (event.type === "article.bundle") {
+        for (const entry of event.words) {
+          await options.onWord?.(entry.word, {
+            text: event.text,
+            wordsRead: event.wordsRead,
+            amountPaidAtomic: event.amountPaidAtomic,
+          });
+        }
       }
       if (event.type === "article.completed") {
         receipt = event.receipt;
@@ -222,8 +270,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 +322,11 @@ export class RubiconClient {
     const transactionHashes: string[] = [];
     const settlementIds: string[] = [];
     const payments: WordPaymentReceipt[] = [];
+    const streamMode = options.streamMode ?? "bundled";
+    const bundleWords = normalizeBundleWords(options.chunkWords);
+    const useBundles = streamMode === "bundled" && typeof this.paymentEngine.createChunkPayment === "function";
+    const selectedWordLimit = selectedRangeWordLimit(session, sectionId);
+    let bundleSequence = 0;
     let stopReason: ReadReceipt["stopReason"] = "article_completed";
     let completed = false;
 
@@ -308,6 +361,84 @@ export class RubiconClient {
         break;
       }
 
+      if (useBundles) {
+        const remainingRequestedWords = options.maxWords === undefined ? Number.MAX_SAFE_INTEGER : Math.max(0, options.maxWords - wordsRead);
+        const affordableWords = Number((budgetAtomic - amountPaid) / wordPaymentAtomic);
+        const remainingArticleWords =
+          selectedWordLimit === undefined ? Number.MAX_SAFE_INTEGER : Math.max(0, selectedWordLimit - wordsRead);
+        const maxWords = Math.min(bundleWords, remainingRequestedWords, affordableWords, remainingArticleWords);
+        if (maxWords < 1) {
+          stopReason = selectedWordLimit !== undefined && wordsRead >= selectedWordLimit ? "article_completed" : "budget_reached";
+          break;
+        }
+        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;
+        }
+        if (result.payment) {
+          payments.push(result.payment);
+        } else {
+          for (const entry of result.words) {
+            if (entry.payment) {
+              payments.push(entry.payment);
+            }
+          }
+        }
+        const previousAmountPaid = amountPaid;
+        const bundleText = result.text || result.words.map((entry) => entry.word).join(" ");
+        for (const entry of result.words) {
+          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.bundle",
+          bundleSequence,
+          words: result.words,
+          text,
+          bundleText,
+          wordCount: result.words.length,
+          amountAtomic: result.payment?.amountAtomic ?? `${amountPaid - previousAmountPaid}`,
+          payment: result.payment,
+          wordsRead,
+          amountPaidAtomic: `${amountPaid}`,
+          completed: result.completed,
+        };
+        bundleSequence += 1;
+        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 +522,16 @@ export class RubiconClient {
 
 /** Backwards-compatible alias. */
 export const AgentClient = RubiconClient;
+
+function normalizeBundleWords(chunkWords: number | undefined): number {
+  if (chunkWords === undefined) return 32;
+  if (!Number.isInteger(chunkWords) || chunkWords < 1) return 1;
+  return Math.min(chunkWords, 256);
+}
+
+function selectedRangeWordLimit(session: StartSessionResponse, sectionId: string | undefined): number | undefined {
+  if (!sectionId || sectionId === "full-article") {
+    return session.article.totalWords;
+  }
+  return session.navigation.sections.find((section) => section.sectionId === sectionId)?.wordCount;
+}