@bliggy/chat-runtime 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,315 @@
-# Temporary Holding Version
+# Chat Runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@bliggy/chat-runtime` runs conversations and tools using `@bliggy/llm-client`.
+Applications supply their prompts, authorized tools, storage and business rules.
+The package also retains the channel orchestration API from
+`@davejohnson/agent-channel-runtime` for Chat, Email, Twilio SMS and turn-based Voice.
+
+```sh
+npm install @bliggy/chat-runtime
+```
+
+There are two application flows:
+
+- `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.
+
+`runConversation` does not implicitly create a `ChannelRuntime` or provide a
+database. Hosts can use their existing confirmation store or compose the two
+APIs. Model requests, transport retries and provider formats belong to
+`@bliggy/llm-client`; this package does not introduce another provider retry layer.
+
+## Streaming conversations
+
+```js
+const { runConversation } = require('@bliggy/chat-runtime');
+const { createOpenAIAdapter } = require('@bliggy/llm-client');
+
+const outcome = await runConversation({
+  messages: [{ role: 'user', content: [{ type: 'text', text: userText }] }],
+  tools: authorizedTools,
+  maxIterations: 16,
+  requestOptions: {
+    adapter: createOpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
+    provider: 'openai',
+    model: configuredModel,
+    maxOutputTokens: configuredOutputTokens,
+    promptCacheKey: conversationKey
+  },
+  getSystem: async () => buildCurrentSystemContext(),
+  onEvent: async event => sendToBrowser(event),
+  onAssistantMessage: async message => saveMessage(message),
+  executeTool: async toolCall => {
+    // Recheck current permissions and validate input here. Queue actions that
+    // need approval rather than executing them; return the actual outcome.
+    const result = await authorizeAndRunOrQueue(toolCall);
+    return { output: result, isError: false };
+  },
+  onToolResult: async message => saveMessage(message)
+});
+```
+
+The returned `status` is `completed`, `max_tokens`, or `limit`. Hosts render
+their own output-budget and iteration-limit notices. Errors propagate to the
+host. The final allowed request is text-only; a provider that disregards it
+cannot execute another tool.
+
+Completed replies must have `end_turn`, `stop_sequence`, or `refusal` as their
+normalized stop reason. A `tool_call` stop reason must have matching tool-call
+blocks; terminal text replies must not contain tool calls. Paused, failed,
+incomplete, missing or unknown stop reasons throw `CHAT_RESPONSE_NOT_COMPLETE`
+before response policy, persistence or tool execution. Contradictory tool state
+throws `INVALID_CHAT_TOOL_STATE`. Both errors include `stopReason`. The loop does
+not automatically resume provider-side paused work.
+
+The loop forwards stream events but persists and executes only after a complete
+final result and successful stream completion. Every tool call in that result
+gets a sequential execution callback and matching result message. A tool outcome
+may return `forceText: true` to make the next request text-only. Execution errors
+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:
+do not persist or expose those as a transcript. Hosts remain responsible for
+safe historical context, attachments, compaction and user-visible receipts.
+
+Additional hooks:
+
+- `streamTurn(request)` replaces the default `llm-client.streamChatTurn` boundary
+  when the application already wraps model configuration.
+- `trackTurn(run, state)` wraps consumption of one provider stream for usage
+  accounting. Call and return `run()` once; replaying it creates another request.
+- `getSystem(state)` refreshes context each iteration, including newly queued
+  actions. `state.iteration` starts at 1 and `state.textOnly` describes the request.
+- `beforeResponse(state)` can return `{ retryMessages: [...] }` to correct an
+  unpersisted response. The rejected response and correction remain in memory,
+  and the retry consumes the same bounded iteration budget. Otherwise return
+  `null` to persist and process the response.
+
+## Partial and flagged confirmations
+
+```js
+const { selectPendingActions } = require('@bliggy/chat-runtime');
+const { selected, remaining, reason } = selectPendingActions(pendingActions, {
+  decision: 'confirm',
+  actionId: requestedActionId // omit for a general confirmation
+});
+```
+
+This pure helper preserves action IDs, order and objects. General `confirm`
+selects actions without a truthy `warning`; flagged actions remain queued.
+An explicit individual ID can select a flagged action. `cancel` selects one
+action or the whole queue, including flagged actions. A host may use
+`confirm_including_flagged` only when it has independently established explicit
+approval of the warnings. Other decisions leave the queue unchanged.
+
+`reason` is `empty`, `not_found`, `all_flagged`, `unconfirmed`, or `null` for a
+successful selection. Selection is not authorization or an atomic claim. The
+host must claim the same persisted queue, recheck current permissions, retain
+unselected actions and record the actual results. Never accept a model-supplied
+decision as proof of user approval.
+
+## Upgrade from agent-channel-runtime
+
+The existing exports remain available under the new npm name. Upgrading from
+0.1.x also requires the 0.2 store contract below: add `getPending` and make
+`claimPending` match the exact turn ID and pending-action snapshot. A package-name
+replacement alone is not sufficient for a host using the older store contract.
+
+## Runtime flow
+
+1. Normalize the provider payload into an envelope.
+2. Authenticate the transport before resolving an actor.
+3. Resolve the tenant and actor through a host callback.
+4. Apply rate limits and idempotently claim the source message.
+5. Plan, authorize, and execute actions.
+6. Persist completion or hold risky actions for confirmation.
+7. Format the response for the originating channel.
+
+The runtime returns formatted responses; the host owns durable delivery. Twilio
+outbound SMS and call helpers are provided separately, so a webhook retry never
+silently sends an email or text twice.
+
+Turn statuses are:
+
+```text
+received -> authenticated -> processing -> completed
+                                      \-> awaiting_confirmation -> executing -> completed
+```
+
+## Host contracts
+
+Create `ChannelRuntime` with:
+
+- `adapters`: channel adapters created by this package or the host.
+- `turnStore`: `claim`, `transition`, `getPending`, and atomic `claimPending` methods.
+- `resolvePrincipal`: returns trusted `{ tenantKey, actorKey, principal }`.
+- `plan`: returns `{ content, summary, actions }`.
+- `authorize`: explicitly classifies actions into `approved`,
+  `requiresConfirmation`, and `rejected` arrays. Unclassified actions fail
+  closed.
+- `execute`: executes one action with the supplied idempotency key.
+- Optional `render`, `rateLimit`, `onSecurityEvent`, and `onError` callbacks.
+- Optional async `parseConfirmation(text, { pendingTurn, principal, envelope,
+  channel, context })`: returns `confirm`, `cancel`, `clarify`, or `null` (normal
+  planning). It runs only after transport authentication and principal resolution.
+  The default retains the legacy short commands; applications that support natural
+  conversation should supply their semantic interpreter. Never fabricate a new
+  message containing a command word. Unrecognized non-null results ask for
+  clarification without claiming the pending action.
+
+The default confirmation lifetime is 24 hours. `confirmationTtlMs`,
+`maxTextLength`, and `maxActions` are configurable constructor limits.
+
+`MemoryTurnStore` is suitable for tests. Production hosts should implement the
+same contract with durable storage and make `claimPending` an atomic row claim.
+`getPending(scope, metadata)` returns the current unexpired pending turn for the
+exact tenant, actor, channel and thread, without claiming it. The interpreter gets
+a copy of that snapshot. `claimPending({ ...scope, turnId, pendingActions }, metadata)`
+must atomically claim only that exact ID with the unchanged action set, still
+pending and unexpired. A different/newer turn must never be substituted. This
+two-phase store contract is required starting in 0.2.0; update durable stores when
+upgrading. No database lock may be held during a model/provider call.
+Confirmed execution receives a separate runtime-created `confirmation` value
+(`decision`, `turnId`, `sourceKey`); ordinary execution receives `null`. The host
+must not accept equivalent claims from model arguments. Policy is rechecked after
+the claim. Interpretation is not an authorization decision.
+Store methods receive a second `{ principal, context }` argument so a host can
+persist through already-resolved tenant associations without querying global
+identifiers again. Runtime callbacks also receive the original trusted
+`context`; it is never copied into the persisted turn automatically.
+
+```js
+const {
+  ChannelRuntime,
+  MemoryTurnStore,
+  createChatAdapter
+} = require('@bliggy/chat-runtime');
+
+const runtime = new ChannelRuntime({
+  adapters: {
+    chat: createChatAdapter({
+      authenticate: async (_envelope, context) => ({
+        allowed: context.sessionAuthenticated,
+        method: 'session'
+      })
+    })
+  },
+  turnStore: new MemoryTurnStore(),
+  resolvePrincipal: async ({ context }) => context.principalResolution,
+  plan: async ({ envelope }) => planner.plan(envelope.text),
+  authorize: async input => policy.authorize(input),
+  execute: async input => tools.execute(input)
+});
+```
+
+The host must generate a unique source key for each Chat message and reuse it
+when retrying that same message.
+Never accept tenant or actor identifiers from the untrusted channel payload.
+
+## Twilio
+
+`createTwilioChannels` returns `sms`, `voice`, `sendSms`, and `startCall`.
+Inbound adapters validate `X-Twilio-Signature` with the official Twilio SDK.
+The host must pass the exact public request URL and every form parameter:
+
+```js
+const { ChannelRuntime, createTwilioChannels } = require('@bliggy/chat-runtime');
+
+const channels = createTwilioChannels({
+  accountSid: process.env.TWILIO_ACCOUNT_SID,
+  authToken: process.env.TWILIO_AUTH_TOKEN,
+  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
+  voiceFrom: process.env.TWILIO_VOICE_NUMBER,
+  voiceActionUrl: 'https://app.example.com/webhooks/twilio/voice'
+});
+
+// Supply the application's durable store and callbacks described above.
+const twilioRuntime = new ChannelRuntime({
+  adapters: { sms: channels.sms, voice: channels.voice },
+  turnStore,
+  resolvePrincipal,
+  plan,
+  authorize,
+  execute
+});
+
+await twilioRuntime.handle({
+  channel: 'sms',
+  payload: req.body,
+  context: {
+    url: publicRequestUrl,
+    params: req.body,
+    headers: req.headers
+  }
+});
+```
+
+Voice uses Programmable Voice speech/DTMF `Gather`. The generated TwiML adds a
+fresh `turnKey` query parameter to every Gather action URL. The host must pass
+that query value back as `context.turnKey`; this distinguishes successive turns
+inside one `CallSid` and makes webhook retries idempotent. Twilio's optional
+speech `Confidence` value is recorded as metadata but is never trusted as an
+authentication signal.
+
+Real-time bidirectional Media Streams are intentionally outside this package
+version and should be added as a separate streaming adapter.
+
+## Security rules
+
+- Authentication happens before tenant or actor resolution and before storage.
+- Provider payloads never choose their own tenant or actor.
+- Duplicate source messages return the stored result without replanning.
+- Confirmations are scoped to tenant, actor, channel, and thread.
+- Asynchronous interpretation binds to an exact pending-action snapshot; a stale,
+  changed, expired, cancelled or concurrently claimed snapshot cannot execute.
+- Hosts own semantic accuracy: keep classifier inputs limited to the authenticated
+  current reply and application-owned action descriptions, excluding document,
+  assistant and tool text. Partial/conditional/uncertain acknowledgment must not
+  become approval of every action in a batch.
+- Policy is fail-closed and is checked again when confirmation is received.
+- Authentication records stored on a turn exclude secrets and signatures.
+- Security-event callbacks receive identifiers and verdicts, not message text.
+
+Twilio webhook validation follows:
+
+- https://www.twilio.com/docs/usage/webhooks/webhooks-security
+- https://www.twilio.com/docs/voice/twiml/gather

package/index.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const {
+  ChannelRuntime,
+  ChannelRuntimeError,
+  EnvelopeValidationError,
+  SecurityError,
+  RateLimitError,
+  TURN_STATUSES,
+  TURN_TRANSITIONS,
+  parseDecision
+} = require('./src/runtime');
+const { MemoryTurnStore } = require('./src/memoryTurnStore');
+const { createChatAdapter, createEmailAdapter } = require('./src/channels');
+const { createTwilioChannels } = require('./src/twilio');
+const { runConversation, streamConversation } = require('./src/conversation');
+const { selectPendingActions } = require('./src/pendingActions');
+
+module.exports = {
+  ChannelRuntime,
+  ChannelRuntimeError,
+  EnvelopeValidationError,
+  SecurityError,
+  RateLimitError,
+  MemoryTurnStore,
+  TURN_STATUSES,
+  TURN_TRANSITIONS,
+  parseDecision,
+  createChatAdapter,
+  createEmailAdapter,
+  createTwilioChannels,
+  runConversation,
+  streamConversation,
+  selectPendingActions
+};

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@bliggy/chat-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Shared chat conversations, tool execution, and action confirmations powered by @bliggy/llm-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davejohnson/agent-channel-runtime.git"
+  },
+  "main": "index.js",
+  "exports": "./index.js",
+  "files": [
+    "index.js",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.node.js"
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "dependencies": {
+    "@bliggy/llm-client": "0.1.0",
+    "twilio": "^6.0.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "ISC"
+}

package/src/channels.js

@@ -0,0 +1,72 @@
+'use strict';
+
+function header(headers, name) {
+  if (!headers || typeof headers !== 'object') return null;
+  const key = Object.keys(headers).find(candidate => candidate.toLowerCase() === name.toLowerCase());
+  return key ? headers[key] : null;
+}
+
+function requireAuthenticator(authenticate, channel) {
+  if (typeof authenticate !== 'function') {
+    throw new TypeError(`${channel} authenticate callback is required`);
+  }
+  return authenticate;
+}
+
+function createChatAdapter({ authenticate, format = null } = {}) {
+  const verify = requireAuthenticator(authenticate, 'chat');
+  return {
+    async normalize(payload, context) {
+      return {
+        channel: 'chat',
+        sourceKey: payload?.sourceKey || context.sourceKey || '',
+        threadKey: payload?.threadKey || payload?.conversationId || context.threadKey || '',
+        sender: null,
+        recipient: 'agent',
+        text: payload?.text ?? payload?.message ?? '',
+        attachments: payload?.attachments || [],
+        metadata: payload?.metadata || null
+      };
+    },
+    authenticate: verify,
+    async format(output, details) {
+      if (format) return await format(output, details);
+      return {
+        content: output.content || '',
+        results: output.results || [],
+        pendingActions: output.pendingActions || []
+      };
+    }
+  };
+}
+
+function createEmailAdapter({ authenticate, format = null } = {}) {
+  const verify = requireAuthenticator(authenticate, 'email');
+  return {
+    async normalize(payload) {
+      const sourceKey = payload?.messageId || header(payload?.headers, 'message-id') || '';
+      const inReplyTo = payload?.inReplyTo || header(payload?.headers, 'in-reply-to');
+      return {
+        channel: 'email',
+        sourceKey,
+        threadKey: payload?.threadKey || inReplyTo || sourceKey,
+        sender: payload?.from || null,
+        recipient: payload?.to || null,
+        subject: payload?.subject || '(no subject)',
+        text: payload?.text || '',
+        attachments: payload?.attachments || [],
+        metadata: payload?.metadata || null
+      };
+    },
+    authenticate: verify,
+    async format(output, details) {
+      if (format) return await format(output, details);
+      const subject = details.envelope.subject.startsWith('Re:')
+        ? details.envelope.subject
+        : `Re: ${details.envelope.subject}`;
+      return { subject, text: output.content || '', html: null };
+    }
+  };
+}
+
+module.exports = { createChatAdapter, createEmailAdapter };