blun-king-cli 9.1.464 → 9.1.465

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

@@ -0,0 +1,384 @@
+import { createAgentApiRuntime } from './agent-api-runtime.mjs';
+
+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',
+      session_id: turn.sessionId,
+      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 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) {
+    if (turn.closed) return;
+    turn.closed = true;
+    activeTurns.delete(turn.sessionId);
+    turn.unsubscribe?.();
+    turn.unsubscribe = undefined;
+
+    if (kind === 'finish') {
+      try {
+        await turn.binding.finish();
+        return;
+      } catch (error) {
+        try {
+          await turn.binding.abort(reason ?? 'Agent API turn cleanup failed');
+        } catch {
+          // Preserve the original finish error.
+        }
+        throw error;
+      }
+    }
+    await turn.binding.abort(reason ?? 'Agent API turn aborted');
+  }
+
+  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.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');
+    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 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 turn = {
+      assistantText: '',
+      binding,
+      closed: false,
+      created: Math.floor(Number(now()) / 1000),
+      publicModel,
+      requestId,
+      session: input.session,
+      sessionId,
+      terminal: createDeferred(),
+      terminalSettled: false,
+      turnId: undefined,
+      unsubscribe: undefined,
+    };
+    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),
+    ]);
+    const failure = outcomes.find((outcome) => outcome.status === 'rejected');
+    if (failure !== undefined) throw failure.reason;
+    return true;
+  }
+
+  return Object.freeze({
+    activeTurnCount: () => activeTurns.size,
+    cancelTurn,
+    continueTurn,
+    startTurn,
+  });
+}
+
+export {
+  AgentApiTurnControllerError,
+  PUBLIC_MODEL_ID,
+  createAgentApiTurnController,
+};

package/package.json

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