chore: agent.usage() (#38790)

Author: Skn0tt

docs/src/api/class-pageagent.md

@@ -96,3 +96,19 @@ Task to perform using agentic loop.
 
 ### option: PageAgent.perform.-inline- = %%-page-agent-call-options-v1.58-%%
 * since: v1.58
+
+## async method: PageAgent.usage
+* since: v1.58
+- returns: <[Object]>
+  - `turns` <[int]>
+  - `inputTokens` <[int]>
+  - `outputTokens` <[int]>
+
+Returns the current token usage for this agent.
+
+**Usage**
+
+```js
+const usage = await agent.usage();
+console.log(`Tokens used: ${usage.inputTokens} in, ${usage.outputTokens} out`);
+```

packages/playwright-client/types/types.d.ts

@@ -5462,6 +5462,25 @@ export interface PageAgent {
     };
   }>;
 
+  /**
+   * Returns the current token usage for this agent.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const usage = await agent.usage();
+   * console.log(`Tokens used: ${usage.inputTokens} in, ${usage.outputTokens} out`);
+   * ```
+   *
+   */
+  usage(): Promise<{
+    turns: number;
+
+    inputTokens: number;
+
+    outputTokens: number;
+  }>;
+
   [Symbol.asyncDispose](): Promise<void>;
 }
 

packages/playwright-core/src/client/pageAgent.ts

@@ -56,6 +56,11 @@ export class PageAgent extends ChannelOwner<channels.PageAgentChannel> implement
     return { result, usage };
   }
 
+  async usage() {
+    const { usage } = await this._channel.usage({});
+    return usage;
+  }
+
   async dispose() {
     await this._channel.dispose();
   }

packages/playwright-core/src/protocol/validator.ts

@@ -2939,6 +2939,10 @@ scheme.PageAgentExtractResult = tObject({
 });
 scheme.PageAgentDisposeParams = tOptional(tObject({}));
 scheme.PageAgentDisposeResult = tOptional(tObject({}));
+scheme.PageAgentUsageParams = tOptional(tObject({}));
+scheme.PageAgentUsageResult = tObject({
+  usage: tType('AgentUsage'),
+});
 scheme.AgentUsage = tObject({
   turns: tInt,
   inputTokens: tInt,

packages/playwright-core/src/server/dispatchers/pageAgentDispatcher.ts

@@ -62,6 +62,10 @@ export class PageAgentDispatcher extends Dispatcher<SdkObject, channels.PageAgen
     return { result, usage: this._usage };
   }
 
+  async usage(params: channels.PageAgentUsageParams, progress: Progress): Promise<channels.PageAgentUsageResult> {
+    return { usage: this._usage };
+  }
+
   async dispose(params: channels.PageAgentDisposeParams, progress: Progress): Promise<void> {
   }
 

packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts

@@ -316,5 +316,6 @@ export const methodMetainfo = new Map<string, { internal?: boolean, title?: stri
   ['PageAgent.perform', { title: 'Perform "{task}"', }],
   ['PageAgent.expect', { title: 'Expect "{expectation}"', }],
   ['PageAgent.extract', { title: 'Extract "{query}"', }],
-  ['PageAgent.dispose', { internal: true, }]
+  ['PageAgent.dispose', { internal: true, }],
+  ['PageAgent.usage', { title: 'Get agent usage', group: 'configuration', }]
 ]);

packages/playwright-core/types/types.d.ts

@@ -5462,6 +5462,25 @@ export interface PageAgent {
     };
   }>;
 
+  /**
+   * Returns the current token usage for this agent.
+   *
+   * **Usage**
+   *
+   * ```js
+   * const usage = await agent.usage();
+   * console.log(`Tokens used: ${usage.inputTokens} in, ${usage.outputTokens} out`);
+   * ```
+   *
+   */
+  usage(): Promise<{
+    turns: number;
+
+    inputTokens: number;
+
+    outputTokens: number;
+  }>;
+
   [Symbol.asyncDispose](): Promise<void>;
 }
 

packages/playwright/src/index.ts

@@ -486,6 +486,10 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures> = ({
 
     await use(agent);
 
+    const usage = await agent.usage();
+    if (usage.turns > 0)
+      await testInfoImpl.attach('agent-usage', { contentType: 'application/json', body: Buffer.from(JSON.stringify(usage, null, 2)) });
+
     if (!resolvedCacheFile || !cacheOutFile)
       return;
     if (testInfo.status !== 'passed')

packages/protocol/src/channels.d.ts

@@ -5103,6 +5103,7 @@ export interface PageAgentChannel extends PageAgentEventTarget, EventTargetChann
   expect(params: PageAgentExpectParams, progress?: Progress): Promise<PageAgentExpectResult>;
   extract(params: PageAgentExtractParams, progress?: Progress): Promise<PageAgentExtractResult>;
   dispose(params?: PageAgentDisposeParams, progress?: Progress): Promise<PageAgentDisposeResult>;
+  usage(params?: PageAgentUsageParams, progress?: Progress): Promise<PageAgentUsageResult>;
 }
 export type PageAgentTurnEvent = {
   role: string,
@@ -5165,6 +5166,11 @@ export type PageAgentExtractResult = {
 export type PageAgentDisposeParams = {};
 export type PageAgentDisposeOptions = {};
 export type PageAgentDisposeResult = void;
+export type PageAgentUsageParams = {};
+export type PageAgentUsageOptions = {};
+export type PageAgentUsageResult = {
+  usage: AgentUsage,
+};
 
 export interface PageAgentEvents {
   'turn': PageAgentTurnEvent;

packages/protocol/src/protocol.yml

@@ -4352,6 +4352,12 @@ PageAgent:
     dispose:
       internal: true
 
+    usage:
+      title: 'Get agent usage'
+      group: configuration
+      returns:
+        usage: AgentUsage
+
   events:
 
     turn: