@bliggy/chat-runtime 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,282 @@
-# 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 entry points for different application flows:
+
+- `runConversation` runs a bounded streaming conversation and tool loop. It
+  delegates every tool call 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.
+
+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,34 @@
+'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 } = 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,
+  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.0",
+  "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 };

package/src/conversation.js

@@ -0,0 +1,154 @@
+'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;
+}
+
+async function consumeTurn(streamTurn, request, onEvent) {
+  let result = null;
+  for await (const event of streamTurn(request)) {
+    if (event.type === 'done') {
+      if (result) throw new Error('Chat stream returned more than one final result.');
+      result = event.result;
+    } else {
+      await onEvent(event);
+    }
+  }
+  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,
+  onToolResult = () => {}
+} = {}) {
+  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 })) {
+    if (callback !== null && typeof callback !== 'function') throw new TypeError(`${name} must be a function.`);
+  }
+
+  const messages = [...initialMessages];
+  let forceText = false;
+  let result = null;
+
+  for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+    const textOnly = forceText || iteration === maxIterations || tools.length === 0;
+    const state = { iteration, textOnly, messages };
+    const request = {
+      ...requestOptions,
+      system: getSystem ? await getSystem(state) : requestOptions.system,
+      messages,
+      tools,
+      toolChoice: textOnly ? 'none' : 'auto',
+      parallelToolCalls: false
+    };
+    result = await trackTurn(() => consumeTurn(streamTurn, request, onEvent), state);
+    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);
+    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) throw new TypeError('executeTool is required for tool calls.');
+
+    const persistedMessage = {
+      ...assistantMessage,
+      content: assistantMessage.content.filter(block => !PRIVATE_BLOCK_TYPES.has(block.type))
+    };
+    await onAssistantMessage(persistedMessage, responseState);
+    // 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;
+    for (const toolCall of toolCalls) {
+      const outcome = await executeTool(toolCall, responseState);
+      if (!outcome || outcome.output === undefined) {
+        throw new TypeError('executeTool must return an outcome with output.');
+      }
+      const message = {
+        role: 'user',
+        content: [{
+          type: 'tool_result',
+          toolCallId: toolCall.id,
+          output: outcome.output,
+          isError: Boolean(outcome.isError)
+        }]
+      };
+      await onToolResult(message, { ...responseState, toolCall, outcome });
+      messages.push(message);
+      forceText ||= Boolean(outcome.forceText);
+    }
+  }
+
+  return { status: 'limit', result, messages, iterations: maxIterations };
+}
+
+module.exports = { runConversation };

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 };