@oar-sh/oar 0.9.16 → 0.9.18

package/server/migrations/0029-deepseek-balance-rises.mjs

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Migration: the DeepSeek balance reference notes when the balance last rose
+ * (services/plan-usage-service.mjs, the DeepSeek card's balance bar). Builds
+ * on 0025.
+ *
+ * `deepseek_balance_reference` gains these columns:
+ * - `rose_at`: when a read last found the balance above the read before it
+ *   (a top-up or a grant); NULL while no rise was seen. `reference_at` cannot
+ *   tell: it is also set by the first read of a currency. A starting balance
+ *   set on the DeepSeek tab counts until the balance rises after it was set
+ *   (plan-usage-deepseek.mjs).
+ * - `last_read_at`: when `last_total` was read; NULL for a row from before.
+ * - `rose_from_at`: when the balance before that rise was read; NULL when
+ *   unknown. A rise the relay first sees after the starting balance was set
+ *   may be a top-up from before it, unless the balance before the rise was
+ *   read after it too.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0029-deepseek-balance-rises.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+import { DEEPSEEK_BALANCE_REFERENCE_TABLE, migrateDeepSeekUsageRequestsDaily } from './0025-deepseek-usage-requests-daily.mjs';
+
+// Added to deepseek_balance_reference, with their DDL.
+export const DEEPSEEK_BALANCE_RISE_COLUMNS = Object.freeze([
+  ['rose_at', 'TEXT'],
+  ['last_read_at', 'TEXT'],
+  ['rose_from_at', 'TEXT'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the service from using the column: '' when nothing does. */
+export function deepseekBalanceRisesProblem(db) {
+  if (!tableExists(db, DEEPSEEK_BALANCE_REFERENCE_TABLE)) return `no ${DEEPSEEK_BALANCE_REFERENCE_TABLE} table`;
+  const present = columnNames(db, DEEPSEEK_BALANCE_REFERENCE_TABLE);
+  const missing = DEEPSEEK_BALANCE_RISE_COLUMNS.map(([name]) => name).filter((name) => !present.has(name));
+  if (missing.length) return `${DEEPSEEK_BALANCE_REFERENCE_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateDeepSeekBalanceRises(db) {
+  // The column goes on 0025's table: a database that skipped 0025 gets it first.
+  migrateDeepSeekUsageRequestsDaily(db);
+  let columnsAdded = 0;
+  const present = columnNames(db, DEEPSEEK_BALANCE_REFERENCE_TABLE);
+  for (const [name, ddl] of DEEPSEEK_BALANCE_RISE_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE ${DEEPSEEK_BALANCE_REFERENCE_TABLE} ADD COLUMN ${name} ${ddl}`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekBalanceRises(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0029 on ${dbPath}`);
+    console.log(result.applied
+      ? `  deepseek balance rises: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0029 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0030-deepseek-usage-actuals.mjs

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * Migration: the figures of DeepSeek's own usage export, imported from the
+ * platform's two CSV files (services/deepseek-usage-import.mjs). The usage
+ * card in Check Usage shows them instead of the relay's estimate for the
+ * days and models they cover.
+ *
+ * Adds one table of its own, `deepseek_usage_actuals`, one row per export
+ * day, model and API key (the key is the day, so a re-export taken in
+ * another time zone replaces the day instead of adding a second row):
+ * - `day`: the local date of `period_start`, in the export's time zone;
+ * - `period_start`, `period_end`: the first start and last end of the day's
+ *   periods as the export gives them (ISO with the export's offset);
+ * - `model`, `key_fp` (the key masked as `sk-XXXXX…YYYY`), `key_name`;
+ * - `hit_tokens`, `miss_tokens`, `output_tokens`, `request_count`;
+ * - `cost`, `currency`: the period's cost, amount × price summed;
+ * - `imported_at`.
+ *
+ * The relay's own usage tables are not touched. Additive and idempotent.
+ * Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0030-deepseek-usage-actuals.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const DEEPSEEK_USAGE_ACTUALS_TABLE = 'deepseek_usage_actuals';
+
+export const DEEPSEEK_USAGE_ACTUALS_COLUMNS = Object.freeze([
+  'period_start',
+  'period_end',
+  'day',
+  'model',
+  'key_fp',
+  'key_name',
+  'hit_tokens',
+  'miss_tokens',
+  'output_tokens',
+  'request_count',
+  'cost',
+  'currency',
+  'imported_at',
+]);
+
+const CREATE_SQL = `
+  CREATE TABLE IF NOT EXISTS ${DEEPSEEK_USAGE_ACTUALS_TABLE} (
+    period_start TEXT NOT NULL,
+    period_end TEXT NOT NULL,
+    day TEXT NOT NULL,
+    model TEXT NOT NULL,
+    key_fp TEXT NOT NULL,
+    key_name TEXT NOT NULL DEFAULT '',
+    hit_tokens INTEGER NOT NULL DEFAULT 0,
+    miss_tokens INTEGER NOT NULL DEFAULT 0,
+    output_tokens INTEGER NOT NULL DEFAULT 0,
+    request_count INTEGER NOT NULL DEFAULT 0,
+    cost REAL NOT NULL DEFAULT 0,
+    currency TEXT NOT NULL DEFAULT '',
+    imported_at TEXT NOT NULL,
+    PRIMARY KEY (day, model, key_fp)
+  );
+  CREATE INDEX IF NOT EXISTS idx_${DEEPSEEK_USAGE_ACTUALS_TABLE}_key_day
+    ON ${DEEPSEEK_USAGE_ACTUALS_TABLE} (key_fp, day);
+`;
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the import from using the table: '' when nothing does. */
+export function deepseekUsageActualsProblem(db) {
+  if (!tableExists(db, DEEPSEEK_USAGE_ACTUALS_TABLE)) return `no ${DEEPSEEK_USAGE_ACTUALS_TABLE} table`;
+  const present = columnNames(db, DEEPSEEK_USAGE_ACTUALS_TABLE);
+  const missing = DEEPSEEK_USAGE_ACTUALS_COLUMNS.filter((name) => !present.has(name));
+  if (missing.length) return `${DEEPSEEK_USAGE_ACTUALS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateDeepSeekUsageActuals(db) {
+  const existed = tableExists(db, DEEPSEEK_USAGE_ACTUALS_TABLE);
+  db.exec(CREATE_SQL);
+  return { applied: !existed, tableCreated: !existed };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateDeepSeekUsageActuals(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0030 on ${dbPath}`);
+    console.log(result.applied
+      ? '  deepseek usage actuals: table created'
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0030 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0031-queue-provider.mjs

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * Migration: a queue row names the billing it runs on (the Claude billing
+ * switch, services/claude-billing-switch-service.mjs).
+ *
+ * `queue.provider`: the provider the row was queued under, written at every
+ * insert from the chat's `runtime_sessions.provider_type`. A Claude chat can
+ * move between `claude` (the subscription) and `claude-api` (the saved API
+ * key); the switch re-stamps the chat's rows that have not started, and every
+ * requeue re-stamps to the chat's billing of that moment. The relay hands a
+ * row only to a worker of that kind, so a turn never runs on a billing nobody
+ * asked for. NULL (a row from before this column) means the chat's billing.
+ *
+ * Two triggers keep the stamp without every writer having to know it:
+ * - `queue_provider_after_insert`: a row inserted without a provider (the
+ *   send route, schedules, events, restart-resume, the board, the usage-limit
+ *   follow-up) takes its chat's provider when the chat is a Claude or Claude
+ *   API one. A writer that names one (a continuation: the kind of the worker
+ *   that runs it) keeps it.
+ * - `queue_provider_after_requeue`: a row going back from processing to
+ *   pending or parked (the stale sweep, dead-worker recovery, a hand-back) is
+ *   a new turn, and takes the chat's provider of that moment.
+ *
+ * The back-fill gives the unfinished rows of Claude and Claude API chats
+ * (pending, parked, processing) their chat's provider. It touches only rows
+ * without one, so it is idempotent; finished rows stay NULL.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0031-queue-provider.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const QUEUE_PROVIDER_COLUMN = 'provider';
+export const QUEUE_PROVIDER_TRIGGERS = Object.freeze(['queue_provider_after_insert', 'queue_provider_after_requeue']);
+
+// The chat's billing, when it is a Claude one: NULL for every other provider.
+const chatClaudeBillingSql = (conversationIdSql) => `(
+  SELECT LOWER(TRIM(rs.provider_type)) FROM runtime_sessions rs
+  WHERE rs.conversation_id = ${conversationIdSql}
+    AND LOWER(TRIM(rs.provider_type)) IN ('claude', 'claude-api')
+)`;
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the relay from stamping rows: '' when nothing does. */
+export function queueProviderProblem(db) {
+  if (!tableExists(db, 'queue')) return 'no queue table';
+  if (!columnNames(db, 'queue').has(QUEUE_PROVIDER_COLUMN)) return 'queue lacks provider';
+  const triggers = new Set(db.prepare(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND tbl_name = 'queue'`).all().map((row) => row.name));
+  const missing = QUEUE_PROVIDER_TRIGGERS.filter((name) => !triggers.has(name));
+  if (missing.length) return `queue lacks the trigger ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateQueueProvider(db) {
+  if (!tableExists(db, 'queue')) return { applied: false, columnsAdded: 0, triggersAdded: 0, rowsFilled: 0 };
+  // The triggers and the back-fill read provider_type: a table without it
+  // waits for the schema boot to add it.
+  if (!tableExists(db, 'runtime_sessions') || !columnNames(db, 'runtime_sessions').has('provider_type')) {
+    return { applied: false, columnsAdded: 0, triggersAdded: 0, rowsFilled: 0 };
+  }
+  let columnsAdded = 0;
+  if (!columnNames(db, 'queue').has(QUEUE_PROVIDER_COLUMN)) {
+    db.exec(`ALTER TABLE queue ADD COLUMN ${QUEUE_PROVIDER_COLUMN} TEXT`);
+    columnsAdded += 1;
+  }
+  const present = new Set(db.prepare(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND tbl_name = 'queue'`).all().map((row) => row.name));
+  let triggersAdded = 0;
+  if (!present.has('queue_provider_after_insert')) {
+    db.exec(`
+      CREATE TRIGGER queue_provider_after_insert
+      AFTER INSERT ON queue
+      WHEN NEW.provider IS NULL
+      BEGIN
+        UPDATE queue SET provider = ${chatClaudeBillingSql('NEW.conversation_id')} WHERE id = NEW.id;
+      END
+    `);
+    triggersAdded += 1;
+  }
+  if (!present.has('queue_provider_after_requeue')) {
+    db.exec(`
+      CREATE TRIGGER queue_provider_after_requeue
+      AFTER UPDATE OF status ON queue
+      WHEN OLD.status = 'processing' AND NEW.status IN ('pending', 'parked')
+      BEGIN
+        UPDATE queue SET provider = COALESCE(${chatClaudeBillingSql('NEW.conversation_id')}, NEW.provider) WHERE id = NEW.id;
+      END
+    `);
+    triggersAdded += 1;
+  }
+  const rowsFilled = db.prepare(`
+    UPDATE queue
+    SET provider = ${chatClaudeBillingSql('queue.conversation_id')}
+    WHERE provider IS NULL
+      AND status IN ('pending', 'parked', 'processing')
+      AND ${chatClaudeBillingSql('queue.conversation_id')} IS NOT NULL
+  `).run().changes;
+  return { applied: columnsAdded > 0 || triggersAdded > 0 || rowsFilled > 0, columnsAdded, triggersAdded, rowsFilled };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateQueueProvider(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0031 on ${dbPath}`);
+    console.log(result.applied
+      ? `  queue provider: columns added ${result.columnsAdded}, triggers added ${result.triggersAdded}, rows filled ${result.rowsFilled}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0031 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0032-runtime-session-billing-switch.mjs

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * Migration: a runtime session remembers its last billing switch (the Claude
+ * billing switch, services/claude-billing-switch-service.mjs).
+ *
+ * `runtime_sessions` gains two columns:
+ * - `billing_switched_at`: when the chat last moved between `claude` (the
+ *   subscription) and `claude-api` (the saved API key); NULL for a chat that
+ *   never did. A worker started before the switch existed reports no kind, and
+ *   on a chat with this set the relay cannot assume the kind from
+ *   `provider_type`: it replaces that worker once, when it is idle. A chat
+ *   never switched has had one billing, which also settles whose turns its
+ *   older messages are.
+ * - `billing_switched_by`: who asked: `user` (the toggle), `agent` (an
+ *   agent's `send` with a provider) or `usage-limit` (the button on the
+ *   usage-limit note).
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0032-runtime-session-billing-switch.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+// Added to runtime_sessions, with their DDL.
+export const RUNTIME_SESSION_BILLING_SWITCH_COLUMNS = Object.freeze([
+  ['billing_switched_at', 'TEXT'],
+  ['billing_switched_by', 'TEXT'],
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+/** What keeps the switch from recording itself: '' when nothing does. */
+export function runtimeSessionBillingSwitchProblem(db) {
+  if (!tableExists(db, 'runtime_sessions')) return 'no runtime_sessions table';
+  const present = columnNames(db, 'runtime_sessions');
+  const missing = RUNTIME_SESSION_BILLING_SWITCH_COLUMNS.map(([name]) => name).filter((name) => !present.has(name));
+  if (missing.length) return `runtime_sessions lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateRuntimeSessionBillingSwitch(db) {
+  if (!tableExists(db, 'runtime_sessions')) return { applied: false, columnsAdded: 0 };
+  let columnsAdded = 0;
+  const present = columnNames(db, 'runtime_sessions');
+  for (const [name, ddl] of RUNTIME_SESSION_BILLING_SWITCH_COLUMNS) {
+    if (present.has(name)) continue;
+    db.exec(`ALTER TABLE runtime_sessions ADD COLUMN ${name} ${ddl}`);
+    columnsAdded += 1;
+  }
+  return { applied: columnsAdded > 0, columnsAdded };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateRuntimeSessionBillingSwitch(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0032 on ${dbPath}`);
+    console.log(result.applied
+      ? `  runtime session billing switch: columns added ${result.columnsAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0032 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/migrations/0033-claude-api-usage-checkpoints.mjs

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Migration: Claude API usage checkpoints (services/plan-usage-service.mjs,
+ * recordClaudeApiUsageReport; the booking behind the Claude API card and its
+ * monthly cap).
+ *
+ * Both Claude workers, the subscription one and the Claude API one, post
+ * after every turn (POST /api/claude-api-usage). A chat can move between the
+ * two billings and keeps its Claude Code session, so what one billing ran
+ * shows up in the totals the other one reports after the switch. One row per
+ * (conversation, Claude Code session, CLI process, model):
+ *
+ * - `conversation_id`, `native_session_id` (the CLI's session id), `run_id`
+ *   (the id the worker gives each CLI process it spawns), `model`.
+ * - `billing`: the kind of the worker that posted: `claude` or `claude-api`.
+ * - `run_hit_tokens`, `run_miss_tokens`, `run_output_tokens`, `run_cost_usd`:
+ *   what this process has run so far, counted from zero, as far as it was
+ *   booked. A post books its rise over these; one at or below them is a
+ *   retried or reordered post and books nothing. Only `claude-api` rows book
+ *   spend.
+ * - `session_hit_tokens`, `session_miss_tokens`, `session_output_tokens`,
+ *   `session_cost_usd`: the CLI's own cumulative totals for the session at
+ *   that post. The row of a session with the latest `last_turn_at` is the
+ *   session's mark: a CLI resumed on the session, under either billing,
+ *   re-reports the earlier turns in its first result, and the mark is what
+ *   that first result is measured against.
+ * - `cost_unknown`: 1 when the CLI had no price for the model.
+ * - `last_turn_id` (the queue row of the turn), `last_turn_at` (when its
+ *   result came): the turn the row covers. A mark is used only when no
+ *   completed turn of the session is newer than it.
+ * - `updated_at`.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0033-claude-api-usage-checkpoints.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+export const CLAUDE_API_USAGE_CHECKPOINTS_TABLE = 'claude_api_usage_checkpoints';
+
+export const CLAUDE_API_USAGE_CHECKPOINT_COLUMNS = Object.freeze([
+  'conversation_id',
+  'native_session_id',
+  'run_id',
+  'model',
+  'billing',
+  'run_hit_tokens',
+  'run_miss_tokens',
+  'run_output_tokens',
+  'run_cost_usd',
+  'session_hit_tokens',
+  'session_miss_tokens',
+  'session_output_tokens',
+  'session_cost_usd',
+  'cost_unknown',
+  'last_turn_id',
+  'last_turn_at',
+  'updated_at',
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+/** What keeps the service from using the table: '' when nothing does. */
+export function claudeApiUsageCheckpointsProblem(db) {
+  if (!tableExists(db, CLAUDE_API_USAGE_CHECKPOINTS_TABLE)) return `no ${CLAUDE_API_USAGE_CHECKPOINTS_TABLE} table`;
+  const present = new Set(db.prepare(`PRAGMA table_info(${CLAUDE_API_USAGE_CHECKPOINTS_TABLE})`).all().map((column) => column.name));
+  const missing = CLAUDE_API_USAGE_CHECKPOINT_COLUMNS.filter((name) => !present.has(name));
+  if (missing.length) return `${CLAUDE_API_USAGE_CHECKPOINTS_TABLE} lacks ${missing.join(', ')}`;
+  return '';
+}
+
+export function migrateClaudeApiUsageCheckpoints(db) {
+  if (tableExists(db, CLAUDE_API_USAGE_CHECKPOINTS_TABLE)) return { applied: false, tablesAdded: 0 };
+  db.exec(`
+    CREATE TABLE ${CLAUDE_API_USAGE_CHECKPOINTS_TABLE} (
+      conversation_id        TEXT NOT NULL,
+      native_session_id      TEXT NOT NULL,
+      run_id                 TEXT NOT NULL,
+      model                  TEXT NOT NULL,
+      billing                TEXT NOT NULL,
+      run_hit_tokens         INTEGER NOT NULL DEFAULT 0,
+      run_miss_tokens        INTEGER NOT NULL DEFAULT 0,
+      run_output_tokens      INTEGER NOT NULL DEFAULT 0,
+      run_cost_usd           REAL NOT NULL DEFAULT 0,
+      session_hit_tokens     INTEGER NOT NULL DEFAULT 0,
+      session_miss_tokens    INTEGER NOT NULL DEFAULT 0,
+      session_output_tokens  INTEGER NOT NULL DEFAULT 0,
+      session_cost_usd       REAL NOT NULL DEFAULT 0,
+      cost_unknown           INTEGER NOT NULL DEFAULT 0,
+      last_turn_id           TEXT,
+      last_turn_at           TEXT,
+      updated_at             TEXT NOT NULL,
+      PRIMARY KEY (conversation_id, native_session_id, run_id, model)
+    )
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_claude_api_usage_checkpoints_mark
+      ON ${CLAUDE_API_USAGE_CHECKPOINTS_TABLE}(native_session_id, last_turn_at)
+  `);
+  return { applied: true, tablesAdded: 1 };
+}
+
+function defaultDbPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, '..', 'data', 'copilot.db');
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateClaudeApiUsageCheckpoints(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
+  try {
+    const result = migrate(dbPath);
+    console.log(`Migration 0033 on ${dbPath}`);
+    console.log(result.applied ? `  claude api usage checkpoints: tables added ${result.tablesAdded}` : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0033 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}