opencastle 0.21.1 → 0.22.0

package/src/cli/convoy/store.test.ts

@@ -84,11 +84,11 @@ describe('DB creation', () => {
     expect(row.journal_mode).toBe('wal')
   })
 
-  it('sets schema version to 2', () => {
+  it('sets schema version to 3', () => {
     const db = new DatabaseSync(dbPath)
     const row = db.prepare('PRAGMA user_version').get() as { user_version: number }
     db.close()
-    expect(row.user_version).toBe(2)
+    expect(row.user_version).toBe(3)
   })
 
   it('creates all required tables', () => {
@@ -113,7 +113,7 @@ describe('DB creation', () => {
     store2.close()
     // Reassign so afterEach does not double-close
     store = createConvoyStore(dbPath)
-    expect(row.user_version).toBe(2)
+    expect(row.user_version).toBe(3)
   })
 })
 
@@ -192,7 +192,180 @@ describe('schema migration', () => {
     verifyDb.close()
 
     expect(cols.map(c => c.name)).toContain('adapter')
-    expect(version.user_version).toBe(2)
+    // v1 chains through v2→v3 in one init, so final version is 3
+    expect(version.user_version).toBe(3)
+  })
+
+  it('schema migration v2 to v3 adds cost columns', () => {
+    // Create a v2 database manually (has adapter column but no cost columns)
+    const v2DbPath = join(tmpDir, 'v2.db')
+    const rawDb = new DatabaseSync(v2DbPath)
+    rawDb.exec(`
+      CREATE TABLE convoy (
+        id          TEXT PRIMARY KEY,
+        name        TEXT NOT NULL,
+        spec_hash   TEXT NOT NULL,
+        status      TEXT NOT NULL DEFAULT 'pending',
+        branch      TEXT,
+        created_at  TEXT NOT NULL,
+        started_at  TEXT,
+        finished_at TEXT,
+        spec_yaml   TEXT NOT NULL
+      );
+      CREATE TABLE task (
+        id          TEXT PRIMARY KEY,
+        convoy_id   TEXT NOT NULL REFERENCES convoy(id),
+        phase       INTEGER NOT NULL,
+        prompt      TEXT NOT NULL,
+        agent       TEXT NOT NULL DEFAULT 'developer',
+        adapter     TEXT,
+        model       TEXT,
+        timeout_ms  INTEGER NOT NULL DEFAULT 1800000,
+        status      TEXT NOT NULL DEFAULT 'pending',
+        worker_id   TEXT,
+        worktree    TEXT,
+        output      TEXT,
+        exit_code   INTEGER,
+        started_at  TEXT,
+        finished_at TEXT,
+        retries     INTEGER NOT NULL DEFAULT 0,
+        max_retries INTEGER NOT NULL DEFAULT 1,
+        files       TEXT,
+        depends_on  TEXT
+      );
+      CREATE TABLE worker (
+        id             TEXT PRIMARY KEY,
+        task_id        TEXT REFERENCES task(id),
+        adapter        TEXT NOT NULL,
+        pid            INTEGER,
+        session_id     TEXT,
+        status         TEXT NOT NULL DEFAULT 'spawned',
+        worktree       TEXT,
+        created_at     TEXT NOT NULL,
+        finished_at    TEXT,
+        last_heartbeat TEXT
+      );
+      CREATE TABLE event (
+        id         INTEGER PRIMARY KEY AUTOINCREMENT,
+        convoy_id  TEXT REFERENCES convoy(id),
+        task_id    TEXT,
+        worker_id  TEXT,
+        type       TEXT NOT NULL,
+        data       TEXT,
+        created_at TEXT NOT NULL
+      );
+    `)
+    rawDb.exec('PRAGMA user_version = 2')
+    rawDb.close()
+
+    // Open with createConvoyStore — should apply the v2→v3 migration
+    const v2Store = createConvoyStore(v2DbPath)
+    v2Store.close()
+
+    // Verify cost columns were added
+    const verifyDb = new DatabaseSync(v2DbPath)
+    const taskCols = verifyDb.prepare('PRAGMA table_info(task)').all() as Array<{ name: string }>
+    const convoyCols = verifyDb.prepare('PRAGMA table_info(convoy)').all() as Array<{ name: string }>
+    const version = verifyDb.prepare('PRAGMA user_version').get() as { user_version: number }
+    verifyDb.close()
+
+    const taskColNames = taskCols.map(c => c.name)
+    expect(taskColNames).toContain('prompt_tokens')
+    expect(taskColNames).toContain('completion_tokens')
+    expect(taskColNames).toContain('total_tokens')
+    expect(taskColNames).toContain('cost_usd')
+
+    const convoyColNames = convoyCols.map(c => c.name)
+    expect(convoyColNames).toContain('total_tokens')
+    expect(convoyColNames).toContain('total_cost_usd')
+
+    expect(version.user_version).toBe(3)
+  })
+
+  it('schema migration v1 to v3 chains correctly in a single init', () => {
+    // Create a v1 database (task table without adapter or cost columns)
+    const v1DbPath = join(tmpDir, 'v1-chain.db')
+    const rawDb = new DatabaseSync(v1DbPath)
+    rawDb.exec(`
+      CREATE TABLE convoy (
+        id          TEXT PRIMARY KEY,
+        name        TEXT NOT NULL,
+        spec_hash   TEXT NOT NULL,
+        status      TEXT NOT NULL DEFAULT 'pending',
+        branch      TEXT,
+        created_at  TEXT NOT NULL,
+        started_at  TEXT,
+        finished_at TEXT,
+        spec_yaml   TEXT NOT NULL
+      );
+      CREATE TABLE task (
+        id          TEXT PRIMARY KEY,
+        convoy_id   TEXT NOT NULL REFERENCES convoy(id),
+        phase       INTEGER NOT NULL,
+        prompt      TEXT NOT NULL,
+        agent       TEXT NOT NULL DEFAULT 'developer',
+        model       TEXT,
+        timeout_ms  INTEGER NOT NULL DEFAULT 1800000,
+        status      TEXT NOT NULL DEFAULT 'pending',
+        worker_id   TEXT,
+        worktree    TEXT,
+        output      TEXT,
+        exit_code   INTEGER,
+        started_at  TEXT,
+        finished_at TEXT,
+        retries     INTEGER NOT NULL DEFAULT 0,
+        max_retries INTEGER NOT NULL DEFAULT 1,
+        files       TEXT,
+        depends_on  TEXT
+      );
+      CREATE TABLE worker (
+        id             TEXT PRIMARY KEY,
+        task_id        TEXT REFERENCES task(id),
+        adapter        TEXT NOT NULL,
+        pid            INTEGER,
+        session_id     TEXT,
+        status         TEXT NOT NULL DEFAULT 'spawned',
+        worktree       TEXT,
+        created_at     TEXT NOT NULL,
+        finished_at    TEXT,
+        last_heartbeat TEXT
+      );
+      CREATE TABLE event (
+        id         INTEGER PRIMARY KEY AUTOINCREMENT,
+        convoy_id  TEXT REFERENCES convoy(id),
+        task_id    TEXT,
+        worker_id  TEXT,
+        type       TEXT NOT NULL,
+        data       TEXT,
+        created_at TEXT NOT NULL
+      );
+    `)
+    rawDb.exec('PRAGMA user_version = 1')
+    rawDb.close()
+
+    // Open with createConvoyStore — should chain v1→v2→v3 in one init
+    const v1Store = createConvoyStore(v1DbPath)
+    v1Store.close()
+
+    // Verify all columns from both migrations are present
+    const verifyDb = new DatabaseSync(v1DbPath)
+    const taskCols = verifyDb.prepare('PRAGMA table_info(task)').all() as Array<{ name: string }>
+    const convoyCols = verifyDb.prepare('PRAGMA table_info(convoy)').all() as Array<{ name: string }>
+    const version = verifyDb.prepare('PRAGMA user_version').get() as { user_version: number }
+    verifyDb.close()
+
+    const taskColNames = taskCols.map(c => c.name)
+    expect(taskColNames).toContain('adapter')
+    expect(taskColNames).toContain('prompt_tokens')
+    expect(taskColNames).toContain('completion_tokens')
+    expect(taskColNames).toContain('total_tokens')
+    expect(taskColNames).toContain('cost_usd')
+
+    const convoyColNames = convoyCols.map(c => c.name)
+    expect(convoyColNames).toContain('total_tokens')
+    expect(convoyColNames).toContain('total_cost_usd')
+
+    expect(version.user_version).toBe(3)
   })
 })
 
@@ -238,6 +411,25 @@ describe('convoy CRUD', () => {
     expect(retrieved.status).toBe('done')
     expect(retrieved.finished_at).toBe(ts)
   })
+
+  it('cost fields are null by default on a new convoy', () => {
+    store.insertConvoy(makeConvoy())
+    const retrieved = store.getConvoy('convoy-1')!
+    expect(retrieved.total_tokens).toBeNull()
+    expect(retrieved.total_cost_usd).toBeNull()
+  })
+
+  it('updateConvoyStatus persists total_tokens and total_cost_usd', () => {
+    store.insertConvoy(makeConvoy())
+    store.updateConvoyStatus('convoy-1', 'done', {
+      finished_at: '2026-01-01T01:00:00.000Z',
+      total_tokens: 5000,
+      total_cost_usd: '0.015000',
+    })
+    const retrieved = store.getConvoy('convoy-1')!
+    expect(retrieved.total_tokens).toBe(5000)
+    expect(retrieved.total_cost_usd).toBe('0.015000')
+  })
 })
 
 // ── task CRUD ─────────────────────────────────────────────────────────────────
@@ -311,6 +503,30 @@ describe('task CRUD', () => {
     expect(task.finished_at).toBe(ts)
     expect(task.retries).toBe(1)
   })
+
+  it('cost fields are null by default on a new task', () => {
+    store.insertTask(makeTask())
+    const task = store.getTask('task-1', 'convoy-1')!
+    expect(task.prompt_tokens).toBeNull()
+    expect(task.completion_tokens).toBeNull()
+    expect(task.total_tokens).toBeNull()
+    expect(task.cost_usd).toBeNull()
+  })
+
+  it('updateTaskStatus persists cost fields', () => {
+    store.insertTask(makeTask())
+    store.updateTaskStatus('task-1', 'convoy-1', 'done', {
+      prompt_tokens: 1200,
+      completion_tokens: 800,
+      total_tokens: 2000,
+      cost_usd: '0.006000',
+    })
+    const task = store.getTask('task-1', 'convoy-1')!
+    expect(task.prompt_tokens).toBe(1200)
+    expect(task.completion_tokens).toBe(800)
+    expect(task.total_tokens).toBe(2000)
+    expect(task.cost_usd).toBe('0.006000')
+  })
 })
 
 // ── getReadyTasks ─────────────────────────────────────────────────────────────

package/src/cli/convoy/store.ts

@@ -9,21 +9,21 @@ import type {
   EventRecord,
 } from './types.js'
 
-const SCHEMA_VERSION = 2
+const SCHEMA_VERSION = 3
 
 export interface ConvoyStore {
-  insertConvoy(record: Omit<ConvoyRecord, 'started_at' | 'finished_at'>): void
+  insertConvoy(record: Omit<ConvoyRecord, 'started_at' | 'finished_at' | 'total_tokens' | 'total_cost_usd'>): void
   getConvoy(id: string): ConvoyRecord | undefined
   getLatestConvoy(): ConvoyRecord | undefined
   updateConvoyStatus(
     id: string,
     status: ConvoyStatus,
-    extra?: { started_at?: string; finished_at?: string },
+    extra?: { started_at?: string; finished_at?: string; total_tokens?: number | null; total_cost_usd?: string | null },
   ): void
   insertTask(
     record: Omit<
       TaskRecord,
-      'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at'
+      'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'prompt_tokens' | 'completion_tokens' | 'total_tokens' | 'cost_usd'
     >,
   ): void
   getTask(id: string, convoyId: string): TaskRecord | undefined
@@ -33,7 +33,7 @@ export interface ConvoyStore {
     convoyId: string,
     status: ConvoyTaskStatus,
     extra?: Partial<
-      Pick<TaskRecord, 'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'retries'>
+      Pick<TaskRecord, 'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'retries' | 'prompt_tokens' | 'completion_tokens' | 'total_tokens' | 'cost_usd'>
     >,
   ): void
   getReadyTasks(convoyId: string): TaskRecord[]
@@ -61,8 +61,8 @@ class ConvoyStoreImpl implements ConvoyStore {
   }
 
   private initSchema(): void {
-    const row = this.db.prepare('PRAGMA user_version').get() as { user_version: number }
-    if (row.user_version === 0) {
+    let version = (this.db.prepare('PRAGMA user_version').get() as { user_version: number }).user_version
+    if (version === 0) {
       this.db.exec(`
         CREATE TABLE IF NOT EXISTS convoy (
           id          TEXT PRIMARY KEY,
@@ -72,8 +72,10 @@ class ConvoyStoreImpl implements ConvoyStore {
           branch      TEXT,
           created_at  TEXT NOT NULL,
           started_at  TEXT,
-          finished_at TEXT,
-          spec_yaml   TEXT NOT NULL
+          finished_at    TEXT,
+          spec_yaml      TEXT NOT NULL,
+          total_tokens   INTEGER,
+          total_cost_usd TEXT
         );
 
         CREATE TABLE IF NOT EXISTS task (
@@ -92,10 +94,14 @@ class ConvoyStoreImpl implements ConvoyStore {
           exit_code   INTEGER,
           started_at  TEXT,
           finished_at TEXT,
-          retries     INTEGER NOT NULL DEFAULT 0,
-          max_retries INTEGER NOT NULL DEFAULT 1,
-          files       TEXT,
-          depends_on  TEXT
+          retries           INTEGER NOT NULL DEFAULT 0,
+          max_retries       INTEGER NOT NULL DEFAULT 1,
+          files             TEXT,
+          depends_on        TEXT,
+          prompt_tokens     INTEGER,
+          completion_tokens INTEGER,
+          total_tokens      INTEGER,
+          cost_usd          TEXT
         );
 
         CREATE TABLE IF NOT EXISTS worker (
@@ -122,14 +128,26 @@ class ConvoyStoreImpl implements ConvoyStore {
         );
       `)
       this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+      version = SCHEMA_VERSION
     }
-    if (row.user_version === 1) {
+    if (version === 1) {
       this.db.exec('ALTER TABLE task ADD COLUMN adapter TEXT')
       this.db.exec('PRAGMA user_version = 2')
+      version = 2
+    }
+    if (version === 2) {
+      this.db.exec('ALTER TABLE task ADD COLUMN prompt_tokens INTEGER')
+      this.db.exec('ALTER TABLE task ADD COLUMN completion_tokens INTEGER')
+      this.db.exec('ALTER TABLE task ADD COLUMN total_tokens INTEGER')
+      this.db.exec('ALTER TABLE task ADD COLUMN cost_usd TEXT')
+      this.db.exec('ALTER TABLE convoy ADD COLUMN total_tokens INTEGER')
+      this.db.exec('ALTER TABLE convoy ADD COLUMN total_cost_usd TEXT')
+      this.db.exec('PRAGMA user_version = 3')
+      version = 3
     }
   }
 
-  insertConvoy(record: Omit<ConvoyRecord, 'started_at' | 'finished_at'>): void {
+  insertConvoy(record: Omit<ConvoyRecord, 'started_at' | 'finished_at' | 'total_tokens' | 'total_cost_usd'>): void {
     this.db
       .prepare(
         `INSERT INTO convoy (id, name, spec_hash, status, branch, created_at, started_at, finished_at, spec_yaml)
@@ -153,10 +171,10 @@ class ConvoyStoreImpl implements ConvoyStore {
   updateConvoyStatus(
     id: string,
     status: ConvoyStatus,
-    extra?: { started_at?: string; finished_at?: string },
+    extra?: { started_at?: string; finished_at?: string; total_tokens?: number | null; total_cost_usd?: string | null },
   ): void {
     const sets = ['status = :status']
-    const params: Record<string, string | null> = { id, status }
+    const params: Record<string, string | number | null> = { id, status }
 
     if (extra?.started_at !== undefined) {
       sets.push('started_at = :started_at')
@@ -166,6 +184,14 @@ class ConvoyStoreImpl implements ConvoyStore {
       sets.push('finished_at = :finished_at')
       params.finished_at = extra.finished_at
     }
+    if (extra?.total_tokens !== undefined) {
+      sets.push('total_tokens = :total_tokens')
+      params.total_tokens = extra.total_tokens
+    }
+    if (extra?.total_cost_usd !== undefined) {
+      sets.push('total_cost_usd = :total_cost_usd')
+      params.total_cost_usd = extra.total_cost_usd
+    }
 
     this.db.prepare(`UPDATE convoy SET ${sets.join(', ')} WHERE id = :id`).run(params)
   }
@@ -173,7 +199,7 @@ class ConvoyStoreImpl implements ConvoyStore {
   insertTask(
     record: Omit<
       TaskRecord,
-      'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at'
+      'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'prompt_tokens' | 'completion_tokens' | 'total_tokens' | 'cost_usd'
     >,
   ): void {
     this.db
@@ -207,12 +233,12 @@ class ConvoyStoreImpl implements ConvoyStore {
     convoyId: string,
     status: ConvoyTaskStatus,
     extra?: Partial<
-      Pick<TaskRecord, 'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'retries'>
+      Pick<TaskRecord, 'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'retries' | 'prompt_tokens' | 'completion_tokens' | 'total_tokens' | 'cost_usd'>
     >,
   ): void {
     const sets = ['status = :status']
     const params: Record<string, string | number | null> = { id, convoy_id: convoyId, status }
-    const extraFields = ['worker_id', 'worktree', 'output', 'exit_code', 'started_at', 'finished_at', 'retries'] as const
+    const extraFields = ['worker_id', 'worktree', 'output', 'exit_code', 'started_at', 'finished_at', 'retries', 'prompt_tokens', 'completion_tokens', 'total_tokens', 'cost_usd'] as const
 
     if (extra) {
       for (const field of extraFields) {

package/src/cli/convoy/types.ts

@@ -21,6 +21,8 @@ export interface ConvoyRecord {
   started_at: string | null
   finished_at: string | null
   spec_yaml: string
+  total_tokens: number | null
+  total_cost_usd: string | null
 }
 
 export interface TaskRecord {
@@ -43,6 +45,10 @@ export interface TaskRecord {
   max_retries: number
   files: string | null
   depends_on: string | null
+  prompt_tokens: number | null
+  completion_tokens: number | null
+  total_tokens: number | null
+  cost_usd: string | null
 }
 
 export interface WorkerRecord {

package/src/cli/run/adapters/claude-code.ts

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process'
-import type { Task, ExecuteOptions, ExecuteResult } from '../../types.js'
+import type { Task, ExecuteOptions, ExecuteResult, TokenUsage } from '../../types.js'
 
 /** Adapter name */
 export const name = 'claude-code'
@@ -60,10 +60,22 @@ export async function execute(task: Task, options: ExecuteOptions = {}): Promise
 
     proc.on('close', (code) => {
       const output = [stdout, stderr].filter(Boolean).join('\n')
+      let usage: TokenUsage | undefined
+      try {
+        const parsed = JSON.parse(stdout) as Record<string, unknown>
+        const u = parsed?.usage as Record<string, number> | undefined
+        if (u) {
+          const promptTokens = (u.input_tokens ?? u.prompt_tokens) as number | undefined
+          const completionTokens = (u.output_tokens ?? u.completion_tokens) as number | undefined
+          const total = ((promptTokens ?? 0) + (completionTokens ?? 0)) || undefined
+          usage = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: total }
+        }
+      } catch { /* not JSON or no usage — graceful degradation */ }
       resolve({
         success: code === 0,
         output: output.slice(0, 10000), // Cap output size
         exitCode: code ?? -1,
+        usage,
       })
     })
 

package/src/cli/run/adapters/copilot.ts

@@ -100,11 +100,19 @@ export async function execute(task: Task, options: ExecuteOptions = {}): Promise
     const timeoutMs = parseTimeout(task.timeout)
     const response = await session.sendAndWait({ prompt }, timeoutMs)
     const output = response?.data?.content ?? ''
+    const rawUsage = (response?.data as Record<string, unknown> | undefined)?.usage ?? (response as Record<string, unknown> | undefined)?.usage
+    const u = rawUsage as Record<string, number> | undefined
+    const usageResult = u ? {
+      prompt_tokens: u.prompt_tokens ?? u.promptTokens,
+      completion_tokens: u.completion_tokens ?? u.completionTokens,
+      total_tokens: u.total_tokens ?? u.totalTokens,
+    } : undefined
 
     return {
       success: true,
       output: output.slice(0, 10_000),
       exitCode: 0,
+      usage: usageResult,
     }
   } catch (err: unknown) {
     return {

package/src/cli/run/adapters/cursor.ts

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process'
-import type { Task, ExecuteOptions, ExecuteResult } from '../../types.js'
+import type { Task, ExecuteOptions, ExecuteResult, TokenUsage } from '../../types.js'
 
 /** Adapter name */
 export const name = 'cursor'
@@ -59,10 +59,22 @@ export async function execute(task: Task, options: ExecuteOptions = {}): Promise
 
     proc.on('close', (code) => {
       const output = [stdout, stderr].filter(Boolean).join('\n')
+      let usage: TokenUsage | undefined
+      try {
+        const parsed = JSON.parse(stdout) as Record<string, unknown>
+        const u = parsed?.usage as Record<string, number> | undefined
+        if (u) {
+          const promptTokens = (u.input_tokens ?? u.prompt_tokens) as number | undefined
+          const completionTokens = (u.output_tokens ?? u.completion_tokens) as number | undefined
+          const total = ((promptTokens ?? 0) + (completionTokens ?? 0)) || undefined
+          usage = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: total }
+        }
+      } catch { /* not JSON or no usage — graceful degradation */ }
       resolve({
         success: code === 0,
         output: output.slice(0, 10000), // Cap output size
         exitCode: code ?? -1,
+        usage,
       })
     })
 

package/src/cli/run/adapters/opencode.ts

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process'
-import type { Task, ExecuteOptions, ExecuteResult } from '../../types.js'
+import type { Task, ExecuteOptions, ExecuteResult, TokenUsage } from '../../types.js'
 
 /** Adapter name */
 export const name = 'opencode'
@@ -53,10 +53,22 @@ export async function execute(task: Task, options: ExecuteOptions = {}): Promise
 
     proc.on('close', (code) => {
       const output = [stdout, stderr].filter(Boolean).join('\n')
+      let usage: TokenUsage | undefined
+      try {
+        const parsed = JSON.parse(stdout) as Record<string, unknown>
+        const u = parsed?.usage as Record<string, number> | undefined
+        if (u) {
+          const promptTokens = (u.input_tokens ?? u.prompt_tokens) as number | undefined
+          const completionTokens = (u.output_tokens ?? u.completion_tokens) as number | undefined
+          const total = ((promptTokens ?? 0) + (completionTokens ?? 0)) || undefined
+          usage = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: total }
+        }
+      } catch { /* not JSON or no usage — graceful degradation */ }
       resolve({
         success: code === 0,
         output: output.slice(0, 10000), // Cap output size
         exitCode: code ?? -1,
+        usage,
       })
     })
 

package/src/cli/run.ts

@@ -8,6 +8,12 @@ import { createReporter, printExecutionPlan } from './run/reporter.js'
 import type { CliContext, RunOptions } from './types.js'
 import type { ConvoyResult } from './convoy/engine.js'
 
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + 'M'
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + 'K'
+  return String(n)
+}
+
 const HELP = `
   opencastle run [options]
 
@@ -153,6 +159,9 @@ function printConvoyResult(result: ConvoyResult): void {
       console.log(`    ${g.passed ? '✓' : '✗'} ${g.command}`)
     }
   }
+  if (result.cost) {
+    console.log(`  Tokens: ${formatTokens(result.cost.total_tokens)}`)
+  }
 }
 
 /**
@@ -199,6 +208,20 @@ export default async function run({ args, pkgRoot }: CliContext): Promise<void>
         console.log(`    ${status}: ${count}`)
       }
       console.log(`    total: ${tasks.length}`)
+      const totalTokens = tasks.reduce((sum, t) => sum + (t.total_tokens ?? 0), 0)
+      if (tasks.some(t => t.total_tokens != null)) {
+        console.log(`\n  Tokens: ${formatTokens(totalTokens)}`)
+        const tasksWithTokens = tasks.filter(t => t.total_tokens != null)
+        if (tasksWithTokens.length > 0) {
+          console.log(`\n  Token usage by task:`)
+          for (const t of tasksWithTokens) {
+            const parts = [formatTokens(t.total_tokens!)]
+            if (t.prompt_tokens != null) parts.push(`in: ${formatTokens(t.prompt_tokens)}`)
+            if (t.completion_tokens != null) parts.push(`out: ${formatTokens(t.completion_tokens)}`)
+            console.log(`    ${t.id}: ${parts.join(' | ')}`)
+          }
+        }
+      }
     } finally {
       store.close()
     }

package/src/cli/types.ts

@@ -238,6 +238,13 @@ export interface ExecuteOptions {
   cwd?: string;
 }
 
+/** Token usage data from adapter execution. */
+export interface TokenUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+}
+
 /** Result from an agent adapter execution. */
 export interface ExecuteResult {
   success: boolean;
@@ -245,6 +252,8 @@ export interface ExecuteResult {
   exitCode: number;
   _timedOut?: boolean;
   taskId?: string;
+  /** Token usage data if available from the adapter. */
+  usage?: TokenUsage;
 }
 
 /** Reporter interface for the run command. */

package/src/dashboard/dist/index.html

@@ -66,6 +66,12 @@ Export
     return div.innerHTML;
   }
 
+  function formatTokens(n) {
+    if (n >= 1000000) return (n / 1000000).toFixed(1) + 'M';
+    if (n >= 1000) return (n / 1000).toFixed(1) + 'K';
+    return String(n);
+  }
+
   // ── SVG Icon Library (empty states) ────────────────────
 
   const EMPTY_ICONS = {
@@ -1133,6 +1139,9 @@ Export
     html += '<div class="convoy-stat"><span class="convoy-stat__label">Tasks</span><span class="convoy-stat__value">' + done + '/' + total + '</span></div>';
     html += '<div class="convoy-stat"><span class="convoy-stat__label">Events</span><span class="convoy-stat__value">' + (convoy.events_count || 0) + '</span></div>';
     html += '<div class="convoy-stat"><span class="convoy-stat__label">Started</span><span class="convoy-stat__value">' + (convoy.started_at ? formatTime(convoy.started_at) : '\u2014') + '</span></div>';
+    if (convoy.total_tokens != null) {
+      html += '<div class="convoy-stat"><span class="convoy-stat__label">Tokens</span><span class="convoy-stat__value">' + formatTokens(convoy.total_tokens) + '</span></div>';
+    }
     html += '</div>';
 
     html += '<div class="convoy-progress">';
@@ -1142,7 +1151,7 @@ Export
 
     if (convoy.tasks && convoy.tasks.length > 0) {
       html += '<table class="sessions-table convoy-tasks">';
-      html += '<thead><tr><th>Task</th><th>Phase</th><th>Agent</th><th>Adapter</th><th>Status</th><th>Retries</th></tr></thead>';
+      html += '<thead><tr><th>Task</th><th>Phase</th><th>Agent</th><th>Adapter</th><th>Status</th><th>Retries</th><th>Tokens</th></tr></thead>';
       html += '<tbody>';
       convoy.tasks.forEach(function(t) {
         const tStatus = t.status === 'done' ? 'success'
@@ -1155,6 +1164,7 @@ Export
         html += '<td>' + escapeHtml(t.adapter || '\u2014') + '</td>';
         html += '<td><span class="outcome-badge outcome-badge--' + tStatus + '">' + escapeHtml(t.status) + '</span></td>';
         html += '<td class="td-num">' + (t.retries || 0) + '</td>';
+        html += '<td class="td-num">' + (t.total_tokens != null ? formatTokens(t.total_tokens) : '\u2014') + '</td>';
         html += '</tr>';
       });
       html += '</tbody></table>';