@techdivision/opencode-time-tracking 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.8.0] - 2025-03-01
+
+### Added
+
+- Add detailed token columns to CSV: `tokens_input`, `tokens_output`, `tokens_reasoning`, `tokens_cache_read`, `tokens_cache_write`
+- Add `cost` column to CSV tracking session cost in USD (from OpenCode SDK)
+- Add `CsvWriter.ensureHeader()` for automatic CSV header management at plugin startup
+
+### Fixed
+
+- Fix CSV header migration: automatically upgrade old 17-column files to 23-column format
+- Fix ticket extraction: skip synthetic text parts (file contents, MCP resources) to avoid false positives from example patterns in docs
+- Fix empty CSV files created without headers
+
+### Changed
+
+- CSV header is now validated and repaired at plugin startup, not on each write
+
+## [0.7.1] - 2025-03-01
+
+### Fixed
+
+- Fix `agent_defaults` lookup to be tolerant of `@` prefix in agent names
+- Add `AgentMatcher` utility for consistent agent name normalization across the codebase
+
 ## [0.7.0] - 2025-02-04
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techdivision/opencode-time-tracking",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Automatic time tracking plugin for OpenCode - tracks session duration and tool usage to CSV",
   "main": "src/Plugin.ts",
   "types": "src/Plugin.ts",

package/src/Plugin.ts

@@ -64,6 +64,9 @@ export const plugin: Plugin = async ({
   const ticketExtractor = new TicketExtractor(client, config.valid_projects)
   const ticketResolver = new TicketResolver(config, ticketExtractor)
 
+  // Ensure CSV file has a valid header at startup
+  await csvWriter.ensureHeader()
+
   const hooks: Hooks = {
     "tool.execute.after": createToolExecuteAfterHook(
       sessionManager,

package/src/hooks/EventHook.ts

@@ -12,6 +12,7 @@ import type { MessageWithParts } from "../types/MessageWithParts"
 import type { OpencodeClient } from "../types/OpencodeClient"
 import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
 
+import { AgentMatcher } from "../utils/AgentMatcher"
 import { DescriptionGenerator } from "../utils/DescriptionGenerator"
 
 /**
@@ -139,6 +140,11 @@ export function createEventHook(
           cacheRead: part.tokens.cache.read,
           cacheWrite: part.tokens.cache.write,
         })
+
+        // Track cost from step-finish events
+        if (part.cost !== undefined) {
+          sessionManager.addCost(part.sessionID, part.cost)
+        }
       }
 
       return
@@ -193,9 +199,11 @@ export function createEventHook(
       const agentString = session.agent?.name ?? null
 
       // Check if agent should be ignored (tolerant matching: with or without @ prefix)
-      const normalizedAgent = agentString?.replace(/^@/, "")
+      const normalizedAgent = agentString
+        ? AgentMatcher.normalize(agentString)
+        : null
       const isIgnoredAgent = config.ignored_agents?.some(
-        (ignored) => ignored.replace(/^@/, "") === normalizedAgent
+        (ignored) => AgentMatcher.normalize(ignored) === normalizedAgent
       )
 
       if (agentString && isIgnoredAgent) {
@@ -221,6 +229,7 @@ export function createEventHook(
           description,
           notes: `Auto-tracked: ${toolSummary}`,
           tokenUsage: session.tokenUsage,
+          cost: session.cost,
           model: modelString,
           agent: agentString,
         })

package/src/services/CsvWriter.ts

@@ -16,9 +16,51 @@ import "../types/Bun"
 /**
  * CSV header row for the worklog export file.
  * Compatible with Jira/Tempo time tracking import.
+ *
+ * @remarks
+ * Columns 1-17: Original format (v0.5.0 - v0.7.x)
+ * Columns 18-23: Extended format (v0.8.0+) with token details and cost
  */
 const CSV_HEADER =
-  "id,start_date,end_date,user,ticket_name,issue_key,account_key,start_time,end_time,duration_seconds,tokens_used,tokens_remaining,story_points,description,notes,model,agent"
+  "id,start_date,end_date,user,ticket_name,issue_key,account_key,start_time,end_time,duration_seconds,tokens_used,tokens_remaining,story_points,description,notes,model,agent,tokens_input,tokens_output,tokens_reasoning,tokens_cache_read,tokens_cache_write,cost"
+
+/** Number of columns in the current CSV format */
+const CSV_COLUMN_COUNT = 23
+
+/**
+ * Checks if a line is a CSV header row.
+ *
+ * @param line - The line to check
+ * @returns `true` if the line appears to be a header
+ */
+function isHeaderLine(line: string): boolean {
+  return line.startsWith('"id"') || line.startsWith("id,")
+}
+
+/**
+ * Pads a CSV line with empty fields to match the expected column count.
+ *
+ * @param line - The CSV line to pad
+ * @param currentColumns - The current number of columns in the line
+ * @param targetColumns - The target number of columns
+ * @returns The padded line, or the original line if no padding needed
+ */
+function padCsvLine(
+  line: string,
+  currentColumns: number,
+  targetColumns: number
+): string {
+  if (currentColumns >= targetColumns) {
+    return line
+  }
+
+  const missingColumns = targetColumns - currentColumns
+  const padding = ',""\n'.repeat(missingColumns).slice(0, -1) // Remove trailing newline, keep commas
+  const emptyFields = Array(missingColumns).fill('""').join(",")
+
+  // Append empty fields to the line
+  return line + "," + emptyFields
+}
 
 /**
  * Writes time tracking entries to a CSV file.
@@ -68,15 +110,95 @@ export class CsvWriter {
     return csvPath
   }
 
+  /**
+   * Ensures the CSV file exists and has a valid, up-to-date header.
+   *
+   * @remarks
+   * Call this once at plugin startup. Handles these cases:
+   * - File doesn't exist: creates it with header
+   * - File is empty: writes header
+   * - File has data but no header: prepends header and pads rows if needed
+   * - File has outdated header (fewer columns): replaces header and pads all rows
+   * - File already has current header: no action needed
+   *
+   * @returns `true` if file was modified, `false` if already valid
+   */
+  async ensureHeader(): Promise<boolean> {
+    const csvPath = this.resolvePath()
+
+    try {
+      await mkdir(dirname(csvPath), { recursive: true })
+    } catch {
+      // Directory may already exist
+    }
+
+    const file = Bun.file(csvPath)
+    const exists = await file.exists()
+
+    if (!exists) {
+      // Create new file with header
+      await Bun.write(csvPath, CSV_HEADER + "\n")
+      return true
+    }
+
+    const content = await file.text()
+    const trimmedContent = content.trim()
+
+    if (trimmedContent.length === 0) {
+      // Empty file: write header
+      await Bun.write(csvPath, CSV_HEADER + "\n")
+      return true
+    }
+
+    const lines = trimmedContent.split("\n")
+    const firstLine = lines[0]
+    const hasHeader = isHeaderLine(firstLine)
+
+    // Determine column count from first data line
+    const dataLineIndex = hasHeader ? 1 : 0
+    if (dataLineIndex >= lines.length) {
+      // Only header, no data - ensure header is current
+      if (hasHeader && CsvFormatter.countColumns(firstLine) < CSV_COLUMN_COUNT) {
+        await Bun.write(csvPath, CSV_HEADER + "\n")
+        return true
+      }
+      return false
+    }
+
+    const firstDataLine = lines[dataLineIndex]
+    const columnCount = CsvFormatter.countColumns(firstDataLine)
+
+    // Check if migration is needed
+    if (columnCount >= CSV_COLUMN_COUNT) {
+      // Already has enough columns
+      if (!hasHeader) {
+        // Just prepend header
+        await Bun.write(csvPath, CSV_HEADER + "\n" + trimmedContent + "\n")
+        return true
+      }
+      return false
+    }
+
+    // Migration needed: pad all data rows to CSV_COLUMN_COUNT
+    const dataLines = hasHeader ? lines.slice(1) : lines
+    const paddedLines = dataLines.map((line) => {
+      const lineColumnCount = CsvFormatter.countColumns(line)
+      return padCsvLine(line, lineColumnCount, CSV_COLUMN_COUNT)
+    })
+
+    // Write new header + padded data
+    await Bun.write(csvPath, CSV_HEADER + "\n" + paddedLines.join("\n") + "\n")
+    return true
+  }
+
   /**
    * Writes a time tracking entry to the CSV file.
    *
    * @param data - The entry data to write
    *
    * @remarks
-   * Creates the CSV file with headers if it doesn't exist.
-   * Appends to existing file if it exists.
-   * Creates parent directories as needed.
+   * Assumes `ensureHeader()` was called at startup.
+   * Simply appends the new entry to the file.
    *
    * @example
    * ```typescript
@@ -87,19 +209,13 @@ export class CsvWriter {
    *   durationSeconds: 3600,
    *   description: "Implemented feature X",
    *   notes: "Auto-tracked: read(5x), edit(3x)",
-   *   tokenUsage: { input: 1000, output: 500, reasoning: 0, cacheRead: 0, cacheWrite: 0 }
+   *   tokenUsage: { input: 1000, output: 500, reasoning: 0, cacheRead: 0, cacheWrite: 0 },
+   *   cost: 0.0234
    * })
    * ```
    */
   async write(data: CsvEntryData): Promise<void> {
     const csvPath = this.resolvePath()
-
-    try {
-      await mkdir(dirname(csvPath), { recursive: true })
-    } catch {
-      // Directory may already exist
-    }
-
     const file = Bun.file(csvPath)
     const exists = await file.exists()
 
@@ -124,11 +240,19 @@ export class CsvWriter {
       CsvFormatter.escape(data.notes),
       data.model ?? "",
       data.agent ?? "",
+      // Extended columns (v0.8.0+)
+      data.tokenUsage.input.toString(),
+      data.tokenUsage.output.toString(),
+      data.tokenUsage.reasoning.toString(),
+      data.tokenUsage.cacheRead.toString(),
+      data.tokenUsage.cacheWrite.toString(),
+      data.cost.toFixed(6),
     ]
 
     const csvLine = fields.map((f) => `"${f}"`).join(",")
 
     if (!exists) {
+      // Fallback: create file with header if ensureHeader() wasn't called
       await Bun.write(csvPath, CSV_HEADER + "\n" + csvLine + "\n")
     } else {
       const content = await file.text()

package/src/services/SessionManager.ts

@@ -63,6 +63,7 @@ export class SessionManager {
         cacheRead: 0,
         cacheWrite: 0,
       },
+      cost: 0,
       model: null,
       agent: null,
     }
@@ -134,6 +135,20 @@ export class SessionManager {
     }
   }
 
+  /**
+   * Adds cost to a session's cumulative total.
+   *
+   * @param sessionID - The OpenCode session identifier
+   * @param cost - The cost in USD to add
+   */
+  addCost(sessionID: string, cost: number): void {
+    const session = this.sessions.get(sessionID)
+
+    if (session) {
+      session.cost += cost
+    }
+  }
+
   /**
    * Updates the ticket reference for a session.
    *

package/src/services/TicketExtractor.ts

@@ -116,7 +116,9 @@ export class TicketExtractor {
         }
 
         for (const part of message.parts) {
-          if (part.type === "text" && part.text) {
+          // Skip synthetic parts (file contents, MCP resources, etc.)
+          // These may contain example ticket patterns from docs
+          if (part.type === "text" && part.text && !part.synthetic) {
             const ticket = this.extractFromText(part.text)
 
             if (ticket) {

package/src/services/TicketResolver.ts

@@ -6,6 +6,8 @@ import type { ResolvedTicketInfo } from "../types/ResolvedTicketInfo"
 import type { TimeTrackingConfig } from "../types/TimeTrackingConfig"
 import type { TicketExtractor } from "./TicketExtractor"
 
+import { AgentMatcher } from "../utils/AgentMatcher"
+
 /**
  * Resolves tickets and account keys using fallback hierarchy.
  *
@@ -65,11 +67,13 @@ export class TicketResolver {
       }
     }
 
-    // 2. Try agent default
-    if (agentName && this.config.agent_defaults?.[agentName]) {
+    // 2. Try agent default (tolerant matching: with or without @ prefix)
+    const agentKey = agentName ? this.findAgentKey(agentName) : null
+
+    if (agentKey) {
       return {
-        ticket: this.config.agent_defaults[agentName].issue_key,
-        accountKey: this.resolveAccountKey(agentName),
+        ticket: this.config.agent_defaults![agentKey].issue_key,
+        accountKey: this.resolveAccountKey(agentKey),
       }
     }
 
@@ -88,16 +92,41 @@ export class TicketResolver {
     }
   }
 
+  /**
+   * Finds the matching config key for an agent name.
+   *
+   * @param agentName - The agent name from the SDK
+   * @returns The matching config key, or `null` if not found
+   *
+   * @remarks
+   * Normalizes both the agent name and config keys to ensure
+   * matching works regardless of @ prefix.
+   */
+  private findAgentKey(agentName: string): string | null {
+    const defaults = this.config.agent_defaults
+
+    if (!defaults) {
+      return null
+    }
+
+    const normalized = AgentMatcher.normalize(agentName)
+    const key = Object.keys(defaults).find(
+      (k) => AgentMatcher.normalize(k) === normalized
+    )
+
+    return key ?? null
+  }
+
   /**
    * Resolves account key using fallback hierarchy.
    *
-   * @param agentName - The agent name, or `null`
+   * @param agentKey - The agent config key, or `null`
    * @returns Resolved Tempo account key
    */
-  private resolveAccountKey(agentName: string | null): string {
+  private resolveAccountKey(agentKey: string | null): string {
     // 1. Agent-specific account_key
-    if (agentName && this.config.agent_defaults?.[agentName]?.account_key) {
-      return this.config.agent_defaults[agentName].account_key!
+    if (agentKey && this.config.agent_defaults?.[agentKey]?.account_key) {
+      return this.config.agent_defaults[agentKey].account_key!
     }
 
     // 2. Global default account_key (required)

package/src/types/CsvEntryData.ts

@@ -29,6 +29,9 @@ export interface CsvEntryData {
   /** Token consumption statistics */
   tokenUsage: TokenUsage
 
+  /** Total cost in USD */
+  cost: number
+
   /**
    * Model identifier in format `providerID/modelID`.
    *

package/src/types/MessagePart.ts

@@ -11,4 +11,14 @@ export interface MessagePart {
 
   /** Text content for text parts */
   text?: string
+
+  /**
+   * Whether this part was synthetically generated by OpenCode.
+   *
+   * @remarks
+   * OpenCode creates synthetic text parts for file contents, MCP resources,
+   * and other system-injected content. These should be excluded from
+   * ticket extraction as they may contain example patterns from docs.
+   */
+  synthetic?: boolean
 }

package/src/types/MessagePartUpdatedProperties.ts

@@ -16,6 +16,9 @@ export interface MessagePartUpdatedProperties {
     /** Session ID (present on step-finish and agent parts) */
     sessionID?: string
 
+    /** Cost in USD (present on step-finish parts) */
+    cost?: number
+
     /** Token usage (present on step-finish parts) */
     tokens?: StepFinishPart["tokens"]
 

package/src/types/SessionData.ts

@@ -23,6 +23,9 @@ export interface SessionData {
   /** Cumulative token usage for the session */
   tokenUsage: TokenUsage
 
+  /** Cumulative cost in USD for the session */
+  cost: number
+
   /** Model used in this session, or `null` if not detected */
   model: ModelInfo | null
 

package/src/types/StepFinishPart.ts

@@ -16,6 +16,9 @@ export interface StepFinishPart {
   /** The session this part belongs to */
   sessionID: string
 
+  /** Cost in USD for this step */
+  cost: number
+
   /** Token usage for this step */
   tokens: {
     /** Input tokens consumed */

package/src/utils/AgentMatcher.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Utility for normalizing agent names.
+ */
+
+/**
+ * Normalizes agent names to a canonical form.
+ *
+ * @remarks
+ * Agent names can appear with or without the "@" prefix
+ * depending on the source (SDK, config, user input).
+ * This class ensures consistent comparison by normalizing
+ * all agent names to the "@<name>" format.
+ */
+export class AgentMatcher {
+  /**
+   * Normalizes an agent name to canonical form (with @ prefix).
+   *
+   * @param agentName - The agent name to normalize
+   * @returns The normalized agent name with @ prefix
+   *
+   * @example
+   * ```typescript
+   * AgentMatcher.normalize("developer")      // → "@developer"
+   * AgentMatcher.normalize("@developer")     // → "@developer"
+   * AgentMatcher.normalize("@time-tracking") // → "@time-tracking"
+   * ```
+   */
+  static normalize(agentName: string): string {
+    return agentName.startsWith("@") ? agentName : `@${agentName}`
+  }
+}

package/src/utils/CsvFormatter.ts

@@ -54,4 +54,31 @@ export class CsvFormatter {
   static formatTime(timestamp: number): string {
     return new Date(timestamp).toTimeString().split(" ")[0]
   }
+
+  /**
+   * Counts the number of columns in a CSV line.
+   *
+   * @param csvLine - A single line from a CSV file (with quoted fields)
+   * @returns The number of columns
+   *
+   * @remarks
+   * Handles quoted fields correctly by counting occurrences of `","` pattern.
+   * Assumes all fields are double-quoted as our CSV writer produces.
+   *
+   * @example
+   * ```typescript
+   * CsvFormatter.countColumns('"a","b","c"')  // Returns: 3
+   * CsvFormatter.countColumns('"single"')     // Returns: 1
+   * ```
+   */
+  static countColumns(csvLine: string): number {
+    if (!csvLine || csvLine.trim().length === 0) {
+      return 0
+    }
+
+    // Count occurrences of "," which separates quoted fields
+    // Add 1 because n separators means n+1 fields
+    const matches = csvLine.match(/","/g)
+    return matches ? matches.length + 1 : 1
+  }
 }