maka-agent 0.2.0-dev.22.20260905 → 0.2.0-dev.23.20260906

package/node_modules/@maka/storage/dist/sqlite-usage-schema.js

@@ -16,7 +16,132 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-export const SQLITE_USAGE_SCHEMA_VERSION = 5;
+export const SQLITE_USAGE_SCHEMA_VERSION = 7;
+/**
+ * The canonical ledger's columns, in the order every statement binds them.
+ *
+ * Ordered so `attempt_id, completed_at, session_id` — the three a damaged row
+ * keeps — come first, and the pricing columns follow.
+ */
+export const MODEL_CALL_COLUMNS = [
+    'attempt_id',
+    'completed_at',
+    'session_id',
+    'logical_call_id',
+    'turn_id',
+    'call_kind',
+    'connection_slug',
+    'provider_id',
+    'model_id',
+    'latency_ms',
+    'status',
+    'error_class',
+    'usage_basis',
+    'input_tokens',
+    'output_tokens',
+    'cache_read_input_tokens',
+    'cache_miss_input_tokens',
+    'cache_write_input_tokens',
+    'reasoning_tokens',
+    'cost_basis',
+    'cost_usd',
+];
+/**
+ * The JSON path each pricing column was read from before the columns existed,
+ * used once by the migration that converted the rows.
+ */
+const MODEL_CALL_COLUMN_SOURCES = [
+    ['logical_call_id', '$.logicalCallId'],
+    ['turn_id', '$.turnId'],
+    ['call_kind', '$.callKind'],
+    ['connection_slug', '$.connectionSlug'],
+    ['provider_id', '$.providerId'],
+    ['model_id', '$.modelId'],
+    ['latency_ms', '$.latencyMs'],
+    ['status', '$.status'],
+    ['error_class', '$.errorClass'],
+    ['usage_basis', '$.usageBasis'],
+    ['input_tokens', '$.inputTokens'],
+    ['output_tokens', '$.outputTokens'],
+    ['cache_read_input_tokens', '$.cacheReadInputTokens'],
+    ['cache_miss_input_tokens', '$.cacheMissInputTokens'],
+    ['cache_write_input_tokens', '$.cacheWriteInputTokens'],
+    ['reasoning_tokens', '$.reasoningTokens'],
+    ['cost_basis', '$.costBasis'],
+    ['cost_usd', '$.costUsd'],
+];
+/** The columns that are present together or not at all. See the table's CHECK. */
+const MODEL_CALL_REQUIRED_COLUMNS = [
+    'logical_call_id',
+    'turn_id',
+    'call_kind',
+    'provider_id',
+    'model_id',
+    'latency_ms',
+    'status',
+    'usage_basis',
+    'cost_basis',
+];
+const MODEL_CALL_TOKEN_COLUMNS = [
+    'input_tokens',
+    'output_tokens',
+    'cache_read_input_tokens',
+    'cache_miss_input_tokens',
+    'cache_write_input_tokens',
+    'reasoning_tokens',
+];
+const NO_TOKENS = MODEL_CALL_TOKEN_COLUMNS.map((column) => `${column} IS NULL`).join(' AND ');
+/**
+ * Canonical model-call accounting ledger (#1679).
+ *
+ * One column per field a cost answer reads, so the totals are a `SUM` the
+ * database can compute rather than every row of a workspace's history parsed
+ * into memory first.
+ *
+ * A row is either a complete pricing record or a tombstone that kept only the
+ * identity and timestamp of a call whose stored form was damaged. Never half of
+ * each — which is what makes `cost_basis IS NOT NULL` a sound test for "this row
+ * can be counted", and its negation the count a read reports as unreadable.
+ *
+ * The vocabularies (`status`, `call_kind`) are deliberately not constrained
+ * here. They are already validated where a record is decoded, and a CHECK on
+ * them would turn one damaged row into a failed migration for the whole
+ * workspace.
+ */
+const MODEL_CALL_TABLE = `
+  CREATE TABLE IF NOT EXISTS %TABLE% (
+    attempt_id TEXT PRIMARY KEY,
+    completed_at INTEGER NOT NULL CHECK (completed_at >= 0),
+    session_id TEXT,
+    logical_call_id TEXT,
+    turn_id TEXT,
+    call_kind TEXT,
+    connection_slug TEXT,
+    provider_id TEXT,
+    model_id TEXT,
+    latency_ms INTEGER,
+    status TEXT,
+    error_class TEXT,
+    usage_basis TEXT,
+    input_tokens INTEGER,
+    output_tokens INTEGER,
+    cache_read_input_tokens INTEGER,
+    cache_miss_input_tokens INTEGER,
+    cache_write_input_tokens INTEGER,
+    reasoning_tokens INTEGER,
+    cost_basis TEXT,
+    cost_usd REAL,
+    CHECK (${MODEL_CALL_REQUIRED_COLUMNS.map((column) => `(${column} IS NULL) = (cost_basis IS NULL)`).join(' AND ')}),
+    -- A price that could not be resolved must never surface as an amount, and a
+    -- priced call must carry one. Zero stays legal: it is the only way to say a
+    -- call was genuinely free.
+    CHECK (cost_basis IS NOT 'priced' OR cost_usd IS NOT NULL),
+    CHECK (cost_basis IS NOT 'unpriced' OR cost_usd IS NULL),
+    -- "The provider reported no usage" and "it reported zero" are different
+    -- facts, so a missing-usage row carries no token counts at all.
+    CHECK (usage_basis IS NOT 'missing' OR (${NO_TOKENS}))
+  )
+`;
 export function migrateSqliteUsageDatabase(db) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS usage_llm_calls (
@@ -40,18 +165,7 @@ export function migrateSqliteUsageDatabase(db) {
     CREATE INDEX IF NOT EXISTS usage_tool_invocations_ts
       ON usage_tool_invocations(ts DESC, id);
 
-    -- Canonical model-call accounting ledger (#1679). Separate from
-    -- usage_llm_calls, which is a frozen historical projection: these rows carry
-    -- usageBasis/costBasis, which that schema cannot express.
-    CREATE TABLE IF NOT EXISTS usage_model_call_attempts (
-      attempt_id TEXT PRIMARY KEY,
-      completed_at INTEGER NOT NULL CHECK (completed_at >= 0),
-      record_json TEXT NOT NULL,
-      session_id TEXT
-    );
-
-    CREATE INDEX IF NOT EXISTS usage_model_call_attempts_completed_at
-      ON usage_model_call_attempts(completed_at DESC, attempt_id);
+    ${MODEL_CALL_TABLE.replace('%TABLE%', 'usage_model_call_attempts')};
 
     -- The AgentRun sequence is the projection's sole progress authority. A run
     -- is behind exactly when its latest model-call event is newer than this
@@ -82,26 +196,92 @@ export function migrateSqliteUsageDatabase(db) {
   `);
     db.exec('DROP TABLE IF EXISTS usage_model_call_reprojection');
     ensureColumn(db, 'usage_llm_calls', 'session_id', 'TEXT');
-    ensureColumn(db, 'usage_model_call_attempts', 'session_id', 'TEXT');
     db.exec(`
     UPDATE usage_llm_calls
     SET session_id = json_extract(record_json, '$.sessionId')
     WHERE session_id IS NULL AND json_valid(record_json);
 
-    UPDATE usage_model_call_attempts
-    SET session_id = json_extract(record_json, '$.sessionId')
-    WHERE session_id IS NULL AND json_valid(record_json);
-
     CREATE INDEX IF NOT EXISTS usage_llm_calls_session_ts
       ON usage_llm_calls(session_id, ts DESC, id);
+  `);
+    // A ledger old enough to predate Session attribution has no column to carry
+    // through, and the conversion below reads one.
+    ensureColumn(db, 'usage_model_call_attempts', 'session_id', 'TEXT');
+    spreadModelCallRecordJson(db);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS usage_model_call_attempts_completed_at
+      ON usage_model_call_attempts(completed_at DESC, attempt_id);
 
     CREATE INDEX IF NOT EXISTS usage_model_call_attempts_session_completed_at
       ON usage_model_call_attempts(session_id, completed_at DESC, attempt_id);
   `);
 }
+/**
+ * Converts rows that stored the record as one JSON blob into the columns.
+ *
+ * Not rebuilt from the AgentRun authority, the usual move for a read model:
+ * deleting a Session drops its runs and cascades their events while these rows
+ * are kept on purpose, so for those calls this table is the last copy and a
+ * wipe-and-replay would erase their spend. See the header of
+ * `model-call-ledger.ts`.
+ *
+ * A blob that does not yield a whole record — damaged text, or a row some other
+ * schema left behind — keeps its identity and timestamp and loses the rest. That
+ * is the same claim the old JSON reader made by counting it as unreadable, and
+ * it is why the conversion is all-or-nothing per row: a half-filled row would
+ * make the table's own CHECK unsatisfiable and take the whole migration with it.
+ */
+function spreadModelCallRecordJson(db) {
+    if (!hasColumn(db, 'usage_model_call_attempts', 'record_json'))
+        return;
+    const extracted = MODEL_CALL_COLUMN_SOURCES.map(([column, path]) => `CASE WHEN json_valid(record_json) THEN json_extract(record_json, '${path}') END AS ${column}`).join(',\n        ');
+    const readable = [
+        ...MODEL_CALL_REQUIRED_COLUMNS.map((column) => `${column} IS NOT NULL`),
+        "(cost_basis IS NOT 'priced' OR cost_usd IS NOT NULL)",
+        "(cost_basis IS NOT 'unpriced' OR cost_usd IS NULL)",
+        `(usage_basis IS NOT 'missing' OR (${NO_TOKENS}))`,
+    ].join('\n          AND ');
+    const pricing = MODEL_CALL_COLUMN_SOURCES.map(([column]) => `CASE WHEN readable THEN ${column} END`).join(',\n      ');
+    // The old table moves aside so the new one is created under its final name:
+    // a table renamed into place keeps a rewritten `CREATE` statement, and the
+    // schema guard compares those texts.
+    db.exec(`
+    ALTER TABLE usage_model_call_attempts RENAME TO usage_model_call_attempts_blob;
+
+    ${MODEL_CALL_TABLE.replace('%TABLE%', 'usage_model_call_attempts')};
+
+    INSERT INTO usage_model_call_attempts(${MODEL_CALL_COLUMNS.join(', ')})
+    WITH extracted AS (
+      SELECT
+        attempt_id,
+        completed_at,
+        -- A tombstone keeps its Session: the row still says a call happened here.
+        COALESCE(
+          session_id,
+          CASE WHEN json_valid(record_json) THEN json_extract(record_json, '$.sessionId') END
+        ) AS session_id,
+        ${extracted}
+      FROM usage_model_call_attempts_blob
+    ),
+    classified AS (
+      SELECT *, (${readable}) AS readable FROM extracted
+    )
+    SELECT
+      attempt_id,
+      completed_at,
+      session_id,
+      ${pricing}
+    FROM classified;
+
+    DROP TABLE usage_model_call_attempts_blob;
+  `);
+}
 function ensureColumn(db, table, column, definition) {
-    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
-    if (columns.some((candidate) => candidate.name === column))
+    if (hasColumn(db, table, column))
         return;
     db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
 }
+function hasColumn(db, table, column) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    return columns.some((candidate) => candidate.name === column);
+}

package/node_modules/@maka/storage/dist/usage-stores.js

@@ -291,7 +291,9 @@ function createWriterFacade(lease, telemetry, modelCalls, pricing) {
             recordToolInvocation: (record) => admitSessionUsageMutation(record.sessionId, () => telemetry.insertToolInvocation(record)),
         },
         modelCalls: {
-            modelCallAttempts: (range, sessionId) => read(() => modelCalls.read(range, sessionId)),
+            modelCallSummary: (query, now) => read(() => modelCalls.summary(query, now)),
+            modelCallBuckets: (query, groupBy, now) => read(() => modelCalls.buckets(query, groupBy, now)),
+            modelCallLogs: (query, now, offset, limit) => read(() => modelCalls.logs(query, now, offset, limit)),
             catchUpModelCallProjection: admitModelCallProjectionCatchUp,
         },
         pricing: {
@@ -323,7 +325,9 @@ function telemetryReader(repo, run) {
 }
 function modelCallReader(ledger, run) {
     return Object.freeze({
-        modelCallAttempts: (range, sessionId) => run(() => ledger.read(range, sessionId)),
+        modelCallSummary: (query, now) => run(() => ledger.summary(query, now)),
+        modelCallBuckets: (query, groupBy, now) => run(() => ledger.buckets(query, groupBy, now)),
+        modelCallLogs: (query, now, offset, limit) => run(() => ledger.logs(query, now, offset, limit)),
     });
 }
 function pricingReader(store, run) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maka-agent",
-  "version": "0.2.0-dev.22.20260905",
+  "version": "0.2.0-dev.23.20260906",
   "description": "Apache Maka (Incubating) developer snapshot; not an Apache release.",
   "license": "Apache-2.0",
   "type": "module",