@bliggy/chat-runtime 0.0.0-stage → 0.3.1

package/src/conversation.js

@@ -0,0 +1,294 @@
+'use strict';
+
+// The model client owns wire formats, retries and streaming. This module owns
+// only the bounded conversation loop; applications still authorize tools and
+// persist their messages, actions and receipts.
+function defaultStreamTurn(options) {
+  return require('@bliggy/llm-client').streamChatTurn(options);
+}
+
+const PRIVATE_BLOCK_TYPES = new Set(['reasoning', 'thinking', 'redacted_thinking']);
+const COMPLETED_STOP_REASONS = new Set(['end_turn', 'stop_sequence', 'refusal']);
+
+function responseStateError(code, message, stopReason) {
+  const error = new Error(message);
+  error.code = code;
+  error.stopReason = stopReason ?? null;
+  return error;
+}
+
+function cancellationError() {
+  const error = new Error('Conversation cancelled.');
+  error.name = 'AbortError';
+  error.code = 'CHAT_CONVERSATION_CANCELLED';
+  return error;
+}
+
+function assertActive(signal) {
+  if (signal?.aborted) throw cancellationError();
+}
+
+function toolResultBlock(toolCall, outcome, executor) {
+  if (!outcome || outcome.output === undefined) {
+    throw new TypeError(`${executor} must return an outcome with output.`);
+  }
+  return {
+    type: 'tool_result',
+    toolCallId: toolCall.id,
+    output: outcome.output,
+    ...(outcome.isError !== undefined || executor === 'executeTool'
+      ? { isError: Boolean(outcome.isError) }
+      : {})
+  };
+}
+
+async function consumeTurn(streamTurn, request, onEvent, signal) {
+  assertActive(signal);
+  let result = null;
+  for await (const event of streamTurn(request)) {
+    assertActive(signal);
+    if (event.type === 'done') {
+      if (result) throw new Error('Chat stream returned more than one final result.');
+      result = event.result;
+    } else {
+      await onEvent(event);
+    }
+  }
+  assertActive(signal);
+  if (!result) throw new Error('Chat stream ended without a final result.');
+  return result;
+}
+
+async function runConversation({
+  messages: initialMessages,
+  tools = [],
+  maxIterations = 12,
+  requestOptions = {},
+  streamTurn = defaultStreamTurn,
+  getSystem = null,
+  onEvent = () => {},
+  trackTurn = (run) => run(),
+  beforeResponse = () => null,
+  onAssistantMessage = () => {},
+  executeTool = null,
+  executeTools = null,
+  onToolResult = () => {},
+  signal = null
+} = {}) {
+  if (!Array.isArray(initialMessages) || initialMessages.length === 0) {
+    throw new TypeError('messages must be a non-empty array.');
+  }
+  if (!Array.isArray(tools)) throw new TypeError('tools must be an array.');
+  if (!Number.isInteger(maxIterations) || maxIterations < 1) {
+    throw new TypeError('maxIterations must be a positive integer.');
+  }
+  for (const [name, callback] of Object.entries({
+    streamTurn, onEvent, trackTurn, beforeResponse, onAssistantMessage, onToolResult
+  })) {
+    if (typeof callback !== 'function') throw new TypeError(`${name} must be a function.`);
+  }
+  for (const [name, callback] of Object.entries({ getSystem, executeTool, executeTools })) {
+    if (callback !== null && typeof callback !== 'function') throw new TypeError(`${name} must be a function.`);
+  }
+  if (executeTool && executeTools) throw new TypeError('executeTool and executeTools are mutually exclusive.');
+
+  const emit = async (event) => {
+    assertActive(signal);
+    await onEvent(event);
+    assertActive(signal);
+  };
+
+  const messages = [...initialMessages];
+  let forceText = false;
+  let result = null;
+
+  for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+    assertActive(signal);
+    const textOnly = forceText || iteration === maxIterations || tools.length === 0;
+    const state = { iteration, textOnly, messages, emit };
+    const request = {
+      ...requestOptions,
+      system: getSystem ? await getSystem(state) : requestOptions.system,
+      messages: [...messages],
+      tools,
+      toolChoice: textOnly ? 'none' : 'auto',
+      parallelToolCalls: false
+    };
+    assertActive(signal);
+    result = await trackTurn(() => consumeTurn(streamTurn, request, emit, signal), state);
+    assertActive(signal);
+    if (!result || result.message?.role !== 'assistant' || !Array.isArray(result.message.content)) {
+      throw new TypeError('Chat result must contain a normalized assistant message.');
+    }
+    const finish = (status) => ({ status, result, messages, iterations: iteration });
+    // An output limit may leave a partial tool call. Let the host render its
+    // own notice without persisting or executing that incomplete response.
+    if (result.stopReason === 'max_tokens') return finish('max_tokens');
+    if (result.toolError) throw result.toolError;
+
+    const assistantMessage = result.message;
+    const toolCalls = assistantMessage.content.filter(block => block.type === 'tool_call');
+    if (result.stopReason !== 'tool_call' && !COMPLETED_STOP_REASONS.has(result.stopReason)) {
+      throw responseStateError(
+        'CHAT_RESPONSE_NOT_COMPLETE',
+        'Chat response did not reach a supported completion state.',
+        result.stopReason
+      );
+    }
+    if ((result.stopReason === 'tool_call') !== (toolCalls.length > 0)) {
+      throw responseStateError(
+        'INVALID_CHAT_TOOL_STATE',
+        'Chat response stop reason does not match its tool calls.',
+        result.stopReason
+      );
+    }
+    const responseState = { ...state, result, assistantMessage, toolCalls };
+    // The final request is text only. A provider disregarding that request must
+    // never cause one more action after the host's execution budget is spent.
+    if (textOnly && toolCalls.length) return finish('limit');
+
+    const policy = await beforeResponse(responseState);
+    assertActive(signal);
+    if (policy?.retryMessages !== undefined) {
+      if (!Array.isArray(policy.retryMessages) || policy.retryMessages.length === 0) {
+        throw new TypeError('beforeResponse.retryMessages must be a non-empty array.');
+      }
+      messages.push(assistantMessage, ...policy.retryMessages);
+      continue;
+    }
+    if (toolCalls.length && !executeTool && !executeTools) {
+      throw new TypeError('executeTool or executeTools is required for tool calls.');
+    }
+
+    const persistedMessage = {
+      ...assistantMessage,
+      content: assistantMessage.content.filter(block => !PRIVATE_BLOCK_TYPES.has(block.type))
+    };
+    await onAssistantMessage(persistedMessage, responseState);
+    assertActive(signal);
+    // Keep the complete response, including opaque provider reasoning, in the
+    // in-memory replay. Only the persistence callback receives filtered content.
+    messages.push(assistantMessage);
+    if (toolCalls.length === 0) return finish('completed');
+
+    forceText = false;
+    if (executeTools) {
+      const outcomes = await executeTools(toolCalls, responseState);
+      assertActive(signal);
+      if (!Array.isArray(outcomes) || outcomes.length !== toolCalls.length) {
+        throw new TypeError('executeTools must return one outcome per tool in the original order.');
+      }
+      const message = {
+        role: 'user',
+        content: toolCalls.map((toolCall, index) => toolResultBlock(toolCall, outcomes[index], 'executeTools'))
+      };
+      await onToolResult(message, { ...responseState, outcomes });
+      assertActive(signal);
+      messages.push(message);
+      forceText = outcomes.some(outcome => Boolean(outcome.forceText));
+      continue;
+    }
+
+    for (const toolCall of toolCalls) {
+      assertActive(signal);
+      const outcome = await executeTool(toolCall, responseState);
+      assertActive(signal);
+      const message = {
+        role: 'user',
+        content: [toolResultBlock(toolCall, outcome, 'executeTool')]
+      };
+      await onToolResult(message, { ...responseState, toolCall, outcome });
+      assertActive(signal);
+      messages.push(message);
+      forceText ||= Boolean(outcome.forceText);
+    }
+  }
+
+  return { status: 'limit', result, messages, iterations: maxIterations };
+}
+
+// One engine, two consumption styles. Each emitted event waits until the caller
+// advances the iterator, so returning at a text/tool event cannot leave the loop
+// running ahead into later actions. A host action already started is not undone.
+async function* conversationEvents(options, controller) {
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, controller.signal])
+    : controller.signal;
+  assertActive(signal);
+  const queue = [];
+  const pending = new Set();
+  let wake = null;
+  let closed = false;
+
+  function deliver(item) {
+    if (closed) return;
+    queue.push(item);
+    if (wake) {
+      const resume = wake;
+      wake = null;
+      resume();
+    }
+  }
+
+  function abort() {
+    const error = cancellationError();
+    for (const acknowledgment of pending) acknowledgment.reject(error);
+    pending.clear();
+    queue.length = 0;
+    deliver({ error });
+  }
+  signal.addEventListener('abort', abort, { once: true });
+
+  const onEvent = async (event) => {
+    await options.onEvent?.(event);
+    assertActive(signal);
+    await new Promise((resolve, reject) => {
+      const acknowledgment = { resolve, reject };
+      pending.add(acknowledgment);
+      deliver({ event, acknowledgment });
+    });
+  };
+  // Both handlers consume settlement, including after a caller closes the
+  // iterator while a provider or host callback is still finishing.
+  runConversation({ ...options, signal, onEvent }).then(
+    result => deliver({ event: { type: 'done', result }, final: true }),
+    error => deliver({ error })
+  );
+
+  try {
+    while (true) {
+      if (queue.length === 0) await new Promise(resolve => { wake = resolve; });
+      const item = queue.shift();
+      if (item.error) throw item.error;
+      yield item.event;
+      if (item.acknowledgment) {
+        pending.delete(item.acknowledgment);
+        item.acknowledgment.resolve();
+      }
+      if (item.final) return;
+    }
+  } finally {
+    closed = true;
+    controller.abort();
+    signal.removeEventListener('abort', abort);
+    queue.length = 0;
+  }
+}
+
+function streamConversation(options = {}) {
+  const controller = new AbortController();
+  const iterator = conversationEvents(options, controller);
+  // Native async-generator return/throw waits behind a pending next(). Signal
+  // cancellation immediately so an in-flight response cannot start a tool while
+  // the caller is waiting for that queued return to reach the generator.
+  for (const method of ['return', 'throw']) {
+    const close = iterator[method].bind(iterator);
+    iterator[method] = (...args) => {
+      controller.abort();
+      return close(...args);
+    };
+  }
+  return iterator;
+}
+
+module.exports = { runConversation, streamConversation };

package/src/memoryTurnStore.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const crypto = require('crypto');
+const { isDeepStrictEqual } = require('node:util');
+const { TURN_TRANSITIONS } = require('./runtime');
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+class MemoryTurnStore {
+  constructor({ now = () => new Date() } = {}) {
+    this.now = now;
+    this.turns = new Map();
+    this.sourceIndex = new Map();
+  }
+
+  async claim(attributes) {
+    const sourceIdentity = [attributes.tenantKey, attributes.channel, attributes.sourceKey].join(':');
+    const existingId = this.sourceIndex.get(sourceIdentity);
+    if (existingId) return { turn: clone(this.turns.get(existingId)), created: false };
+
+    const timestamp = this.now().toISOString();
+    const turn = {
+      id: crypto.randomUUID(),
+      ...clone(attributes),
+      status: 'received',
+      createdAt: timestamp,
+      updatedAt: timestamp
+    };
+    this.turns.set(turn.id, turn);
+    this.sourceIndex.set(sourceIdentity, turn.id);
+    return { turn: clone(turn), created: true };
+  }
+
+  async transition(turn, status, updates = {}) {
+    const current = this.turns.get(turn.id);
+    if (!current) throw new Error(`Unknown turn: ${turn.id}`);
+    if (!TURN_TRANSITIONS[current.status]?.includes(status)) {
+      throw new Error(`Invalid turn transition: ${current.status} -> ${status}`);
+    }
+
+    const updated = {
+      ...current,
+      ...clone(updates),
+      status,
+      updatedAt: this.now().toISOString()
+    };
+    this.turns.set(updated.id, updated);
+    return clone(updated);
+  }
+
+  async getPending({ tenantKey, actorKey, channel, threadKey }) {
+    const candidates = [...this.turns.values()]
+      .filter(turn => (
+        turn.tenantKey === tenantKey &&
+        turn.actorKey === actorKey &&
+        turn.channel === channel &&
+        turn.threadKey === threadKey &&
+        turn.status === 'awaiting_confirmation'
+      ))
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    let pending = null;
+    for (const candidate of candidates) {
+      if (candidate.expiresAt && new Date(candidate.expiresAt) <= this.now()) {
+        await this.transition(candidate, 'expired');
+      } else {
+        pending = candidate;
+        break;
+      }
+    }
+    return pending ? clone(pending) : null;
+  }
+
+  async claimPending({ tenantKey, actorKey, channel, threadKey, turnId, pendingActions }) {
+    const pending = this.turns.get(turnId);
+    if (!pending || pending.tenantKey !== tenantKey || pending.actorKey !== actorKey ||
+        pending.channel !== channel || pending.threadKey !== threadKey ||
+        pending.status !== 'awaiting_confirmation' ||
+        !(new Date(pending.expiresAt) > this.now()) ||
+        !isDeepStrictEqual(pending.pendingActions, pendingActions)) return null;
+    return await this.transition(pending, 'executing');
+  }
+
+  async get(id) {
+    const turn = this.turns.get(id);
+    return turn ? clone(turn) : null;
+  }
+
+  async list() {
+    return [...this.turns.values()].map(clone);
+  }
+}
+
+module.exports = { MemoryTurnStore };

package/src/pendingActions.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// Select from an already authorized queue without executing or changing it.
+// Callers own confirmation interpretation, atomic claiming, authorization at
+// execution time, and receipts. A warning requires explicit approval; a general
+// confirmation cannot override it. Existing ids and action objects are retained.
+function selectPendingActions(actions, { decision, actionId = null } = {}) {
+  if (!Array.isArray(actions)) throw new TypeError('actions must be an array');
+  const unchanged = reason => ({ selected: [], remaining: [...actions], reason });
+  if (actions.length === 0) return unchanged('empty');
+  if (!['confirm', 'confirm_including_flagged', 'cancel'].includes(decision)) {
+    return unchanged('unconfirmed');
+  }
+
+  if (actionId !== null && actionId !== undefined) {
+    const index = actions.findIndex(action => String(action.id) === String(actionId));
+    if (index === -1) return unchanged('not_found');
+    return {
+      selected: [actions[index]],
+      remaining: actions.filter((_, actionIndex) => actionIndex !== index),
+      reason: null
+    };
+  }
+
+  if (decision === 'cancel' || decision === 'confirm_including_flagged') {
+    return { selected: [...actions], remaining: [], reason: null };
+  }
+
+  const selected = [];
+  const remaining = [];
+  for (const action of actions) {
+    (action.warning ? remaining : selected).push(action);
+  }
+  return { selected, remaining, reason: selected.length === 0 ? 'all_flagged' : null };
+}
+
+module.exports = { selectPendingActions };