@agent-os-lab/agent-sdk 0.1.18 → 0.1.20

package/README.md

@@ -162,6 +162,7 @@ await client.createProfile({
 await client.createAgent({
   agentId: "support-agent",
   displayName: "Support Agent",
+  billingSubjectId: "company-a/user-123",
   systemPrompt: "You are a support assistant.",
   model: "openai/gpt-5.2",
   memoryProvider: "none",
@@ -199,6 +200,62 @@ for await (const event of client.streamMessage("support-agent", session.sessionI
 }
 ```
 
+## Billing Attribution And Export
+
+Set `billingSubjectId` on Agents or Wikis when a tenant application needs cost attribution for one of its own business users, teams, or accounts. Per-request APIs that accept `billingSubjectId` can override the resource default for that request.
+
+```ts
+await client.createAgent({
+  agentId: "support-agent",
+  displayName: "Support Agent",
+  billingSubjectId: "company-a/user-123",
+  systemPrompt: "You are a support assistant.",
+  model: "openai/gpt-5.2",
+  memoryProvider: "none",
+  memoryScopeMode: "both",
+  compressionEnabled: false,
+  memoryReviewEnabled: false,
+});
+
+for await (const event of client.streamMessage("support-agent", session.sessionId, {
+  profileId: "business-user-123",
+  message: "Help me understand my invoice.",
+  billingSubjectId: "company-a/user-456",
+})) {
+  // ...
+}
+```
+
+Pull billing events from a trusted backend with `listBillingEvents`. The cursor is `afterSequence`; poll until `hasMore` is false, then store `nextSequence` for the next polling cycle.
+
+```ts
+let afterSequence = loadLastBillingSequence();
+
+while (true) {
+  const page = await client.listBillingEvents({
+    afterSequence,
+    limit: 1000,
+  });
+
+  await saveBillingEvents(page.events);
+  afterSequence = page.nextSequence;
+
+  if (!page.hasMore) {
+    await saveLastBillingSequence(afterSequence);
+    break;
+  }
+}
+```
+
+Use `billingSubjectId` to fetch one subject's ledger:
+
+```ts
+const page = await client.listBillingEvents({
+  billingSubjectId: "company-a/user-123",
+  limit: 1000,
+});
+```
+
 ## Create A Bot-Owned Agent And Wiki
 
 For tenant product setup flows, use `createBotBundle` to create a Bot with its own Agent, optional Wiki, and optional channel account in one call. The SDK creates the Wiki first, passes the generated `wikiId` into Agent creation, creates the Bot bound to that Agent, then creates the channel account bound to the Bot.
@@ -538,6 +595,6 @@ Delete operations archive or deactivate control-plane resources. `deleteAgent` a
 
 ## Coverage
 
-The server SDK covers tenant-scoped agent registry, profile registry, sessions, streaming, async runs, memory, session search, lineage, and webhooks.
+The server SDK covers tenant-scoped agent registry, profile registry, sessions, streaming, async runs, memory, session search, lineage, billing event export, and webhooks.
 
 The browser SDK covers the current-user conversation surface: sessions, sync messages, streaming messages, async runs, run polling, cancellation, and run event replay.

package/USAGE.md

@@ -78,6 +78,7 @@ The browser client strips caller-provided `authorization` and `x-hermes-tenant-i
 - Sessions and messages: create, list, get, send, stream, continue, lineage, search.
 - Attachments: create upload, confirm upload, list, get, retry conversion.
 - Async runs: create, get, cancel, replay events.
+- Billing: assign `billingSubjectId` and pull billing events with cursor pagination.
 - AG-UI: create an AG-UI chat facade, create an AG-UI HTTP agent, and inspect active runs for stream resume.
 - Memory: read, create entry, delete entry.
 - Tenant: get current tenant.
@@ -168,6 +169,7 @@ await client.createProfile({
 await client.createAgent({
   agentId: "support-agent",
   displayName: "Support Agent",
+  billingSubjectId: "company-a/user-123",
   systemPrompt: "You are a support assistant.",
   model: "openai/gpt-5.2",
   memoryProvider: "none",
@@ -177,6 +179,74 @@ await client.createAgent({
 });
 ```
 
+## Billing Attribution And Export
+
+`billingSubjectId` is the tenant application's own attribution key. Store any stable string that your business system can resolve, such as `company-a/user-123` or `account-42/team-7`. AgentOS stores the string and returns it in billing records; it does not interpret hierarchy.
+
+Resource defaults:
+
+```ts
+await client.createAgent({
+  agentId: "support-agent",
+  displayName: "Support Agent",
+  billingSubjectId: "company-a/user-123",
+  systemPrompt: "You are a support assistant.",
+  model: "openai/gpt-5.2",
+  memoryProvider: "none",
+  memoryScopeMode: "both",
+  compressionEnabled: false,
+  memoryReviewEnabled: false,
+});
+
+await client.createWiki({
+  wikiId: "support-knowledge",
+  displayName: "Support Knowledge",
+  billingSubjectId: "company-a",
+});
+```
+
+Per-request override:
+
+```ts
+await client.sendMessage("support-agent", session.sessionId, {
+  profileId: "business-user-123",
+  message: "Explain my latest invoice.",
+  billingSubjectId: "company-a/user-456",
+});
+```
+
+Billing export is server-only. Use `listBillingEvents` from a trusted backend and persist the returned `nextSequence` as your cursor. A typical sync job can run every few minutes and keep pulling pages until `hasMore` is false.
+
+```ts
+let afterSequence = await loadLastBillingSequence();
+
+while (true) {
+  const page = await client.listBillingEvents({
+    afterSequence,
+    limit: 1000,
+  });
+
+  await upsertBillingEvents(page.events);
+  afterSequence = page.nextSequence;
+
+  if (!page.hasMore) {
+    await saveLastBillingSequence(afterSequence);
+    break;
+  }
+}
+```
+
+Filter by one subject when reconciling a tenant user's bill:
+
+```ts
+const page = await client.listBillingEvents({
+  billingSubjectId: "company-a/user-123",
+  limit: 1000,
+});
+```
+
+Each event includes `sequence`, `billingSubjectId`, `source`, `sourceId`, resource ids such as `agentId`/`wikiId`/`runId`, `cost`, `currency`, `totalTokens`, and the raw `payload`.
+
 ## Creating A Bot Bundle
 
 Use `createBotBundle` when a tenant application wants a productized setup flow for a Bot-owned Agent. The SDK creates the resources in order: Wiki, Agent, Bot, then Bot channel account. If `wiki` is present, the new Agent is created with `wikiId` already bound.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-sdk",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",