opencastle 0.21.0 → 0.22.0

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

@@ -1472,3 +1472,180 @@ describe('diamond dependency skip', () => {
     expect(byId['task-c']).toBe('skipped')
   })
 })
+
+// ── 21. Cost tracking (usage propagation) ────────────────────────────────────
+
+describe('cost tracking', () => {
+  it('persists usage data to task record when adapter returns usage', async () => {
+    const adapter = makeAdapter()
+    adapter.execute.mockResolvedValue({
+      success: true,
+      output: 'ok',
+      exitCode: 0,
+      usage: { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 },
+    } satisfies ExecuteResult)
+
+    const engine = createConvoyEngine({
+      spec: makeSpec(),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+    expect(result.status).toBe('done')
+
+    const store = createConvoyStore(dbPath)
+    const tasks = store.getTasksByConvoy(result.convoyId)
+    store.close()
+    expect(tasks[0].prompt_tokens).toBe(100)
+    expect(tasks[0].completion_tokens).toBe(50)
+    expect(tasks[0].total_tokens).toBe(150)
+  })
+
+  it('leaves cost fields null when adapter returns no usage', async () => {
+    const adapter = makeAdapter()
+    // default makeAdapter returns no usage field
+
+    const engine = createConvoyEngine({
+      spec: makeSpec(),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+
+    const store = createConvoyStore(dbPath)
+    const tasks = store.getTasksByConvoy(result.convoyId)
+    store.close()
+    expect(tasks[0].prompt_tokens).toBeNull()
+    expect(tasks[0].completion_tokens).toBeNull()
+    expect(tasks[0].total_tokens).toBeNull()
+  })
+
+  it('aggregates total_tokens from multiple tasks to convoy record', async () => {
+    const adapter = makeAdapter()
+    adapter.execute
+      .mockResolvedValueOnce({ success: true, output: 'ok', exitCode: 0, usage: { total_tokens: 100 } })
+      .mockResolvedValueOnce({ success: true, output: 'ok', exitCode: 0, usage: { total_tokens: 200 } })
+
+    const spec = makeSpec({ concurrency: 2 }, [
+      { id: 'task-1', depends_on: [] },
+      { id: 'task-2', depends_on: [] },
+    ])
+    const engine = createConvoyEngine({
+      spec,
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+
+    const store = createConvoyStore(dbPath)
+    const convoy = store.getConvoy(result.convoyId)
+    store.close()
+    expect(convoy!.total_tokens).toBe(300)
+  })
+
+  it('includes cost in ConvoyResult when usage is available', async () => {
+    const adapter = makeAdapter()
+    adapter.execute.mockResolvedValue({
+      success: true,
+      output: 'ok',
+      exitCode: 0,
+      usage: { total_tokens: 75 },
+    } satisfies ExecuteResult)
+
+    const engine = createConvoyEngine({
+      spec: makeSpec(),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+
+    expect(result.cost).toEqual({ total_tokens: 75 })
+  })
+
+  it('omits cost from ConvoyResult when no usage data is available', async () => {
+    const adapter = makeAdapter()
+    // default makeAdapter returns no usage
+
+    const engine = createConvoyEngine({
+      spec: makeSpec(),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+
+    expect(result.cost).toBeUndefined()
+  })
+
+  it('partial usage fields are persisted correctly (only total_tokens set)', async () => {
+    const adapter = makeAdapter()
+    adapter.execute.mockResolvedValue({
+      success: true,
+      output: 'ok',
+      exitCode: 0,
+      usage: { total_tokens: 42 },
+    } satisfies ExecuteResult)
+
+    const engine = createConvoyEngine({
+      spec: makeSpec(),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+
+    const store = createConvoyStore(dbPath)
+    const tasks = store.getTasksByConvoy(result.convoyId)
+    store.close()
+    expect(tasks[0].total_tokens).toBe(42)
+    expect(tasks[0].prompt_tokens).toBeNull()
+    expect(tasks[0].completion_tokens).toBeNull()
+  })
+
+  it('convoy total_tokens is null when no task has usage', async () => {
+    const adapter = makeAdapter()
+    // default adapter returns no usage
+
+    const engine = createConvoyEngine({
+      spec: makeSpec({ concurrency: 2 }, [
+        { id: 'task-1', depends_on: [] },
+        { id: 'task-2', depends_on: [] },
+      ]),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+
+    const result = await engine.run()
+
+    const store = createConvoyStore(dbPath)
+    const convoy = store.getConvoy(result.convoyId)
+    store.close()
+    expect(convoy!.total_tokens).toBeNull()
+    expect(result.cost).toBeUndefined()
+  })
+})

package/src/cli/convoy/engine.ts

@@ -37,6 +37,7 @@ export interface ConvoyResult {
   summary: { total: number; done: number; failed: number; skipped: number; timedOut: number }
   duration: string
   gateResults?: Array<{ command: string; exitCode: number; passed: boolean }>
+  cost?: { total_tokens: number }
 }
 
 export interface ConvoyEngine {
@@ -290,11 +291,19 @@ async function runConvoy(
         await removeWorktree()
       }
 
+      const usageExtra: Partial<{ prompt_tokens: number; completion_tokens: number; total_tokens: number }> = {}
+      if (result.usage) {
+        if (result.usage.prompt_tokens != null) usageExtra.prompt_tokens = result.usage.prompt_tokens
+        if (result.usage.completion_tokens != null) usageExtra.completion_tokens = result.usage.completion_tokens
+        if (result.usage.total_tokens != null) usageExtra.total_tokens = result.usage.total_tokens
+      }
+
       store.withTransaction(() => {
         store.updateTaskStatus(taskRecord.id, convoyId, 'done', {
           finished_at: finishedAt,
           output: result.output,
           exit_code: result.exitCode,
+          ...usageExtra,
         })
         store.updateWorkerStatus(workerId, 'done', { finished_at: finishedAt })
       })
@@ -398,7 +407,18 @@ async function runConvoy(
       ? 'failed'
       : 'done'
 
-  store.updateConvoyStatus(convoyId, finalStatus, { finished_at: new Date().toISOString() })
+  // Aggregate token usage across completed tasks
+  let convoyTotalTokens: number | null = null
+  for (const t of allTasksFinal) {
+    if (t.total_tokens != null) {
+      convoyTotalTokens = (convoyTotalTokens ?? 0) + t.total_tokens
+    }
+  }
+
+  store.updateConvoyStatus(convoyId, finalStatus, {
+    finished_at: new Date().toISOString(),
+    total_tokens: convoyTotalTokens,
+  })
 
   return {
     convoyId,
@@ -406,6 +426,7 @@ async function runConvoy(
     summary,
     duration: formatDuration(Date.now() - startTime),
     gateResults: spec.gates && spec.gates.length > 0 ? gateResults : undefined,
+    cost: convoyTotalTokens != null ? { total_tokens: convoyTotalTokens } : undefined,
   }
 }
 

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

@@ -187,4 +187,41 @@ describe('exportConvoyToNdjson', () => {
       process.chdir(originalCwd)
     }
   })
+
+  it('includes cost fields (prompt_tokens, completion_tokens, total_tokens) per task when present', async () => {
+    insertConvoy('c1')
+    insertTask('t1', 'c1')
+    // Manually set token cost on the task record
+    store.updateTaskStatus('t1', 'c1', 'done', {
+      prompt_tokens: 200,
+      completion_tokens: 100,
+      total_tokens: 300,
+    })
+    // Set convoy-level totals
+    store.updateConvoyStatus('c1', 'done', { total_tokens: 300 })
+    const logsDir = join(tmpDir, 'logs')
+
+    await exportConvoyToNdjson(store, 'c1', logsDir)
+
+    const record = JSON.parse(readFileSync(join(logsDir, 'convoys.ndjson'), 'utf8').trim())
+    expect(record.tasks[0].prompt_tokens).toBe(200)
+    expect(record.tasks[0].completion_tokens).toBe(100)
+    expect(record.tasks[0].total_tokens).toBe(300)
+    expect(record.total_tokens).toBe(300)
+  })
+
+  it('cost fields are null when no usage data recorded', async () => {
+    insertConvoy('c1')
+    insertTask('t1', 'c1')
+    const logsDir = join(tmpDir, 'logs')
+
+    await exportConvoyToNdjson(store, 'c1', logsDir)
+
+    const record = JSON.parse(readFileSync(join(logsDir, 'convoys.ndjson'), 'utf8').trim())
+    expect(record.tasks[0].prompt_tokens).toBeNull()
+    expect(record.tasks[0].completion_tokens).toBeNull()
+    expect(record.tasks[0].total_tokens).toBeNull()
+    expect(record.total_tokens).toBeNull()
+    expect(record.total_cost_usd).toBeNull()
+  })
 })

package/src/cli/convoy/export.ts

@@ -39,8 +39,13 @@ export async function exportConvoyToNdjson(
         started_at: t.started_at,
         finished_at: t.finished_at,
         retries: t.retries,
+        prompt_tokens: t.prompt_tokens,
+        completion_tokens: t.completion_tokens,
+        total_tokens: t.total_tokens,
       })),
       events_count: eventsCount,
+      total_tokens: convoy.total_tokens,
+      total_cost_usd: convoy.total_cost_usd,
     }
 
     const dir = logsDir ?? resolve(process.cwd(), '.opencastle', 'logs')

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 ─────────────────────────────────────────────────────────────