blun-king-cli 9.1.465 → 9.1.466

package/bin/agent-api-turn-controller.mjs

@@ -1,4 +1,10 @@
 import { createAgentApiRuntime } from './agent-api-runtime.mjs';
+import usageJournalModule from './agent-api-usage-journal.cjs';
+
+const {
+  createAgentApiTaskId,
+  createAgentApiUsageJournal,
+} = usageJournalModule;
 
 const MAIN_AGENT_ID = 'main';
 const PUBLIC_MODEL_ID = 'king';
@@ -116,6 +122,7 @@ function openAiEnvelope(turn, message, finishReason) {
     }],
     blun: {
       mode: 'agent',
+      task_id: turn.taskId,
       session_id: turn.sessionId,
       request_id: turn.requestId,
     },
@@ -149,6 +156,8 @@ function completedResponse(turn, event) {
 
 function createAgentApiTurnController(options = {}) {
   const runtime = options.runtime ?? createAgentApiRuntime(options.runtimeOptions);
+  const usageJournal = options.usageJournal ?? createAgentApiUsageJournal();
+  const taskIdFactory = options.taskIdFactory ?? createAgentApiTaskId;
   const publicModel = options.publicModel ?? PUBLIC_MODEL_ID;
   const now = options.now ?? Date.now;
   const activeTurns = new Map();
@@ -172,7 +181,7 @@ function createAgentApiTurnController(options = {}) {
     return turn;
   }
 
-  async function closeBinding(turn, kind, reason) {
+  async function closeBinding(turn, kind, reason, status = 'failed') {
     if (turn.closed) return;
     turn.closed = true;
     activeTurns.delete(turn.sessionId);
@@ -182,6 +191,12 @@ function createAgentApiTurnController(options = {}) {
     if (kind === 'finish') {
       try {
         await turn.binding.finish();
+        usageJournal.finishTask({
+          taskId: turn.taskId,
+          requestId: turn.requestId,
+          sessionId: turn.sessionId,
+          status,
+        });
         return;
       } catch (error) {
         try {
@@ -189,10 +204,38 @@ function createAgentApiTurnController(options = {}) {
         } catch {
           // Preserve the original finish error.
         }
+        try {
+          usageJournal.finishTask({
+            taskId: turn.taskId,
+            requestId: turn.requestId,
+            sessionId: turn.sessionId,
+            status: 'failed',
+          });
+        } catch {
+          // Preserve the original finish error.
+        }
         throw error;
       }
     }
-    await turn.binding.abort(reason ?? 'Agent API turn aborted');
+    let abortError;
+    try {
+      await turn.binding.abort(reason ?? 'Agent API turn aborted');
+    } catch (error) {
+      abortError = error;
+    }
+    let journalError;
+    try {
+      usageJournal.finishTask({
+        taskId: turn.taskId,
+        requestId: turn.requestId,
+        sessionId: turn.sessionId,
+        status,
+      });
+    } catch (error) {
+      journalError = error;
+    }
+    if (abortError !== undefined) throw abortError;
+    if (journalError !== undefined) throw journalError;
   }
 
   function settleTerminal(turn, event) {
@@ -223,6 +266,23 @@ function createAgentApiTurnController(options = {}) {
       }
       if (turn.turnId === undefined || event.turnId !== turn.turnId) return;
       switch (event.type) {
+        case 'turn.step.completed':
+          try {
+            usageJournal.recordModelCall({
+              taskId: turn.taskId,
+              requestId: turn.requestId,
+              sessionId: turn.sessionId,
+              callId: event.stepId ?? `${turn.turnId}:${event.step}`,
+              usage: event.usage ?? null,
+            });
+          } catch (error) {
+            settleTerminal(turn, {
+              type: 'turn.error',
+              reason: 'failed',
+              error,
+            });
+          }
+          return;
         case 'turn.step.retrying':
           turn.assistantText = '';
           return;
@@ -268,7 +328,7 @@ function createAgentApiTurnController(options = {}) {
     }
 
     const response = completedResponse(turn, outcome.event);
-    await closeBinding(turn, 'finish');
+    await closeBinding(turn, 'finish', undefined, 'completed');
     return response;
   }
 
@@ -293,6 +353,7 @@ function createAgentApiTurnController(options = {}) {
       requestId,
       tools: input.tools ?? [],
     });
+    const taskId = requireId(taskIdFactory(sessionId, requestId), 'taskId');
     const turn = {
       assistantText: '',
       binding,
@@ -302,11 +363,22 @@ function createAgentApiTurnController(options = {}) {
       requestId,
       session: input.session,
       sessionId,
+      taskId,
       terminal: createDeferred(),
       terminalSettled: false,
       turnId: undefined,
       unsubscribe: undefined,
     };
+    try {
+      usageJournal.startTask({ taskId, requestId, sessionId });
+    } catch (error) {
+      try {
+        await binding.abort('Agent API usage task could not be started');
+      } catch {
+        // Preserve the journal error.
+      }
+      throw error;
+    }
     activeTurns.set(sessionId, turn);
     turn.unsubscribe = installEventListener(turn);
 
@@ -362,7 +434,7 @@ function createAgentApiTurnController(options = {}) {
       : 'Agent API turn cancelled';
     const outcomes = await Promise.allSettled([
       turn.session.cancel(),
-      closeBinding(turn, 'abort', reason),
+      closeBinding(turn, 'abort', reason, 'cancelled'),
     ]);
     const failure = outcomes.find((outcome) => outcome.status === 'rejected');
     if (failure !== undefined) throw failure.reason;
@@ -373,6 +445,7 @@ function createAgentApiTurnController(options = {}) {
     activeTurnCount: () => activeTurns.size,
     cancelTurn,
     continueTurn,
+    getUsageTask: (taskId) => usageJournal.getTask(taskId),
     startTurn,
   });
 }

package/bin/agent-api-usage-journal.cjs

@@ -0,0 +1,259 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PUBLIC_MODEL_ID = 'king';
+const JOURNAL_VERSION = 1;
+
+class AgentApiUsageJournalError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'AgentApiUsageJournalError';
+    this.code = code;
+  }
+}
+
+function journalError(code, message) {
+  return new AgentApiUsageJournalError(code, message);
+}
+
+function requireId(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw journalError('AGENT_API_USAGE_INVALID_SCOPE', `${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function tokenCount(value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw journalError(
+      'AGENT_API_USAGE_INVALID_VALUE',
+      'usage token counters must be finite non-negative numbers',
+    );
+  }
+  return Math.trunc(value);
+}
+
+function normalizeRawUsage(usage) {
+  if (usage === undefined || usage === null) return null;
+  if (typeof usage !== 'object' || Array.isArray(usage)) {
+    throw journalError('AGENT_API_USAGE_INVALID_VALUE', 'usage must be an object or null');
+  }
+
+  if (Object.hasOwn(usage, 'prompt_tokens') || Object.hasOwn(usage, 'completion_tokens')) {
+    const promptTokens = tokenCount(usage.prompt_tokens ?? 0);
+    const completionTokens = tokenCount(usage.completion_tokens ?? 0);
+    const cachedTokens = Math.min(
+      promptTokens,
+      tokenCount(usage.prompt_tokens_details?.cached_tokens ?? 0),
+    );
+    return {
+      prompt_tokens: promptTokens,
+      completion_tokens: completionTokens,
+      prompt_tokens_details: { cached_tokens: cachedTokens },
+    };
+  }
+
+  const inputOther = tokenCount(usage.inputOther ?? 0);
+  const inputCacheRead = tokenCount(usage.inputCacheRead ?? 0);
+  const inputCacheCreation = tokenCount(usage.inputCacheCreation ?? 0);
+  const output = tokenCount(usage.output ?? 0);
+  return {
+    prompt_tokens: inputOther + inputCacheRead + inputCacheCreation,
+    completion_tokens: output,
+    prompt_tokens_details: { cached_tokens: inputCacheRead },
+  };
+}
+
+function createAgentApiTaskId(sessionId, requestId) {
+  const session = requireId(sessionId, 'sessionId');
+  const request = requireId(requestId, 'requestId');
+  const digest = crypto.createHash('sha256').update(`${session}\0${request}`).digest('hex');
+  return `task-${digest.slice(0, 24)}`;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+function normalizeTimestamp(value, label) {
+  const timestamp = typeof value === 'string' ? value.trim() : '';
+  if (timestamp.length === 0 || Number.isNaN(Date.parse(timestamp))) {
+    throw journalError('AGENT_API_USAGE_INVALID_TIME', `${label} must be an ISO timestamp`);
+  }
+  return timestamp;
+}
+
+function createAgentApiUsageJournal(options = {}) {
+  const filePath = options.filePath === undefined
+    ? null
+    : path.resolve(String(options.filePath));
+  const now = options.now ?? (() => new Date().toISOString());
+  const tasks = new Map();
+
+  function taskForScope(input) {
+    const taskId = requireId(input.taskId, 'taskId');
+    const requestId = requireId(input.requestId, 'requestId');
+    const sessionId = requireId(input.sessionId, 'sessionId');
+    const task = tasks.get(taskId);
+    if (task === undefined) {
+      throw journalError('AGENT_API_USAGE_TASK_NOT_FOUND', 'usage task does not exist');
+    }
+    if (task.request_id !== requestId || task.session_id !== sessionId) {
+      throw journalError(
+        'AGENT_API_USAGE_SCOPE_MISMATCH',
+        'usage event does not belong to this task',
+      );
+    }
+    return task;
+  }
+
+  function appendEvent(event) {
+    if (filePath === null) return;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, `${JSON.stringify(event)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+  }
+
+  function replay(event) {
+    if (event === null || typeof event !== 'object' || event.version !== JOURNAL_VERSION) {
+      throw journalError('AGENT_API_USAGE_JOURNAL_CORRUPT', 'invalid usage journal event');
+    }
+    if (event.type === 'task.started') {
+      if (tasks.has(event.task_id)) {
+        throw journalError('AGENT_API_USAGE_JOURNAL_CORRUPT', 'duplicate task start');
+      }
+      tasks.set(event.task_id, {
+        version: JOURNAL_VERSION,
+        task_id: event.task_id,
+        request_id: event.request_id,
+        session_id: event.session_id,
+        model: PUBLIC_MODEL_ID,
+        status: 'active',
+        started_at: event.at,
+        finished_at: null,
+        calls: [],
+        callIds: new Set(),
+      });
+      return;
+    }
+    const task = tasks.get(event.task_id);
+    if (task === undefined) {
+      throw journalError('AGENT_API_USAGE_JOURNAL_CORRUPT', 'event references unknown task');
+    }
+    if (event.type === 'model.usage') {
+      if (task.callIds.has(event.call_id)) return;
+      task.callIds.add(event.call_id);
+      task.calls.push({
+        call_id: event.call_id,
+        sequence: event.sequence,
+        recorded_at: event.at,
+        usage: event.usage,
+      });
+      return;
+    }
+    if (event.type === 'task.finished') {
+      task.status = event.status;
+      task.finished_at = event.at;
+      return;
+    }
+    throw journalError('AGENT_API_USAGE_JOURNAL_CORRUPT', 'unknown usage journal event');
+  }
+
+  function load() {
+    if (filePath === null || !fs.existsSync(filePath)) return;
+    const content = fs.readFileSync(filePath, 'utf8');
+    for (const line of content.split(/\r?\n/u)) {
+      if (line.length === 0) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        throw journalError('AGENT_API_USAGE_JOURNAL_CORRUPT', 'invalid JSONL record');
+      }
+      replay(event);
+    }
+  }
+
+  function startTask(input) {
+    const taskId = requireId(input.taskId, 'taskId');
+    const requestId = requireId(input.requestId, 'requestId');
+    const sessionId = requireId(input.sessionId, 'sessionId');
+    if (tasks.has(taskId)) {
+      throw journalError('AGENT_API_USAGE_TASK_EXISTS', 'usage task already exists');
+    }
+    const event = {
+      version: JOURNAL_VERSION,
+      type: 'task.started',
+      task_id: taskId,
+      request_id: requestId,
+      session_id: sessionId,
+      at: normalizeTimestamp(input.at ?? now(), 'task start time'),
+    };
+    appendEvent(event);
+    replay(event);
+    return taskId;
+  }
+
+  function recordModelCall(input) {
+    const task = taskForScope(input);
+    if (task.status !== 'active') {
+      throw journalError('AGENT_API_USAGE_TASK_CLOSED', 'usage task is already closed');
+    }
+    const callId = requireId(input.callId, 'callId');
+    if (task.callIds.has(callId)) return false;
+    const event = {
+      version: JOURNAL_VERSION,
+      type: 'model.usage',
+      task_id: task.task_id,
+      call_id: callId,
+      sequence: task.calls.length + 1,
+      usage: normalizeRawUsage(input.usage),
+      at: normalizeTimestamp(input.at ?? now(), 'model call time'),
+    };
+    appendEvent(event);
+    replay(event);
+    return true;
+  }
+
+  function finishTask(input) {
+    const task = taskForScope(input);
+    const status = requireId(input.status, 'status');
+    if (!['completed', 'cancelled', 'failed'].includes(status)) {
+      throw journalError('AGENT_API_USAGE_INVALID_STATUS', 'invalid usage task status');
+    }
+    if (task.status !== 'active') return false;
+    const event = {
+      version: JOURNAL_VERSION,
+      type: 'task.finished',
+      task_id: task.task_id,
+      status,
+      at: normalizeTimestamp(input.at ?? now(), 'task finish time'),
+    };
+    appendEvent(event);
+    replay(event);
+    return true;
+  }
+
+  function getTask(taskId) {
+    const task = tasks.get(requireId(taskId, 'taskId'));
+    if (task === undefined) return null;
+    const { callIds: _callIds, ...snapshot } = task;
+    return clone(snapshot);
+  }
+
+  load();
+  return Object.freeze({ finishTask, getTask, recordModelCall, startTask });
+}
+
+module.exports = {
+  AgentApiUsageJournalError,
+  JOURNAL_VERSION,
+  createAgentApiTaskId,
+  createAgentApiUsageJournal,
+  normalizeRawUsage,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blun-king-cli",
-  "version": "9.1.465",
+  "version": "9.1.466",
   "description": "BLUN CLI - your own AI agent with a Telegram channel. Get it done. With BLUN.",
   "license": "MIT",
   "bin": {