feat(turns): extract turns from agent-tokens artifact in workflow_run_id mode (#20)

* feat(turns): extract turns from agent-tokens artifact in workflow_run_id mode

* docs: document turns field in agent-tokens artifact format

* test: add turns to inline CI test and lock file token extraction

* test: add manual turns test workflow (workflow_dispatch via gh-aw)

Author: adamhenson

.github/aw/actions-lock.json

@@ -5,6 +5,11 @@
       "version": "v8",
       "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
     },
+    "github/gh-aw-actions/setup@v0.67.4": {
+      "repo": "github/gh-aw-actions/setup",
+      "version": "v0.67.4",
+      "sha": "9d6ae06250fc0ec536a0e5f35de313b35bad7246"
+    },
     "github/gh-aw/actions/setup@v0.55.0": {
       "repo": "github/gh-aw/actions/setup",
       "version": "v0.55.0",

.github/workflows/agent-review.lock.yml

@@ -0,0 +1,41 @@
+---
+name: "Agent: Turns Test"
+description: "Manually-triggered agent run to verify turns tracking end-to-end"
+
+engine: claude
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to check out (defaults to current)"
+        required: false
+        default: ""
+
+timeout-minutes: 10
+
+permissions:
+  contents: read
+  pull-requests: read
+
+tools:
+  bash: ["cat", "head", "tail", "grep", "wc", "ls", "find", "echo"]
+  github:
+    toolsets: [repos]
+
+safe-outputs:
+  noop:
+    max: 1
+---
+
+# Turns Test
+
+You are verifying that the AgentMeter action correctly captures agent turn counts.
+
+## Your Task
+
+1. List the files in the root of this repository using `ls`.
+2. Count the number of TypeScript source files in `src/` using `find`.
+3. Report your findings using `noop` with a brief summary of what you found.
+
+Keep it short. This is a smoke-test to generate a real agent run with a known turn count.

.github/workflows/agent-turns-test.lock.yml

@@ -4,6 +4,7 @@ on:
   workflow_run:
     workflows:
       - "Agent: Code Review"
+      - "Agent: Turns Test"
     types:
       - completed
 

.github/workflows/agent-turns-test.md

@@ -256,11 +256,17 @@ The action reads token counts from an `agent-tokens` artifact uploaded by the ag
       OUTPUT=$(echo "$RESULT_LINE" | jq -r '.usage.output_tokens // 0')
       CACHE_READ=$(echo "$RESULT_LINE" | jq -r '.usage.cache_read_input_tokens // 0')
       CACHE_WRITE=$(echo "$RESULT_LINE" | jq -r '.usage.cache_creation_input_tokens // 0')
+      TURNS=$(echo "$RESULT_LINE" | jq -r '.num_turns // empty')
     else
-      INPUT=0; OUTPUT=0; CACHE_READ=0; CACHE_WRITE=0
+      INPUT=0; OUTPUT=0; CACHE_READ=0; CACHE_WRITE=0; TURNS=""
+    fi
+    if [ -n "$TURNS" ]; then
+      printf '{"input_tokens":%s,"output_tokens":%s,"cache_read_tokens":%s,"cache_write_tokens":%s,"turns":%s}\n' \
+        "$INPUT" "$OUTPUT" "$CACHE_READ" "$CACHE_WRITE" "$TURNS" > /tmp/gh-aw/agent-tokens.json
+    else
+      printf '{"input_tokens":%s,"output_tokens":%s,"cache_read_tokens":%s,"cache_write_tokens":%s}\n' \
+        "$INPUT" "$OUTPUT" "$CACHE_READ" "$CACHE_WRITE" > /tmp/gh-aw/agent-tokens.json
     fi
-    printf '{"input_tokens":%s,"output_tokens":%s,"cache_read_tokens":%s,"cache_write_tokens":%s}\n' \
-      "$INPUT" "$OUTPUT" "$CACHE_READ" "$CACHE_WRITE" > /tmp/gh-aw/agent-tokens.json
 
 - name: Upload token data
   if: always()
@@ -282,8 +288,8 @@ If you're not using gh-aw, add these two steps to your agent job to write and up
 - name: Write token counts
   if: always()
   run: |
-    printf '{"input_tokens":%s,"output_tokens":%s,"cache_read_tokens":%s,"cache_write_tokens":%s}\n' \
-      "$INPUT_TOKENS" "$OUTPUT_TOKENS" "$CACHE_READ_TOKENS" "$CACHE_WRITE_TOKENS" \
+    printf '{"input_tokens":%s,"output_tokens":%s,"cache_read_tokens":%s,"cache_write_tokens":%s,"turns":%s}\n' \
+      "$INPUT_TOKENS" "$OUTPUT_TOKENS" "$CACHE_READ_TOKENS" "$CACHE_WRITE_TOKENS" "$TURNS" \
       > /tmp/agent-tokens.json
 
 - uses: actions/upload-artifact@v4
@@ -293,7 +299,7 @@ If you're not using gh-aw, add these two steps to your agent job to write and up
     path: /tmp/agent-tokens.json
 ```
 
-Replace `$INPUT_TOKENS` etc. with however your agent exposes token counts (step outputs, env vars, parsed log lines).
+Replace `$INPUT_TOKENS` etc. with however your agent exposes token counts (step outputs, env vars, parsed log lines). `turns` is optional — omit it from the JSON if your agent doesn't expose an iteration count.
 
 ---
 

.github/workflows/agentmeter.yml

@@ -301,6 +301,38 @@ describe('resolveWorkflowRun', () => {
     });
   });
 
+  it('extracts turns from artifact when present', async () => {
+    const json =
+      '{"input_tokens":1000,"output_tokens":200,"cache_read_tokens":500,"cache_write_tokens":100,"turns":42}';
+    const zip = makeTokenZip(json);
+
+    const octokit = makeOctokit({
+      artifacts: [{ name: 'agent-tokens', id: 999 }],
+      artifactZip: zip,
+    });
+    mockGetOctokit.mockReturnValue(octokit as never);
+
+    const result = await resolveWorkflowRun(baseArgs);
+
+    expect(result.artifactTurns).toBe(42);
+  });
+
+  it('sets artifactTurns to null when turns absent from artifact', async () => {
+    const json =
+      '{"input_tokens":1000,"output_tokens":200,"cache_read_tokens":500,"cache_write_tokens":100}';
+    const zip = makeTokenZip(json);
+
+    const octokit = makeOctokit({
+      artifacts: [{ name: 'agent-tokens', id: 999 }],
+      artifactZip: zip,
+    });
+    mockGetOctokit.mockReturnValue(octokit as never);
+
+    const result = await resolveWorkflowRun(baseArgs);
+
+    expect(result.artifactTurns).toBeNull();
+  });
+
   it('defaults output_tokens to 0 when missing from artifact', async () => {
     const zip = makeTokenZip(
       '{"input_tokens":1000,"cache_read_tokens":500,"cache_write_tokens":100}'

README.md

@@ -49,6 +49,7 @@ export async function run(): Promise<void> {
   // timestamps, trigger number, and agent-tokens artifact. This removes the need
   // for manual pre-steps in the caller's companion workflow.
   let workflowRunTokens: ReturnType<typeof resolveTokens>;
+  let artifactTurns: number | null = null;
   let resolvedTriggerNumber = inputs.triggerNumber ?? ctx.triggerNumber;
   let resolvedTriggerEvent = inputs.triggerEvent || ctx.triggerType;
   let resolvedTriggerRef: string | null = null;
@@ -102,6 +103,7 @@ export async function run(): Promise<void> {
       // companion workflow and would misattribute if used as a fallback here.
       resolvedWorkflowName = runData.workflowName;
       workflowRunTokens = runData.tokens;
+      artifactTurns = runData.artifactTurns;
     }
   }
 
@@ -155,8 +157,11 @@ export async function run(): Promise<void> {
       ? Math.max(0, Math.round((endMs - startMs) / 1000))
       : 0;
 
+  // Priority: explicit input → artifact (workflow_run_id mode) → extracted from agent_output
   const resolvedTurns =
-    inputs.turns ?? (inputs.agentOutput ? extractTurnsFromOutput(inputs.agentOutput) : null);
+    inputs.turns ??
+    artifactTurns ??
+    (inputs.agentOutput ? extractTurnsFromOutput(inputs.agentOutput) : null);
 
   const result = await submitRun({
     apiKey: inputs.apiKey,

__tests__/workflow-run.test.ts

@@ -154,6 +154,8 @@ export interface AgentTokensArtifact {
   cache_read_tokens: number;
   /** Cache write tokens */
   cache_write_tokens: number;
+  /** Number of agent turns/iterations (optional — populated by agent workflows that track it) */
+  turns?: number;
 }
 
 /**