blun-king-cli 9.1.587 → 9.1.588

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

@@ -1,461 +0,0 @@
-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';
-
-class AgentApiTurnControllerError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = 'AgentApiTurnControllerError';
-    this.code = code;
-  }
-}
-
-function controllerError(code, message) {
-  return new AgentApiTurnControllerError(code, message);
-}
-
-function requireId(value, label) {
-  if (typeof value !== 'string' || value.trim().length === 0) {
-    throw controllerError('AGENT_API_INVALID_SCOPE', `${label} must be a non-empty string`);
-  }
-  return value.trim();
-}
-
-function validateSession(session) {
-  if (session === null || typeof session !== 'object') {
-    throw controllerError('AGENT_API_INVALID_SESSION', 'session must be an SDK session');
-  }
-  for (const method of ['onEvent', 'cancel']) {
-    if (typeof session[method] !== 'function') {
-      throw controllerError(
-        'AGENT_API_INVALID_SESSION',
-        `session.${method} must be a function`,
-      );
-    }
-  }
-  if (typeof session.promptAccepted !== 'function' && typeof session.prompt !== 'function') {
-    throw controllerError(
-      'AGENT_API_INVALID_SESSION',
-      'session.promptAccepted or session.prompt must be a function',
-    );
-  }
-  return requireId(session.id, 'session.id');
-}
-
-function createDeferred() {
-  let resolve;
-  let reject;
-  const promise = new Promise((resolvePromise, rejectPromise) => {
-    resolve = resolvePromise;
-    reject = rejectPromise;
-  });
-  return { promise, reject, resolve };
-}
-
-function isMainAgentEvent(event) {
-  return event.agentId === undefined || event.agentId === MAIN_AGENT_ID;
-}
-
-function normalizeToolResults(value) {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw controllerError(
-      'AGENT_API_INVALID_TOOL_RESULTS',
-      'toolResults must be a non-empty array',
-    );
-  }
-  return value.map((result, index) => {
-    if (result === null || typeof result !== 'object' || Array.isArray(result)) {
-      throw controllerError(
-        'AGENT_API_INVALID_TOOL_RESULT',
-        `toolResults[${index}] must be an object`,
-      );
-    }
-    const toolCallId = requireId(result.tool_call_id, `toolResults[${index}].tool_call_id`);
-    if (typeof result.output !== 'string') {
-      throw controllerError(
-        'AGENT_API_INVALID_TOOL_RESULT',
-        `toolResults[${index}].output must be a string`,
-      );
-    }
-    if (result.is_error !== undefined && typeof result.is_error !== 'boolean') {
-      throw controllerError(
-        'AGENT_API_INVALID_TOOL_RESULT',
-        `toolResults[${index}].is_error must be a boolean`,
-      );
-    }
-    return {
-      toolCallId,
-      output: result.output,
-      isError: result.is_error === true,
-    };
-  });
-}
-
-function serializeToolArgs(args) {
-  try {
-    return JSON.stringify(args ?? {});
-  } catch {
-    throw controllerError(
-      'AGENT_API_INVALID_TOOL_ARGS',
-      'client tool arguments must be JSON-serializable',
-    );
-  }
-}
-
-function openAiEnvelope(turn, message, finishReason) {
-  return {
-    id: `agent-${turn.requestId}`,
-    object: 'chat.completion',
-    created: turn.created,
-    model: turn.publicModel,
-    choices: [{
-      index: 0,
-      message,
-      finish_reason: finishReason,
-    }],
-    blun: {
-      mode: 'agent',
-      task_id: turn.taskId,
-      session_id: turn.publicSessionId,
-      request_id: turn.requestId,
-    },
-  };
-}
-
-function toolCallResponse(turn, event) {
-  const content = turn.assistantText.length > 0 ? turn.assistantText : null;
-  turn.assistantText = '';
-  return openAiEnvelope(turn, {
-    role: 'assistant',
-    content,
-    tool_calls: [{
-      id: event.toolCallId,
-      type: 'function',
-      function: {
-        name: event.toolName,
-        arguments: serializeToolArgs(event.args),
-      },
-    }],
-  }, 'tool_calls');
-}
-
-function completedResponse(turn, event) {
-  const reason = event.reason === 'completed' ? 'stop' : event.reason;
-  return openAiEnvelope(turn, {
-    role: 'assistant',
-    content: turn.assistantText,
-  }, reason);
-}
-
-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();
-
-  function turnForScope(input) {
-    const sessionId = requireId(input.sessionId, 'sessionId');
-    const requestId = requireId(input.requestId, 'requestId');
-    const turn = activeTurns.get(sessionId);
-    if (turn === undefined) {
-      throw controllerError(
-        'AGENT_API_TURN_NOT_ACTIVE',
-        'no active Agent API turn for session',
-      );
-    }
-    if (turn.requestId !== requestId) {
-      throw controllerError(
-        'AGENT_API_TURN_SCOPE_MISMATCH',
-        'request does not own the active Agent API turn',
-      );
-    }
-    return turn;
-  }
-
-  async function closeBinding(turn, kind, reason, status = 'failed') {
-    if (turn.closed) return;
-    turn.closed = true;
-    activeTurns.delete(turn.sessionId);
-    turn.unsubscribe?.();
-    turn.unsubscribe = undefined;
-
-    if (kind === 'finish') {
-      try {
-        await turn.binding.finish();
-        usageJournal.finishTask({
-          taskId: turn.taskId,
-          requestId: turn.requestId,
-          sessionId: turn.sessionId,
-          status,
-        });
-        return;
-      } catch (error) {
-        try {
-          await turn.binding.abort(reason ?? 'Agent API turn cleanup failed');
-        } 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;
-      }
-    }
-    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) {
-    if (turn.terminalSettled) return;
-    turn.terminalSettled = true;
-    turn.terminal.resolve(event);
-  }
-
-  function installEventListener(turn) {
-    return turn.session.onEvent((event) => {
-      if (!isMainAgentEvent(event)) return;
-      if (event.type === 'turn.started') {
-        if (turn.turnId === undefined) turn.turnId = event.turnId;
-        return;
-      }
-      if (event.type === 'error') {
-        if (turn.turnId !== undefined && event.turnId !== undefined
-          && event.turnId !== turn.turnId) return;
-        settleTerminal(turn, {
-          type: 'turn.error',
-          reason: 'failed',
-          error: controllerError(
-            event.code ?? 'AGENT_API_TURN_FAILED',
-            event.message ?? 'Agent API turn failed',
-          ),
-        });
-        return;
-      }
-      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;
-        case 'assistant.delta':
-          turn.assistantText += event.delta;
-          return;
-        case 'turn.ended':
-          settleTerminal(turn, event);
-          return;
-        default:
-      }
-    });
-  }
-
-  async function waitForOutput(turn) {
-    if (turn.closed) {
-      throw controllerError('AGENT_API_TURN_NOT_ACTIVE', 'Agent API turn is closed');
-    }
-
-    const tool = turn.binding.nextToolCall().then(
-      (event) => ({ kind: 'tool', event }),
-      (error) => ({ kind: 'tool_error', error }),
-    );
-    const terminal = turn.terminal.promise.then((event) => ({ kind: 'terminal', event }));
-    const outcome = await Promise.race([tool, terminal]);
-
-    if (outcome.kind === 'tool') return toolCallResponse(turn, outcome.event);
-    if (outcome.kind === 'tool_error') {
-      if (turn.closed) {
-        throw controllerError('AGENT_API_TURN_NOT_ACTIVE', 'Agent API turn is closed');
-      }
-      await closeBinding(turn, 'abort', 'Agent API tool bridge failed');
-      throw outcome.error;
-    }
-
-    if (outcome.event.type === 'turn.error') {
-      await closeBinding(turn, 'abort', 'Agent API turn failed');
-      throw outcome.event.error;
-    }
-    if (outcome.event.reason === 'failed') {
-      await closeBinding(turn, 'abort', 'Agent API turn failed');
-      throw controllerError('AGENT_API_TURN_FAILED', 'Agent API turn failed');
-    }
-
-    const response = completedResponse(turn, outcome.event);
-    await closeBinding(turn, 'finish', undefined, 'completed');
-    return response;
-  }
-
-  async function startTurn(input) {
-    if (input === null || typeof input !== 'object') {
-      throw controllerError('AGENT_API_INVALID_REQUEST', 'turn input must be an object');
-    }
-    const sessionId = validateSession(input.session);
-    const publicSessionId = input.publicSessionId === undefined
-      ? sessionId
-      : requireId(input.publicSessionId, 'publicSessionId');
-    const requestId = requireId(input.requestId, 'requestId');
-    if (activeTurns.has(sessionId)) {
-      throw controllerError(
-        'AGENT_API_SESSION_BUSY',
-        'session already has an active Agent API turn',
-      );
-    }
-    if (input.prompt === undefined || input.prompt === null) {
-      throw controllerError('AGENT_API_INVALID_PROMPT', 'prompt is required');
-    }
-
-    const binding = await runtime.bindClientTools({
-      session: input.session,
-      requestId,
-      tools: input.tools ?? [],
-    });
-    const taskId = requireId(taskIdFactory(sessionId, requestId), 'taskId');
-    const turn = {
-      assistantText: '',
-      binding,
-      closed: false,
-      created: Math.floor(Number(now()) / 1000),
-      publicModel,
-      publicSessionId,
-      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);
-
-    try {
-      if (typeof input.session.promptAccepted === 'function') {
-        const accepted = await input.session.promptAccepted(input.prompt);
-        if (accepted?.accepted === false || accepted?.buffered === true) {
-          await closeBinding(turn, 'abort', 'Agent API session is busy');
-          throw controllerError(
-            'AGENT_API_SESSION_BUSY',
-            'Agent API prompt was not accepted as a new active turn',
-          );
-        }
-        if (Number.isSafeInteger(accepted?.turnId)) {
-          if (turn.turnId !== undefined && turn.turnId !== accepted.turnId) {
-            await closeBinding(turn, 'abort', 'Agent API turn identity mismatch');
-            throw controllerError(
-              'AGENT_API_TURN_ID_MISMATCH',
-              'accepted turn ID does not match the emitted turn',
-            );
-          }
-          turn.turnId = accepted.turnId;
-        }
-      } else {
-        await input.session.prompt(input.prompt);
-      }
-    } catch (error) {
-      if (!turn.closed) await closeBinding(turn, 'abort', 'Agent API prompt failed');
-      throw error;
-    }
-
-    return waitForOutput(turn);
-  }
-
-  async function continueTurn(input) {
-    if (input === null || typeof input !== 'object') {
-      throw controllerError('AGENT_API_INVALID_REQUEST', 'continuation input must be an object');
-    }
-    const turn = turnForScope(input);
-    for (const result of normalizeToolResults(input.toolResults)) {
-      turn.binding.submitToolResult(result);
-    }
-    return waitForOutput(turn);
-  }
-
-  async function cancelTurn(input) {
-    if (input === null || typeof input !== 'object') {
-      throw controllerError('AGENT_API_INVALID_REQUEST', 'cancel input must be an object');
-    }
-    const turn = turnForScope(input);
-    const reason = typeof input.reason === 'string' && input.reason.trim().length > 0
-      ? input.reason.trim()
-      : 'Agent API turn cancelled';
-    const outcomes = await Promise.allSettled([
-      turn.session.cancel(),
-      closeBinding(turn, 'abort', reason, 'cancelled'),
-    ]);
-    const failure = outcomes.find((outcome) => outcome.status === 'rejected');
-    if (failure !== undefined) throw failure.reason;
-    return true;
-  }
-
-  return Object.freeze({
-    activeTurnCount: () => activeTurns.size,
-    cancelTurn,
-    continueTurn,
-    getUsageTask: (taskId) => usageJournal.getTask(taskId),
-    startTurn,
-  });
-}
-
-export {
-  AgentApiTurnControllerError,
-  PUBLIC_MODEL_ID,
-  createAgentApiTurnController,
-};

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

@@ -1,259 +0,0 @@
-'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,
-};