@adonis-agora/agent 0.64.0 → 0.65.0

package/dist/src/channels/handler.js

@@ -1,74 +1,13 @@
-import { DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY, ptBrActionProposalText, } from '../action-proposal-text.js';
+import { DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY, parseTextActionProposalCommand, } from '../action-proposal-text.js';
 import { AgentService, AttachmentRefusedError } from '../agent-service.js';
+import { onAgentEngine, registeredAgentEngine } from '../durable/agent-run-context.js';
+import { durableExecutor, inlineExecutor, jobId, registerChannelWorkflows, withRetries, } from './executor.js';
 import { ChannelMediaTooLargeError } from './http.js';
 import { toChannelMarkdown } from './markdown.js';
-import { DEFAULT_CHANNEL_QUESTION_TEXTS, formatChannelQuestion, parseChannelAnswer, ptBrChannelQuestionTexts, } from './questions.js';
+import { formatChannelQuestion, parseChannelAnswer } from './questions.js';
 import { splitMessage } from './split.js';
 import { InMemoryChannelStore, lucidChannelStore } from './store.js';
-/** `20 MB`, `512 KB`. */
-const readableSize = (bytes) => bytes >= 1024 * 1024
-    ? `${Math.round(bytes / (1024 * 1024))} MB`
-    : `${Math.max(1, Math.ceil(bytes / 1024))} KB`;
-export const DEFAULT_CHANNEL_TEXTS = {
-    approve: 'Confirm',
-    reject: 'Cancel',
-    proposal: ({ confirmation, toolName }) => confirmation
-        ? `*${confirmation.title}*${confirmation.detail ? `\n${confirmation.detail}` : ''}`
-        : `*Run ${toolName}?*`,
-    instruction: ({ approve, reject }) => `Reply *${approve}* to confirm or *${reject}* to cancel.`,
-    blockingApproval: 'This action needs an approval that can only be given in the app.',
-    failed: 'Sorry, something went wrong. Please try again.',
-    actionSucceeded: 'Done.',
-    actionFailed: 'The action could not be completed.',
-    mediaRefused: (reason, media, limits) => reason === 'disabled'
-        ? 'I can only read text messages here.'
-        : reason === 'size'
-            ? `That file is too large${limits ? ` (the limit is ${readableSize(limits.maxBytes)})` : ''}.`
-            : reason === 'failed'
-                ? 'I could not download that file. Please send it again.'
-                : media.kind === 'audio'
-                    ? 'I cannot listen to audio messages. Please type your message.'
-                    : `I cannot read this kind of file${media.contentType ? ` (${media.contentType})` : ''}.`,
-    questions: DEFAULT_CHANNEL_QUESTION_TEXTS,
-};
-/**
- * Brazilian Portuguese channel texts — the default when the agent's `actionProposalText` is
- * `ptBrActionProposalText`, so the reply words and what the channel says agree.
- */
-export const ptBrChannelTexts = {
-    approve: 'Confirmar',
-    reject: 'Cancelar',
-    proposal: ({ confirmation, toolName }) => confirmation
-        ? `*${confirmation.title}*${confirmation.detail ? `\n${confirmation.detail}` : ''}`
-        : `*Executar ${toolName}?*`,
-    instruction: ({ approve, reject }) => `Responda *${approve}* para confirmar ou *${reject}* para cancelar.`,
-    blockingApproval: 'Esta ação precisa de uma aprovação que só pode ser dada no app.',
-    failed: 'Desculpe, algo deu errado. Tente de novo, por favor.',
-    actionSucceeded: 'Pronto.',
-    actionFailed: 'Não foi possível concluir a ação.',
-    mediaRefused: (reason, media, limits) => reason === 'disabled'
-        ? 'Por aqui eu só consigo ler mensagens de texto.'
-        : reason === 'size'
-            ? `Esse arquivo é grande demais${limits ? ` (o limite é ${readableSize(limits.maxBytes)})` : ''}.`
-            : reason === 'failed'
-                ? 'Não consegui baixar esse arquivo. Envie de novo, por favor.'
-                : media.kind === 'audio'
-                    ? 'Não consigo ouvir mensagens de áudio. Escreva sua mensagem, por favor.'
-                    : `Não consigo ler esse tipo de arquivo${media.contentType ? ` (${media.contentType})` : ''}.`,
-    questions: ptBrChannelQuestionTexts,
-};
-/**
- * The channel texts that speak the language of the agent's text-decision words: {@link
- * ptBrChannelTexts} for `ptBrActionProposalText` (or any vocabulary whose `language` is Portuguese),
- * else {@link DEFAULT_CHANNEL_TEXTS}.
- */
-export function channelTextsFor(vocabulary) {
-    if (!vocabulary)
-        return DEFAULT_CHANNEL_TEXTS;
-    const portuguese = /^pt(-|$)/i.test(vocabulary.language ?? '') ||
-        vocabulary.approve === ptBrActionProposalText.vocabulary.approve;
-    return portuguese ? ptBrChannelTexts : DEFAULT_CHANNEL_TEXTS;
-}
+import { channelTextsFor, mergeTexts, } from './texts.js';
 const BUTTON_ID = /^agora:(approve|reject):([^\s]+)$/;
 /** The tail of a proposal id a button carries — Telegram's `callback_data` holds 64 bytes. */
 const BUTTON_REF_LENGTH = 32;
@@ -76,6 +15,10 @@ const OUTCOME_POLL_MS = 500;
 /** How long "this outcome was relayed" is remembered. */
 const OUTCOME_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const buttonRef = (proposalId) => proposalId.slice(-BUTTON_REF_LENGTH);
+/** How long the proposal cards sent to a conversation are remembered, and how many. */
+const CARDS_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_CARDS = 20;
+const foldLabel = (label) => label.trim().toLowerCase();
 /** The button ids for a proposal: what {@link ChannelRouteHandler} maps back to its decision. */
 export function proposalButtonIds(proposalId) {
     const ref = buttonRef(proposalId);
@@ -97,50 +40,15 @@ async function containerService() {
     return (await app.container.make(AgentService));
 }
 const registry = new Map();
-const mergeTexts = (overrides = {}, base = DEFAULT_CHANNEL_TEXTS) => ({
-    ...base,
-    ...overrides,
-    questions: { ...base.questions, ...overrides.questions },
-});
-/** Send `text` converted to the channel's markdown, split at its length limit. */
-async function deliverText(adapter, conversation, text) {
-    const { markdown, maxLength } = adapter.capabilities;
-    for (const piece of splitMessage(toChannelMarkdown(text, markdown), maxLength))
-        await adapter.send(conversation, { text: piece });
-}
-/** What an executed proposal tells the person; `null` when it did not execute. */
-function outcomeText(proposal, texts) {
-    const status = proposal.execution?.status;
-    if (status === 'failed')
-        return texts.actionFailed;
-    if (status !== 'succeeded')
-        return null;
-    // What its presentation said (`present` / `emitUi` text), else a plain confirmation.
-    return proposal.outcome?.text?.trim() || texts.actionSucceeded;
-}
-/**
- * Relay an executed proposal's outcome to the conversation it was proposed in — once: the handler's
- * own wait and this share a claim in the channel's store. `false` when it was not relayed (no
- * channel recorded, the channel is not registered in this process, not executed, already relayed).
- */
-async function deliverOutcome(proposal, service) {
-    const address = record(proposal.executionContext?.pageContext?.channel);
-    const name = typeof address?.name === 'string' ? address.name : undefined;
-    const conversation = typeof address?.conversation === 'string' ? address.conversation : undefined;
-    const registration = name === undefined ? undefined : registry.get(name);
-    if (!registration || conversation === undefined)
-        return false;
-    return relayOnce(await registration.store(service), registration.adapter, await registration.texts(service), conversation, proposal);
-}
-/** Send an executed proposal's outcome unless it was sent already (by this or another replica). */
-async function relayOnce(store, adapter, texts, conversation, proposal) {
-    const text = outcomeText(proposal, texts);
-    if (text === null)
-        return false;
-    if (!(await store.claim(`${adapter.name}:outcome:${proposal.id}`, OUTCOME_TTL_MS)))
-        return false;
-    await deliverText(adapter, conversation, text);
-    return true;
+/** The job runner of the channel registered under `channel` in this process. */
+const runnerFor = (channel) => registry.get(channel)?.run;
+let following = false;
+/** Register the channel workflows on the agent's durable engine, now or once it is wired. */
+function followAgentEngine() {
+    if (following)
+        return;
+    following = true;
+    onAgentEngine((engine) => registerChannelWorkflows(engine, runnerFor));
 }
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -149,45 +57,75 @@ function record(value) {
 }
 /** `image/jpeg` → `jpeg`, for a file that arrives without a name. */
 const extensionOf = (contentType) => (contentType.split('/')[1] ?? 'bin').split(/[;+]/)[0] ?? 'bin';
+const replyList = (value) => value === null || value === undefined ? [] : Array.isArray(value) ? value : [value];
+/** The component a frame carries (a live one, or a replayed `ui` event), else `null`. */
+function componentOf(frame, position) {
+    if (frame.t === 'component') {
+        return {
+            id: frame.id ?? `ui:${position}`,
+            name: frame.name,
+            data: frame.data,
+            version: frame.version ?? 1,
+            ...(frame.fallbackText !== undefined ? { fallbackText: frame.fallbackText } : {}),
+        };
+    }
+    if (frame.t === 'event' && frame.event.kind === 'ui') {
+        const { event } = frame;
+        return {
+            id: event.id,
+            name: event.component,
+            data: event.props,
+            version: event.version ?? 1,
+            ...(event.fallbackText !== undefined ? { fallbackText: event.fallbackText } : {}),
+        };
+    }
+    return null;
+}
 /**
  * The webhook route for one channel. Each request is verified (`401` when it is not the provider's),
- * parsed, deduplicated by the provider's message id, and acknowledged with `200` at once; the turn
- * runs after the response, so a slow model never makes the provider retry. Then:
+ * parsed, deduplicated by the provider's message id, taken (persisted, with a durable engine) and
+ * acknowledged with `200`; the message is handled after the response — one at a time per
+ * conversation, each phase retried — so a slow model never makes the provider retry. Then:
  *
- * - media are downloaded and attached (held to the attachment store's limits), or refused with a text;
- * - the message is sent with text-only capabilities (components arrive as their `fallbackText`);
- *   a text decision ("yes", "confirm #ID") is answered with its reply instead of starting a turn;
+ * - an unknown sender gets `unknownSender`; a known one goes through `beforeTurn`;
+ * - an answer to a question the turn asked resumes it;
  * - a press on a proposal's button decides that proposal (`via` = the adapter's name);
- * - a question the turn asks is sent as text, one at a time, and the next messages answer it;
- * - the reply is converted to the channel's markdown, split at its length limit, and sent;
- * - a proposal the turn left pending is sent with Confirm/Cancel buttons — or, on a channel without
- *   them, with a text instruction in the configured `actionProposalText` vocabulary;
+ * - a text decision ("yes", "no #ID", a button label) decides a card delivered to THIS conversation
+ *   — never a proposal made elsewhere (`texts.noPendingConfirmation`);
+ * - media are downloaded (`prepareMedia`) and attached, or refused with a text;
+ * - the message (`transformInbound`) starts a turn with the channel's capabilities;
+ * - the reply is converted to the channel's markdown, split at its length limit, and sent — each
+ *   message once, even when the work is retried or resumed after a crash;
+ * - a proposal the turn left pending is sent with Confirm/Cancel buttons (or a text instruction);
  * - an approved proposal's outcome is relayed once it executed (see `outcomeTimeoutMs`, and
  *   `channels.onSettled` for one that runs later).
  *
  * Wants `actionApprovalMode: 'independent'`: a blocking approval holds the turn open until someone
  * decides it in the app, so the channel sends what it has and `texts.blockingApproval`.
  *
- * Registers the adapter under its `name` for `channels.onSettled` — names must be unique.
+ * Registers the adapter under its `name` for `channels.onSettled` and the durable jobs — names must
+ * be unique, and a process that resumes durable channel jobs must create the same handlers at boot.
  */
 export function handleChannel(adapter, options) {
-    let resolvedTexts;
-    /** The texts, over the defaults in the language of the service's vocabulary — chosen once. */
-    const textsFor = (service) => {
-        if (resolvedTexts)
-            return resolvedTexts;
-        const texts = mergeTexts(options.texts, channelTextsFor(service?.actionProposalVocabulary?.() ?? null));
-        if (service)
-            resolvedTexts = texts;
-        return texts;
-    };
     const dedupeTtlMs = options.dedupeTtlMs ?? 24 * 60 * 60 * 1000;
     const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
     const outcomeTimeoutMs = options.outcomeTimeoutMs ?? 60_000;
     const questionTimeoutMs = options.questionTimeoutMs ?? 30 * 60 * 1000;
     const { capabilities } = adapter;
     const buttons = (capabilities.buttons ?? 0) >= 2;
-    const inFlight = new Set();
+    const name = adapter.name;
+    let resolvedService;
+    const serviceFor = (given) => {
+        if (options.service)
+            return Promise.resolve(options.service);
+        if (given)
+            return Promise.resolve(given);
+        resolvedService ??= containerService().catch((error) => {
+            resolvedService = undefined;
+            throw error;
+        });
+        return resolvedService;
+    };
     let resolvedStore;
     /** The configured store, else Lucid over the agent store's database, else memory — chosen once. */
     const storeFor = (service) => {
@@ -200,33 +138,127 @@ export function handleChannel(adapter, options) {
         })();
         return resolvedStore;
     };
-    registry.set(adapter.name, {
-        adapter,
-        texts: async (service) => textsFor(options.service ?? service ?? (await containerService().catch(() => undefined))),
-        store: storeFor,
-    });
-    const deliver = (conversation, text) => deliverText(adapter, conversation, text);
-    const questionKey = (conversation) => `${adapter.name}:question:${conversation}`;
-    const commandsFor = (service, proposalId, withId) => {
+    /** The texts for one context, over the defaults in the language of the service's vocabulary. */
+    const textsFor = async (service, context) => {
+        const base = channelTextsFor(service.actionProposalVocabulary?.() ?? null);
+        const overrides = typeof options.texts === 'function' ? await options.texts(context) : options.texts;
+        return mergeTexts(overrides, base);
+    };
+    const questionKey = (conversation) => `${name}:question:${conversation}`;
+    const cardsKey = (conversation) => `${name}:cards:${conversation}`;
+    const answeredKey = (runId, toolCallId) => `${name}:answered:${runId}:${toolCallId}`;
+    /**
+     * Settle a question once — by its answer, by its timeout, or skipped: `true` when `owner` settles
+     * it (now, or in an earlier run of the same phase), `false` when something else did first.
+     */
+    const settleQuestion = async (store, runId, toolCallId, owner) => {
+        const key = answeredKey(runId, toolCallId);
+        if (await store.claim(key, dedupeTtlMs)) {
+            await store.set(key, owner, dedupeTtlMs);
+            return true;
+        }
+        return (await store.get(key)) === owner;
+    };
+    /**
+     * Sends to one conversation, each message at most once: every message takes a numbered slot
+     * under `key` in the store before it goes out, so a phase that runs again (a retry, a crash
+     * recovery) skips what already went. A failed send frees its slot, so the retry sends it.
+     */
+    const outbox = (store, key, conversation, who) => {
+        let next = 0;
+        const send = async (outbound, kind) => {
+            const slot = `${key}:${next++}`;
+            if (!(await store.claim(slot, dedupeTtlMs)))
+                return;
+            try {
+                if (options.canDeliver &&
+                    !(await options.canDeliver({
+                        channel: name,
+                        conversation,
+                        outbound,
+                        kind,
+                        actor: who.actor,
+                        actorRef: who.actorRef ?? who.actor?.id ?? null,
+                        message: who.message,
+                        proposal: who.proposal ?? null,
+                    })))
+                    return;
+                await adapter.send(conversation, outbound);
+            }
+            catch (error) {
+                await Promise.resolve(store.delete(slot)).catch(() => { });
+                throw error;
+            }
+        };
+        /** Text in the model's markdown: converted, split. */
+        const text = async (value, kind) => {
+            for (const piece of splitMessage(toChannelMarkdown(value, capabilities.markdown), capabilities.maxLength))
+                await send({ text: piece }, kind);
+        };
+        /** A hook's reply. */
+        const reply = async (value, kind) => {
+            if (typeof value === 'string')
+                return text(value, kind);
+            if ('media' in value) {
+                const caption = value.caption ?? '';
+                if (capabilities.media === true) {
+                    const max = capabilities.maxCaptionLength ?? capabilities.maxLength;
+                    return send({
+                        text: toChannelMarkdown(caption, capabilities.markdown).slice(0, max),
+                        media: value.media,
+                    }, kind);
+                }
+                const fallback = value.fallbackText ?? caption;
+                if (fallback.trim() !== '')
+                    return text(fallback, kind);
+                return;
+            }
+            if (value.raw === true) {
+                for (const piece of splitMessage(value.text, capabilities.maxLength))
+                    await send({ text: piece }, kind);
+                return;
+            }
+            return text(value.text, kind);
+        };
+        return { send, text, reply };
+    };
+    const commandsFor = (service, proposalId) => {
         const vocabulary = service.actionProposalVocabulary?.() ?? DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY;
-        const suffix = withId ? ` #${proposalId}` : '';
+        const suffix = proposalId !== null ? ` #${proposalId}` : '';
         return {
             approve: `${vocabulary.approve[0] ?? 'yes'}${suffix}`,
             reject: `${vocabulary.reject[0] ?? 'no'}${suffix}`,
         };
     };
-    const sendProposal = async (service, conversation, proposal, withId) => {
-        const texts = textsFor(service);
+    /** Remember a proposal card sent to `conversation` — the only proposals it can decide. */
+    const rememberCard = async (store, conversation, proposalId) => {
+        const key = cardsKey(conversation);
+        const saved = await store.get(key);
+        const ref = buttonRef(proposalId);
+        const refs = saved === null ? [] : JSON.parse(saved);
+        const next = [...refs.filter((known) => known !== ref), ref].slice(-MAX_CARDS);
+        await store.set(key, JSON.stringify(next), CARDS_TTL_MS);
+    };
+    const cardsOf = async (store, conversation) => {
+        const saved = await store.get(cardsKey(conversation));
+        return new Set(saved === null ? [] : JSON.parse(saved));
+    };
+    const sendProposal = async (service, store, texts, out, conversation, proposal, withId) => {
         const summary = texts.proposal(proposal);
-        const instruction = texts.instruction(commandsFor(service, proposal.id, withId));
-        const asText = toChannelMarkdown(`${summary}\n\n${instruction}`, capabilities.markdown);
+        const footer = typeof texts.footer === 'function' ? texts.footer(proposal) : texts.footer;
+        const instruction = texts.instruction(commandsFor(service, withId ? proposal.id : null));
+        const asText = toChannelMarkdown([summary, instruction, footer]
+            .filter((part) => part !== undefined && part !== '')
+            .join('\n\n'), capabilities.markdown);
+        // Remembered before it goes: a "yes" can only decide a card this conversation was sent.
+        await rememberCard(store, conversation, proposal.id);
         if (!buttons) {
             for (const piece of splitMessage(asText, capabilities.maxLength))
-                await adapter.send(conversation, { text: piece });
+                await out.send({ text: piece }, 'card');
             return;
         }
         const ids = proposalButtonIds(proposal.id);
-        const message = {
+        await out.send({
             text: toChannelMarkdown(summary, capabilities.markdown).slice(0, capabilities.maxLength),
             buttons: [
                 { id: ids.approve, label: texts.approve },
@@ -234,11 +266,50 @@ export function handleChannel(adapter, options) {
             ],
             fallbackText: asText.slice(0, capabilities.maxLength),
             instruction: toChannelMarkdown(instruction, capabilities.markdown),
-        };
-        await adapter.send(conversation, message);
+            ...(footer !== undefined && footer !== ''
+                ? { footer: toChannelMarkdown(footer, capabilities.markdown) }
+                : {}),
+        }, 'card');
+    };
+    /** What an executed proposal tells the person, in order; `null` when it did not execute. */
+    const outcomeReplies = async (proposal, texts) => {
+        const status = proposal.execution?.status;
+        if (status !== 'failed' && status !== 'succeeded')
+            return null;
+        // What its presentation said (`present` / `emitUi` text), else a plain confirmation.
+        const text = status === 'failed'
+            ? texts.actionFailed
+            : proposal.outcome?.text?.trim() || texts.actionSucceeded;
+        const formatted = await options.formatOutcome?.(proposal, { text, texts });
+        return formatted ?? [text];
+    };
+    /** Send an executed proposal's outcome unless it was sent already (by this or another replica). */
+    const relay = async (proposal, conversation, given, who) => {
+        const service = await serviceFor(given);
+        const store = await storeFor(service);
+        const status = proposal.execution?.status;
+        if (status !== 'failed' && status !== 'succeeded')
+            return false;
+        if (!(await store.claim(`${name}:outcome:${proposal.id}`, OUTCOME_TTL_MS)))
+            return false;
+        const texts = await textsFor(service, {
+            actor: who?.actor ?? null,
+            message: who?.message ?? null,
+            proposal,
+        });
+        const replies = (await outcomeReplies(proposal, texts)) ?? [];
+        const out = outbox(store, `${name}:out:outcome:${proposal.id}`, conversation, {
+            actor: who?.actor ?? null,
+            actorRef: who?.actor?.id ?? proposal.actorRef ?? null,
+            message: who?.message ?? null,
+            proposal,
+        });
+        for (const reply of replies)
+            await out.reply(reply, 'outcome');
+        return true;
     };
     /** Wait for an approved proposal to run, then relay what it said (or that it failed). */
-    const relayOutcome = async (service, actor, threadId, proposalId, conversation) => {
+    const relayOutcome = async (service, actor, threadId, proposalId, message) => {
         if (outcomeTimeoutMs <= 0 || !service.listActionProposals)
             return;
         const deadline = Date.now() + outcomeTimeoutMs;
@@ -246,16 +317,51 @@ export function handleChannel(adapter, options) {
             const current = (await service.listActionProposals(actor, threadId)).find((proposal) => proposal.id === proposalId);
             if (current?.decision !== 'approved')
                 return;
-            const texts = textsFor(service);
-            if (outcomeText(current, texts) !== null) {
-                await relayOnce(await storeFor(service), adapter, texts, conversation, current);
+            const status = current.execution?.status;
+            if (status === 'succeeded' || status === 'failed') {
+                await relay(current, message.conversation, service, { actor, message });
                 return;
             }
             await new Promise((resolve) => setTimeout(resolve, OUTCOME_POLL_MS));
         }
     };
+    /**
+     * A button press the provider forwarded without its id — only the label (Whatsmiau): the id of
+     * the one card it can have come from — a card sent to this conversation whose proposal is still
+     * pending. Several such cards → `undefined`: never guess; the label then goes on as a text
+     * decision, which asks for the `#id`.
+     */
+    const recoverButtonId = async (service, store, texts, actor, threadId, message) => {
+        if (message.buttonId !== undefined || message.buttonWithoutId !== true)
+            return undefined;
+        if (threadId === null || !service.listActionProposals)
+            return undefined;
+        const label = foldLabel(message.text);
+        const action = label === foldLabel(texts.approve)
+            ? 'approve'
+            : label === foldLabel(texts.reject)
+                ? 'reject'
+                : undefined;
+        if (action === undefined)
+            return undefined;
+        const refs = await cardsOf(store, message.conversation);
+        if (refs.size === 0)
+            return undefined;
+        const live = (await service.listActionProposals(actor, threadId)).filter((proposal) => proposal.decision === 'pending' && refs.has(buttonRef(proposal.id)));
+        const only = live.length === 1 ? live[0] : undefined;
+        return only === undefined ? undefined : `agora:${action}:${buttonRef(only.id)}`;
+    };
+    /** Decide one proposal by a press or a text, answer, and relay its outcome when it ran. */
+    const decide = async (service, out, actor, threadId, proposalId, decision, remember, message) => {
+        if (!service.decideActionProposal)
+            return;
+        const result = await service.decideActionProposal(actor, threadId, proposalId, decision, remember ? { remember: true } : {}, name);
+        await out.text(service.actionProposalReply(result, decision), 'notice');
+        if (result.status === 'applied' && decision === 'approved')
+            await relayOutcome(service, actor, threadId, proposalId, message);
+    };
     /** A press on one of our proposal buttons: decide it. `false` → not one of ours. */
-    const pressButton = async (service, actor, threadId, message) => {
+    const pressButton = async (service, out, actor, threadId, message) => {
         const match = message.buttonId === undefined ? null : BUTTON_ID.exec(message.buttonId);
         if (!match || !service.decideActionProposal || !service.listActionProposals)
             return false;
@@ -265,68 +371,144 @@ export function handleChannel(adapter, options) {
             ? undefined
             : (await service.listActionProposals(actor, threadId)).find((candidate) => buttonRef(candidate.id) === ref);
         if (threadId === null || !proposal) {
-            await deliver(message.conversation, service.actionProposalReply({ status: 'not_found' }, decision));
+            await out.text(service.actionProposalReply({ status: 'not_found' }, decision), 'notice');
             return true;
         }
-        const result = await service.decideActionProposal(actor, threadId, proposal.id, decision, {}, adapter.name);
-        await deliver(message.conversation, service.actionProposalReply(result, decision));
-        if (result.status === 'applied' && decision === 'approved')
-            await relayOutcome(service, actor, threadId, proposal.id, message.conversation);
+        await decide(service, out, actor, threadId, proposal.id, decision, false, message);
         return true;
     };
-    const askNext = (service, conversation, pending) => {
+    /**
+     * A text decision ("yes", "no #ID", a button label the provider forwarded alone), scoped to the
+     * cards this conversation was sent. `false` → not a decision: an ordinary message.
+     */
+    const decideByText = async (service, store, texts, out, actor, threadId, message, text) => {
+        if (threadId === null || !service.listActionProposals || !service.decideActionProposal)
+            return false;
+        const vocabulary = service.actionProposalVocabulary?.() ?? DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY;
+        const command = parseTextActionProposalCommand(text, vocabulary);
+        if (command.status !== 'command')
+            return false;
+        const proposals = await service.listActionProposals(actor, threadId);
+        const cards = await cardsOf(store, message.conversation);
+        const deliverable = proposals.filter((proposal) => proposal.decision === 'pending' && cards.has(buttonRef(proposal.id)));
+        const named = command.proposalId;
+        if (named !== undefined) {
+            const target = deliverable.find((proposal) => proposal.id === named);
+            // An `#ID` naming no proposal of the thread is an ordinary message.
+            if (target === undefined && !proposals.some((proposal) => proposal.id === named))
+                return false;
+            if (target === undefined) {
+                await out.text(texts.noPendingConfirmation, 'notice');
+                return true;
+            }
+            if (command.remember && options.allowRemember === false) {
+                await out.text(texts.rememberRefused, 'notice');
+                return true;
+            }
+            await decide(service, out, actor, threadId, target.id, command.decision, command.remember, message);
+            return true;
+        }
+        if (deliverable.length === 0) {
+            // Nothing pending anywhere: "yes" is just a word in the conversation.
+            if (!proposals.some((proposal) => proposal.decision === 'pending'))
+                return false;
+            await out.text(texts.noPendingConfirmation, 'notice');
+            return true;
+        }
+        if (deliverable.length > 1) {
+            await out.text(texts.ambiguousDecision(deliverable.map((proposal) => proposal.id), commandsFor(service, null)), 'notice');
+            return true;
+        }
+        if (command.remember && options.allowRemember === false) {
+            await out.text(texts.rememberRefused, 'notice');
+            return true;
+        }
+        const [only] = deliverable;
+        if (only === undefined)
+            return false;
+        await decide(service, out, actor, threadId, only.id, command.decision, command.remember, message);
+        return true;
+    };
+    const askNext = (texts, out, pending) => {
         const question = pending.questions[pending.index];
         if (!question)
             return Promise.resolve();
-        return deliver(conversation, formatChannelQuestion(question, {
+        return out.text(formatChannelQuestion(question, {
             index: pending.index,
             total: pending.questions.length,
             ...(pending.preamble !== undefined ? { preamble: pending.preamble } : {}),
-        }, textsFor(service).questions));
+        }, texts.questions), 'question');
     };
-    /** The person's message answers the question in front of them; the last one resumes the run. */
-    const answerQuestion = async (service, store, actor, message, pending) => {
-        const question = pending.questions[pending.index];
-        if (!question || !service.answer)
-            return;
-        const texts = textsFor(service);
-        const parsed = parseChannelAnswer(question, message.text, texts.questions.skipWord);
-        if (parsed.status === 'invalid') {
-            await deliver(message.conversation, texts.questions.invalid(parsed.problem));
-            await askNext(service, message.conversation, pending);
-            return;
-        }
-        const next = {
-            ...pending,
-            index: pending.index + 1,
-            answers: parsed.status === 'answer'
-                ? { ...pending.answers, [question.id]: parsed.values }
-                : pending.answers,
-        };
+    /**
+     * The person's message answers the question in front of them; the last one resumes the run.
+     * Returns the run to read on, once all are answered.
+     */
+    const answerQuestion = async (service, store, texts, out, actor, message, pending) => {
+        if (!service.answer)
+            return null;
         const key = questionKey(message.conversation);
-        if (next.index < next.questions.length) {
+        // This message's answer was applied already (its phase is running again): carry on from there.
+        const applied = pending.lastMessageId === message.id;
+        let next = pending;
+        if (!applied) {
+            const question = pending.questions[pending.index];
+            if (!question)
+                return null;
+            const parsed = parseChannelAnswer(question, message.text, texts.questions.skipWord);
+            if (parsed.status === 'invalid') {
+                await out.text(texts.questions.invalid(parsed.problem), 'question');
+                await askNext(texts, out, pending);
+                return null;
+            }
+            next = {
+                ...pending,
+                index: pending.index + 1,
+                answers: parsed.status === 'answer'
+                    ? { ...pending.answers, [question.id]: parsed.values }
+                    : pending.answers,
+                lastMessageId: message.id,
+            };
             await store.set(key, JSON.stringify(next), questionTimeoutMs);
-            await askNext(service, message.conversation, next);
-            return;
+        }
+        if (next.index < next.questions.length) {
+            await askNext(texts, out, next);
+            return null;
+        }
+        if (!(await settleQuestion(store, next.runId, next.toolCallId, `answer:${message.id}`))) {
+            // It timed out while this answer was on its way: the run went on without it, and this is a
+            // message like any other.
+            await store.delete(key);
+            return 'expired';
+        }
+        // The run that asked goes on: what it says next is read from its stream.
+        try {
+            await service.answer({
+                runId: next.runId,
+                toolCallId: next.toolCallId,
+                answers: next.answers,
+                answeredByRef: actor.id,
+                answeredVia: name,
+            });
+        }
+        catch (error) {
+            // Taken by a run of this phase that died after answering: the run has it.
+            if (!applied)
+                throw error;
         }
         await store.delete(key);
-        // The turn that asked is still being read: what the agent says next reaches the person there.
-        await service.answer({
-            runId: next.runId,
-            toolCallId: next.toolCallId,
-            answers: next.answers,
-            answeredByRef: actor.id,
-            answeredVia: adapter.name,
-        });
+        return next.streamRunId;
     };
     /** Download a message's files and stage them for the turn; refuse what cannot be attached. */
-    const attachMedia = async (service, actor, message) => {
+    const attachMedia = async (service, texts, out, actor, message) => {
         const refs = [];
-        const limits = service.attachmentLimits?.() ?? null;
-        const texts = textsFor(service);
+        const extra = [];
+        const base = service.attachmentLimits?.() ?? null;
         for (const media of message.media ?? []) {
-            const refuse = (reason) => deliver(message.conversation, texts.mediaRefused(reason, media, limits));
-            if (limits === null || !adapter.download || !service.stageAttachment) {
+            const limits = options.mediaLimits ? options.mediaLimits(base, media) : base;
+            const refuse = (reason) => out.text(texts.mediaRefused(reason, media, limits), 'notice');
+            if (limits === null ||
+                !adapter.download ||
+                (!service.stageAttachment && !options.prepareMedia)) {
                 await refuse('disabled');
                 continue;
             }
@@ -340,7 +522,28 @@ export function handleChannel(adapter, options) {
                 continue;
             }
             try {
-                const file = await adapter.download(media, { maxBytes: limits.maxBytes });
+                let file = await adapter.download(media, { maxBytes: limits.maxBytes });
+                const prepared = await options.prepareMedia?.(file, media, {
+                    channel: name,
+                    conversation: message.conversation,
+                    message,
+                    actor,
+                });
+                if (prepared && 'refuse' in prepared) {
+                    await refuse(prepared.refuse);
+                    continue;
+                }
+                if (prepared && 'text' in prepared) {
+                    if (prepared.text.trim() !== '')
+                        extra.push(prepared.text);
+                    continue;
+                }
+                if (prepared && 'file' in prepared)
+                    file = prepared.file;
+                if (!service.stageAttachment) {
+                    await refuse('disabled');
+                    continue;
+                }
                 const attachment = await service.stageAttachment(actor, {
                     data: file.data,
                     contentType: file.contentType,
@@ -359,71 +562,89 @@ export function handleChannel(adapter, options) {
                 }
             }
         }
-        return refs;
+        return { refs, extra };
     };
-    /** Read a run's frames until it ends (or parks on something a text channel cannot settle). */
-    const readTurn = async (service, store, actor, runId, threadId, conversation) => {
+    /**
+     * Read a run's frames until it ends (or parks on a question, or on something a text channel
+     * cannot settle) and deliver them. Reads the stream from its start: what was delivered before (a
+     * read before a question, a read a crash cut short) is skipped by its slot.
+     */
+    const readTurn = async (service, store, actor, runId, threadId, conversation, message) => {
+        const texts = await textsFor(service, { actor, message });
+        const out = outbox(store, `${name}:out:${runId}`, conversation, { actor, message });
         const parts = [];
         const proposals = new Map();
+        /** Components rendered as files, by id (a later one replaces), sent before the text. */
+        const rendered = new Map();
+        const asText = new Set();
+        let wroteText = false;
         let failed = false;
         let blocked = false;
-        let deadlineAt = Date.now() + timeoutMs;
-        /** The question set this reader is waiting on, while it waits. */
-        let asking = null;
-        const flush = async () => {
+        let parked = false;
+        let position = 0;
+        const deadlineAt = Date.now() + timeoutMs;
+        const flush = async (end) => {
+            const batch = [...rendered.values()];
+            rendered.clear();
+            for (const { replies } of batch)
+                for (const reply of replies)
+                    await out.reply(reply, 'reply');
             const text = parts.join('').trim();
             parts.length = 0;
             if (text !== '')
-                await deliver(conversation, text);
+                await out.text(text, 'reply');
+            if (end && !wroteText && batch.length > 0) {
+                const after = texts.componentsOnly?.(batch.map(({ component }) => component));
+                if (after !== undefined && after !== '')
+                    await out.text(after, 'reply');
+            }
         };
         const stream = service.subscribe(runId)[Symbol.asyncIterator]();
-        let reading;
         try {
             for (;;) {
                 let timer;
                 const timeout = new Promise((resolve) => {
                     timer = setTimeout(() => resolve('timeout'), Math.max(0, deadlineAt - Date.now()));
                 });
-                // A read that lost a race to the timer is still the next frame: keep it, never ask twice.
-                reading ??= stream.next();
-                const next = await Promise.race([reading, timeout]).finally(() => clearTimeout(timer));
-                if (next !== 'timeout')
-                    reading = undefined;
+                const next = await Promise.race([stream.next(), timeout]).finally(() => clearTimeout(timer));
                 if (next === 'timeout') {
-                    if (asking !== null) {
-                        // Nobody answered: the agent goes on on its own assumptions.
-                        const { runId: parkedRun, toolCallId } = asking;
-                        asking = null;
-                        await store.delete(questionKey(conversation));
-                        await service
-                            .skip({
-                            runId: parkedRun,
-                            toolCallId,
-                            answeredByRef: actor.id,
-                            answeredVia: adapter.name,
-                        })
-                            .catch(() => { });
-                        deadlineAt = Date.now() + timeoutMs;
-                        continue;
-                    }
-                    failed = parts.length === 0;
+                    failed = parts.length === 0 && rendered.size === 0 && !wroteText;
                     await service.cancel(runId).catch(() => { });
                     break;
                 }
                 if (next.done)
                     break;
                 const frame = next.value;
-                if (asking !== null) {
-                    // The run moved on: the questions were answered (or skipped elsewhere).
-                    asking = null;
-                    deadlineAt = Date.now() + timeoutMs;
+                const component = componentOf(frame, position++);
+                if (component !== null) {
+                    const replies = options.renderComponent
+                        ? replyList(await options.renderComponent(component, {
+                            actor,
+                            conversation,
+                            runId,
+                            rendered: rendered.size,
+                        }))
+                        : [];
+                    if (replies.length > 0) {
+                        rendered.set(component.id, { component, replies });
+                        continue;
+                    }
+                    rendered.delete(component.id);
+                    if (component.fallbackText && !asText.has(component.id)) {
+                        // Only a component the turn negotiated as drawable comes as a frame; its text is all a
+                        // channel that does not render it can show.
+                        asText.add(component.id);
+                        wroteText = true;
+                        parts.push(`\n\n${component.fallbackText}\n\n`);
+                    }
                 }
-                if (frame.t === 'text')
+                else if (frame.t === 'text') {
+                    wroteText ||= frame.v.trim() !== '';
                     parts.push(frame.v);
-                else if (frame.t === 'component' && frame.fallbackText) {
-                    // Only a component the turn negotiated as drawable comes as a frame — never with
-                    // text-only capabilities; its text is all a channel can show.
-                    parts.push(`\n\n${frame.fallbackText}\n\n`);
+                }
+                else if (frame.t === 'event' && frame.event.kind === 'text') {
+                    wroteText ||= frame.event.text.trim() !== '';
+                    parts.push(frame.event.text);
                 }
                 else if (frame.t === 'approval') {
                     if (frame.target?.kind === 'proposal') {
@@ -441,169 +662,456 @@ export function handleChannel(adapter, options) {
                 }
                 else if (frame.t === 'elicitation') {
                     const questions = frame.request.questions;
+                    const asked = {
+                        threadId,
+                        runId: frame.runId,
+                        streamRunId: runId,
+                        toolCallId: frame.id,
+                        ...(frame.request.preamble !== undefined ? { preamble: frame.request.preamble } : {}),
+                        questions,
+                        index: 0,
+                        answers: {},
+                    };
+                    if ((await store.get(answeredKey(frame.runId, frame.id))) !== null) {
+                        // Answered (or skipped) before, and the run went on past it. What was sent around it
+                        // then is sent (skipped, by its slots) the same way now, so what follows keeps its slots.
+                        if (service.answer && questions.length > 0) {
+                            await flush(false);
+                            await askNext(texts, out, asked);
+                        }
+                        continue;
+                    }
                     if (!service.answer || questions.length === 0) {
+                        await settleQuestion(store, frame.runId, frame.id, 'skipped');
                         await service
                             .skip({
                             runId: frame.runId,
                             toolCallId: frame.id,
                             answeredByRef: actor.id,
-                            answeredVia: adapter.name,
+                            answeredVia: name,
                         })
                             .catch(() => { });
                         continue;
                     }
-                    await flush();
-                    const pending = {
-                        threadId,
+                    await flush(false);
+                    const pending = asked;
+                    const key = questionKey(conversation);
+                    const waiting = await store.get(key);
+                    const same = waiting !== null && JSON.parse(waiting).toolCallId === frame.id;
+                    if (!same)
+                        await store.set(key, JSON.stringify(pending), questionTimeoutMs);
+                    await askNext(texts, out, pending);
+                    // The answers come as the next messages; nobody answering in time skips it.
+                    await executor().later({
+                        kind: 'timeout',
+                        channel: name,
+                        conversation,
                         runId: frame.runId,
                         toolCallId: frame.id,
-                        ...(frame.request.preamble !== undefined ? { preamble: frame.request.preamble } : {}),
-                        questions,
-                        index: 0,
-                        answers: {},
-                    };
-                    await store.set(questionKey(conversation), JSON.stringify(pending), questionTimeoutMs);
-                    await askNext(service, conversation, pending);
-                    asking = { runId: frame.runId, toolCallId: frame.id };
-                    deadlineAt = Date.now() + questionTimeoutMs;
+                        streamRunId: runId,
+                        threadId,
+                        actor,
+                    }, jobId(name, 'timeout', frame.runId, frame.id), Date.now() + questionTimeoutMs);
+                    parked = true;
+                    break;
                 }
-                else if (frame.t === 'error')
+                else if (frame.t === 'error') {
                     failed = true;
+                    // A failed turn shows none of what it drew before failing.
+                    rendered.clear();
+                }
             }
         }
         finally {
             void stream.return?.();
         }
-        return { text: parts.join('').trim(), proposals: [...proposals.values()], failed, blocked };
+        if (parked)
+            return;
+        await flush(true);
+        if (failed)
+            await out.text(texts.failed, 'notice');
+        if (blocked)
+            await out.text(texts.blockingApproval, 'notice');
+        const left = [...proposals.values()];
+        for (const proposal of left)
+            await sendProposal(service, store, texts, out, conversation, proposal, left.length > 1);
     };
-    const handleMessage = async (service, message) => {
-        await adapter.acknowledge?.(message).catch(() => { });
-        const texts = textsFor(service);
+    const hookContext = (message) => ({
+        channel: name,
+        conversation: message.conversation,
+        message,
+    });
+    /** Before the turn: who is talking, and whether the app lets them through. */
+    const prepare = async (message) => {
+        const service = await serviceFor();
         const store = await storeFor(service);
+        await adapter.acknowledge?.(message).catch(() => { });
         const actor = await options.actor(message);
         if (actor === null) {
-            if (texts.unknownSender !== undefined)
-                await deliver(message.conversation, texts.unknownSender);
-            return;
+            const out = outbox(store, `${name}:out:msg:${message.id}:sender`, message.conversation, {
+                actor: null,
+                message,
+            });
+            const replies = options.unknownSender
+                ? replyList(await options.unknownSender(message, hookContext(message)))
+                : replyList((await textsFor(service, { actor: null, message })).unknownSender);
+            for (const reply of replies)
+                await out.reply(reply, 'gate');
+            return { stop: true };
+        }
+        const gate = await options.beforeTurn?.(message, actor, hookContext(message));
+        if (gate === 'stop')
+            return { stop: true };
+        if (gate !== undefined && gate !== 'continue') {
+            const out = outbox(store, `${name}:out:msg:${message.id}:gate`, message.conversation, {
+                actor,
+                message,
+            });
+            for (const reply of 'replies' in gate ? gate.replies : [gate.reply])
+                await out.reply(reply, 'gate');
+            return { stop: true };
         }
         const threadId = (await options.thread(actor, message)) ?? null;
+        return { stop: false, actor, threadId };
+    };
+    /**
+     * The message itself: an answer, a press, a decision, or a turn. Returns the run to read, if any.
+     * A turn is started once per message, however often this runs: its run id is kept under the
+     * message id before anything else can fail.
+     */
+    const act = async (received, actor, threadId) => {
+        const service = await serviceFor();
+        const store = await storeFor(service);
+        const turnKey = `${name}:turn:${received.id}`;
+        const started = await store.get(turnKey);
+        if (started !== null && started !== '') {
+            // This phase ran to its end before (a retry, a recovery): the same outcome.
+            return JSON.parse(started);
+        }
+        /** What this message came to, kept so a phase that runs again does not do it twice. */
+        const done = async (result) => {
+            await store.set(turnKey, JSON.stringify(result), dedupeTtlMs);
+            return result;
+        };
+        const texts = await textsFor(service, { actor, message: received });
+        const out = outbox(store, `${name}:out:msg:${received.id}`, received.conversation, {
+            actor,
+            message: received,
+        });
+        const recovered = await recoverButtonId(service, store, texts, actor, threadId, received);
+        const message = recovered === undefined ? received : { ...received, buttonId: recovered };
         const ours = message.buttonId !== undefined && BUTTON_ID.test(message.buttonId);
         if (!ours) {
             const waiting = await store.get(questionKey(message.conversation));
             const pending = waiting === null ? null : JSON.parse(waiting);
             if (pending !== null && (pending.threadId === null || pending.threadId === threadId)) {
-                await answerQuestion(service, store, actor, message, pending);
-                return;
+                const resume = await answerQuestion(service, store, texts, out, actor, message, pending);
+                if (resume !== 'expired')
+                    return done(resume === null ? null : { runId: resume, threadId: pending.threadId });
             }
         }
-        if (await pressButton(service, actor, threadId, message))
-            return;
-        const attachments = await attachMedia(service, actor, message);
+        if (await pressButton(service, out, actor, threadId, message))
+            return done(null);
+        const media = await attachMedia(service, texts, out, actor, message);
+        let inbound = {
+            text: [message.text, ...media.extra].filter((part) => part.trim() !== '').join('\n\n'),
+            attachments: media.refs,
+        };
+        if (options.transformInbound)
+            inbound = await options.transformInbound(inbound, {
+                ...hookContext(message),
+                actor,
+                threadId,
+            });
+        if (inbound.attachments.length === 0 &&
+            (await decideByText(service, store, texts, out, actor, threadId, message, inbound.text)))
+            return done(null);
         // A file nobody could attach, and no caption: there is nothing left to answer.
-        if (message.text === '' && attachments.length === 0)
-            return;
+        if (inbound.text === '' && inbound.attachments.length === 0)
+            return done(null);
+        if (!(await store.claim(turnKey, dedupeTtlMs))) {
+            // Taken by a run of this phase that died between starting the turn and recording it: never
+            // start a second turn for one message.
+            throw Object.assign(new Error(`[@adonis-agora/agent] channel ${name}: message ${message.id} may have started a turn already; not starting another`), { name: 'ChannelTurnUncertainError', status: 409 });
+        }
         const pageContext = typeof options.pageContext === 'function'
             ? options.pageContext(message)
-            : (options.pageContext ?? { kind: adapter.name });
-        const channel = { name: adapter.name, conversation: message.conversation };
-        const sent = await service.send({
-            actor,
-            message: message.text,
-            ...(threadId !== null ? { threadId } : {}),
-            ...(options.agentName !== undefined ? { agentName: options.agentName } : {}),
-            ...(attachments.length > 0 ? { attachments } : {}),
-            // Nothing is drawn: every component arrives as its text.
-            uiCapabilities: { components: [] },
-            pageContext: { ...pageContext, channel },
-            hostContext: {
-                channel: adapter.name,
-                conversation: message.conversation,
-                messageId: message.id,
-            },
-        });
-        if (threadId === null)
-            await options.onThreadCreated?.(sent.threadId, actor, message);
+            : (options.pageContext ?? { kind: name });
+        const channel = { name, conversation: message.conversation };
+        const sendOptions = { textDecisions: false };
+        let sent;
+        try {
+            sent = await service.send({
+                actor,
+                message: inbound.text,
+                ...(threadId !== null ? { threadId } : {}),
+                ...(options.agentName !== undefined ? { agentName: options.agentName } : {}),
+                ...(inbound.attachments.length > 0 ? { attachments: inbound.attachments } : {}),
+                uiCapabilities: options.uiCapabilities ?? { components: [] },
+                pageContext: { ...pageContext, channel },
+                hostContext: {
+                    channel: name,
+                    conversation: message.conversation,
+                    messageId: message.id,
+                },
+            }, sendOptions);
+        }
+        catch (error) {
+            // Nothing started: a retry may start it.
+            await Promise.resolve(store.delete(turnKey)).catch(() => { });
+            throw error;
+        }
         if ('proposalDecision' in sent) {
-            await deliver(message.conversation, sent.text);
+            // A service that decides by text itself (one that ignores `textDecisions`).
+            await done(null);
+            await out.text(sent.text, 'notice');
             const decided = sent.proposalDecision;
             if ('proposal' in decided &&
                 decided.status === 'applied' &&
                 decided.proposal?.decision === 'approved')
-                await relayOutcome(service, actor, sent.threadId, decided.proposal.id, message.conversation);
-            return;
+                await relayOutcome(service, actor, sent.threadId, decided.proposal.id, message);
+            return null;
         }
         // A queued message starts later under its own id: its answer is read the same way.
         const runId = sent.queued === true ? (sent.runId ?? sent.messageId) : sent.runId;
-        const turn = await readTurn(service, store, actor, runId, sent.threadId, message.conversation);
-        if (turn.text !== '')
-            await deliver(message.conversation, turn.text);
-        if (turn.failed)
-            await deliver(message.conversation, texts.failed);
-        if (turn.blocked)
-            await deliver(message.conversation, texts.blockingApproval);
-        for (const proposal of turn.proposals)
-            await sendProposal(service, message.conversation, proposal, turn.proposals.length > 1);
+        const turn = await done({ runId, threadId: sent.threadId });
+        if (threadId === null)
+            await options.onThreadCreated?.(sent.threadId, actor, message);
+        await options.onTurnStarted?.({
+            runId,
+            threadId: sent.threadId,
+            actor,
+            message,
+            queued: sent.queued === true,
+        });
+        return turn;
     };
-    const track = (work) => {
-        inFlight.add(work);
-        void work.finally(() => inFlight.delete(work));
+    const retry = (fn) => withRetries(fn, options.retry);
+    const report = (error, message) => {
+        if (options.onError && message !== null)
+            options.onError(error, message);
+        else
+            console.error('[@adonis-agora/agent] Channel message failed', {
+                channel: name,
+                message: error instanceof Error ? error.message : String(error),
+            });
     };
-    const handler = async (ctx) => {
-        const request = requestOf(ctx);
+    /** One job, phase by phase — each phase a checkpoint under a durable engine. */
+    const run = async (job, step) => {
+        const message = job.kind === 'message' ? job.message : null;
+        try {
+            if (job.kind === 'timeout') {
+                await step('timeout', () => retry(async () => {
+                    const service = await serviceFor();
+                    const store = await storeFor(service);
+                    // Answered in time: nothing to do.
+                    if (!(await settleQuestion(store, job.runId, job.toolCallId, 'timeout')))
+                        return false;
+                    // Nobody answered: the agent goes on on its own assumptions.
+                    const key = questionKey(job.conversation);
+                    const waiting = await store.get(key);
+                    const pending = waiting === null ? null : JSON.parse(waiting);
+                    if (pending?.runId === job.runId && pending.toolCallId === job.toolCallId)
+                        await store.delete(key);
+                    await service
+                        .skip({
+                        runId: job.runId,
+                        toolCallId: job.toolCallId,
+                        answeredByRef: job.actor.id,
+                        answeredVia: name,
+                    })
+                        .catch(() => { });
+                    await executor().enqueue({
+                        kind: 'resume',
+                        channel: name,
+                        conversation: job.conversation,
+                        runId: job.streamRunId,
+                        threadId: job.threadId,
+                        actor: job.actor,
+                    }, jobId(name, 'resume', job.runId, job.toolCallId));
+                    return true;
+                }));
+                return;
+            }
+            if (job.kind === 'resume') {
+                await step('read', () => retry(async () => {
+                    const service = await serviceFor();
+                    await readTurn(service, await storeFor(service), job.actor, job.runId, job.threadId, job.conversation, null);
+                    return null;
+                }));
+                return;
+            }
+            const received = job.message;
+            const prepared = await step('prepare', () => retry(() => prepare(received)));
+            if (prepared.stop)
+                return;
+            const turn = await step('act', () => retry(() => act(received, prepared.actor, prepared.threadId)));
+            if (turn === null)
+                return;
+            await step('read', () => retry(async () => {
+                const service = await serviceFor();
+                await readTurn(service, await storeFor(service), prepared.actor, turn.runId, turn.threadId, received.conversation, received);
+                return null;
+            }));
+        }
+        catch (error) {
+            if (error?.name === 'WorkflowSuspended')
+                throw error;
+            report(error, message);
+        }
+    };
+    let current;
+    /** Durable when an engine is there (given, or the agent's), else in this process. */
+    const executor = () => {
+        if (current)
+            return current;
+        const engine = options.durable === false
+            ? undefined
+            : typeof options.durable === 'object'
+                ? options.durable
+                : registeredAgentEngine();
+        if (engine === undefined && options.durable === true)
+            console.warn(`[@adonis-agora/agent] channel ${name}: \`durable: true\` but no durable engine is wired (\`durable: true\` in config/agent.ts) — messages are handled in this process`);
+        if (engine !== undefined) {
+            registerChannelWorkflows(engine, runnerFor);
+            current = durableExecutor(engine);
+            return current;
+        }
+        current = inlineExecutor((job) => run(job, (_name, fn) => fn()));
+        return current;
+    };
+    registry.set(name, {
+        adapter,
+        run,
+        relay: (proposal, conversation, service) => relay(proposal, conversation, service),
+    });
+    // Registered on the engine as soon as there is one: a restarted process resumes the jobs a crash
+    // interrupted only for workflows it knows.
+    if (typeof options.durable === 'object')
+        registerChannelWorkflows(options.durable, runnerFor);
+    else if (options.durable !== false)
+        followAgentEngine();
+    const notify = async (event) => {
+        try {
+            await options.onWebhook?.({ channel: name, ...event });
+        }
+        catch {
+            // Observation never changes the answer.
+        }
+    };
+    const handleRequest = async (request, logger) => {
+        const empty = { accepted: 0, duplicates: 0, messages: [] };
         const challenge = adapter.challenge?.(request) ?? null;
         if (challenge !== null) {
-            ctx.response
-                .status(challenge.status)
-                .header('content-type', challenge.contentType ?? 'text/plain')
-                .send(challenge.body);
-            return;
+            await notify({ status: 'challenge', ...empty });
+            return {
+                status: challenge.status,
+                body: challenge.body,
+                contentType: challenge.contentType ?? 'text/plain',
+            };
         }
         if (request.method !== 'POST') {
-            ctx.response.status(405).send({ error: 'method_not_allowed' });
-            return;
+            await notify({ status: 'method_not_allowed', ...empty });
+            return { status: 405, body: { error: 'method_not_allowed' } };
         }
         if (!(await adapter.verify(request))) {
-            ctx.response.status(401).send({ error: 'unauthorized' });
-            return;
+            await notify({ status: 'unauthorized', ...empty });
+            return { status: 401, body: { error: 'unauthorized' } };
         }
         const parsed = adapter.parse(request.body);
         const messages = parsed === null ? [] : Array.isArray(parsed) ? parsed : [parsed];
-        if (messages.length > 0) {
-            const service = options.service ??
-                (await ctx.containerResolver.make(AgentService));
-            const store = await storeFor(service);
-            const fresh = [];
-            // Claimed before the 200: a store that is down answers 500, and the provider retries.
-            for (const message of messages) {
-                if (await store.claim(`${adapter.name}:${message.id}`, dedupeTtlMs))
-                    fresh.push(message);
+        if (messages.length === 0) {
+            const ignored = adapter.ignored?.(request.body) ?? null;
+            const event = ignored?.event ??
+                (typeof request.body === 'object' && request.body !== null
+                    ? request.body.event
+                    : undefined);
+            const reason = ignored?.reason ?? 'no message';
+            // Logged with the event and the reason — never the content — so a dropped message can be
+            // diagnosed.
+            if (logger) {
+                const log = ignored?.unexpected ? logger.warn : logger.debug;
+                log?.call(logger, { channel: name, ...(typeof event === 'string' ? { event } : {}), reason }, 'channels: webhook ignored');
             }
-            for (const message of fresh) {
-                track(handleMessage(service, message).catch((error) => {
-                    if (options.onError)
-                        options.onError(error, message);
-                    else
-                        console.error('[@adonis-agora/agent] Channel message failed', {
-                            channel: adapter.name,
-                            message: error instanceof Error ? error.message : String(error),
-                        });
-                }));
+            await notify({
+                status: 'ignored',
+                reason,
+                ...(typeof event === 'string' ? { event } : {}),
+                ...empty,
+            });
+            return { status: 200, body: { ok: true } };
+        }
+        const fresh = [];
+        try {
+            const store = await storeFor(await serviceFor());
+            // Taken before the 200: a store or an engine that is down answers 500, and the provider
+            // retries.
+            for (const message of messages) {
+                const key = `${name}:${message.id}`;
+                if (!(await store.claim(key, dedupeTtlMs)))
+                    continue;
+                try {
+                    await executor().enqueue({ kind: 'message', channel: name, conversation: message.conversation, message }, jobId(name, 'message', message.id));
+                }
+                catch (error) {
+                    await Promise.resolve(store.delete(key)).catch(() => { });
+                    throw error;
+                }
+                fresh.push(message);
             }
         }
-        ctx.response.status(200).send({ ok: true });
+        catch (error) {
+            await notify({
+                status: 'failed',
+                reason: error instanceof Error ? error.message : String(error),
+                accepted: fresh.length,
+                duplicates: 0,
+                messages: fresh,
+            });
+            return { status: 500, body: { error: 'unavailable' } };
+        }
+        await notify({
+            status: fresh.length > 0 ? 'accepted' : 'duplicate',
+            accepted: fresh.length,
+            duplicates: messages.length - fresh.length,
+            messages: fresh,
+        });
+        return { status: 200, body: { ok: true } };
+    };
+    const handler = async (ctx) => {
+        const answer = await handleRequest(requestOf(ctx), ctx.logger);
+        if (answer.contentType !== undefined)
+            ctx.response
+                .status(answer.status)
+                .header('content-type', answer.contentType)
+                .send(answer.body);
+        else
+            ctx.response.status(answer.status).send(answer.body);
     };
     return Object.assign(handler, {
-        async drain() {
-            while (inFlight.size > 0)
-                await Promise.allSettled([...inFlight]);
-        },
+        drain: () => executor().drain(),
+        handleRequest: (request) => handleRequest(request),
     });
 }
+/**
+ * Relay an executed proposal's outcome to the conversation it was proposed in — once: the handler's
+ * own wait and this share a claim in the channel's store. `false` when it was not relayed (no
+ * channel recorded, the channel is not registered in this process, not executed, already relayed).
+ */
+async function deliverOutcome(proposal, service) {
+    const address = record(proposal.executionContext?.pageContext?.channel);
+    const channelName = typeof address?.name === 'string' ? address.name : undefined;
+    const conversation = typeof address?.conversation === 'string' ? address.conversation : undefined;
+    const registration = channelName === undefined ? undefined : registry.get(channelName);
+    if (!registration || conversation === undefined)
+        return false;
+    return registration.relay(proposal, conversation, service);
+}
 /**
  * `actionProposalWorker.onSettled` for text channels: relays an executed proposal's outcome to the
- * conversation it was proposed in, through the adapter registered under the recorded channel name.
- * Proposals from other surfaces are ignored. Safe next to the handler's own wait: an outcome is
- * relayed once.
+ * conversation it was proposed in, through the adapter registered under the recorded channel name
+ * (with its `formatOutcome`, `texts` and `canDeliver`). Proposals from other surfaces are ignored.
+ * Safe next to the handler's own wait: an outcome is relayed once.
  *
  * ```ts
  * // config/agent.ts