@bliggy/chat-runtime 0.3.0 → 0.3.1

package/README.md

@@ -9,10 +9,11 @@ The package also retains the channel orchestration API from
 npm install @bliggy/chat-runtime
 ```
 
-There are two entry points for different application flows:
+There are two application flows:
 
-- `runConversation` runs a bounded streaming conversation and tool loop. It
-  delegates every tool call to the host's authorization/execution callback.
+- `runConversation` runs a bounded conversation and tool loop; `streamConversation`
+  exposes that same loop as an async iterator. Both delegate tool calls to the
+  host's authorization/execution callback.
 - `ChannelRuntime` authenticates channel messages, claims durable turns, checks
   action policy and handles confirmation of pending turns. Its host supplies
   planning, execution and storage callbacks.
@@ -72,6 +73,38 @@ may return `forceText: true` to make the next request text-only. Execution error
 must be converted by the host to safe `{ output, isError: true }` results when
 the conversation should continue; uncaught errors stop the loop and are not retried.
 
+When the host authorizes or queues a whole proposal together, supply
+`executeTools(toolCalls, state)` instead of `executeTool`. The callbacks are
+mutually exclusive. The batch callback runs once per completed assistant response
+and returns one `{ output, isError?, forceText? }` outcome per call, in the original
+order. The loop appends one user message containing all tool results, then calls
+the provider again. `onToolResult(message, state)` receives that combined message
+once, with `state.toolCalls` and `state.outcomes`. An omitted `isError` remains
+omitted on this batch path. The host owns batch authorization, transaction scope,
+durable claims and confirmation; this callback does not make a batch atomic.
+
+For async-iterator consumers, pass the same options to `streamConversation`:
+
+```js
+const { streamConversation } = require('@bliggy/chat-runtime');
+
+for await (const event of streamConversation(options)) {
+  if (event.type === 'done') handleOutcome(event.result);
+  else sendToBrowser(event);
+}
+```
+
+The iterator yields normalized provider events and application events sent with
+`await state.emit(event)`, followed by one `{ type: 'done', result: outcome }`.
+It starts when first consumed, and waits for the consumer to advance after each
+event. An interrupted provider stream throws without a successful `done` event.
+Both APIs accept an optional `AbortSignal` as `signal`. Closing or throwing into
+the iterator also cancels immediately, including while `next()` is pending.
+Cancellation prevents later model calls, tool callbacks and persistence callbacks;
+it cannot undo an already-started host action or abort an in-flight provider
+request. Host callbacks that emit progress should await `state.emit` before
+starting their next action.
+
 Opaque reasoning and assistant phase survive in-memory tool continuation.
 `onAssistantMessage` receives content without reasoning/thinking blocks. The
 response state and returned `messages` still contain the full provider context:

package/index.js

@@ -13,7 +13,7 @@ const {
 const { MemoryTurnStore } = require('./src/memoryTurnStore');
 const { createChatAdapter, createEmailAdapter } = require('./src/channels');
 const { createTwilioChannels } = require('./src/twilio');
-const { runConversation } = require('./src/conversation');
+const { runConversation, streamConversation } = require('./src/conversation');
 const { selectPendingActions } = require('./src/pendingActions');
 
 module.exports = {
@@ -30,5 +30,6 @@ module.exports = {
   createEmailAdapter,
   createTwilioChannels,
   runConversation,
+  streamConversation,
   selectPendingActions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bliggy/chat-runtime",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared chat conversations, tool execution, and action confirmations powered by @bliggy/llm-client",
   "repository": {
     "type": "git",

package/src/conversation.js

@@ -17,9 +17,36 @@ function responseStateError(code, message, stopReason) {
   return error;
 }
 
-async function consumeTurn(streamTurn, request, onEvent) {
+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;
@@ -27,6 +54,7 @@ async function consumeTurn(streamTurn, request, onEvent) {
       await onEvent(event);
     }
   }
+  assertActive(signal);
   if (!result) throw new Error('Chat stream ended without a final result.');
   return result;
 }
@@ -43,7 +71,9 @@ async function runConversation({
   beforeResponse = () => null,
   onAssistantMessage = () => {},
   executeTool = null,
-  onToolResult = () => {}
+  executeTools = null,
+  onToolResult = () => {},
+  signal = null
 } = {}) {
   if (!Array.isArray(initialMessages) || initialMessages.length === 0) {
     throw new TypeError('messages must be a non-empty array.');
@@ -57,26 +87,36 @@ async function runConversation({
   })) {
     if (typeof callback !== 'function') throw new TypeError(`${name} must be a function.`);
   }
-  for (const [name, callback] of Object.entries({ getSystem, executeTool })) {
+  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 };
+    const state = { iteration, textOnly, messages, emit };
     const request = {
       ...requestOptions,
       system: getSystem ? await getSystem(state) : requestOptions.system,
-      messages,
+      messages: [...messages],
       tools,
       toolChoice: textOnly ? 'none' : 'auto',
       parallelToolCalls: false
     };
-    result = await trackTurn(() => consumeTurn(streamTurn, request, onEvent), state);
+    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.');
     }
@@ -108,6 +148,7 @@ async function runConversation({
     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.');
@@ -115,34 +156,49 @@ async function runConversation({
       messages.push(assistantMessage, ...policy.retryMessages);
       continue;
     }
-    if (toolCalls.length && !executeTool) throw new TypeError('executeTool is required for tool calls.');
+    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);
-      if (!outcome || outcome.output === undefined) {
-        throw new TypeError('executeTool must return an outcome with output.');
-      }
+      assertActive(signal);
       const message = {
         role: 'user',
-        content: [{
-          type: 'tool_result',
-          toolCallId: toolCall.id,
-          output: outcome.output,
-          isError: Boolean(outcome.isError)
-        }]
+        content: [toolResultBlock(toolCall, outcome, 'executeTool')]
       };
       await onToolResult(message, { ...responseState, toolCall, outcome });
+      assertActive(signal);
       messages.push(message);
       forceText ||= Boolean(outcome.forceText);
     }
@@ -151,4 +207,88 @@ async function runConversation({
   return { status: 'limit', result, messages, iterations: maxIterations };
 }
 
-module.exports = { runConversation };
+// 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 };