managed-deepagents 0.10.0-dev.16 → 0.10.0-dev.18

package/dist/channels/trigger/http.d.ts

@@ -1,10 +1,14 @@
-import type { ChannelBinding } from "../binding.js";
+import type { JsonValue } from "../types.js";
+import { type ChannelBinding } from "../binding.js";
 import { type ReactionChoice } from "../reactions.js";
 import { type ObservedIngressRun, type PendingInterrupt } from "./ingress.js";
-import type { StartedIngressRun } from "../../ingress/runs.js";
+import { type MultitaskStrategy, type StartedIngressRun } from "../../ingress/runs.js";
+import { type NormalizedRunInput } from "../run-input.js";
+import type { HttpChannelAdapter } from "../http/types.js";
 import { type TriggerClientLike } from "./client.js";
 import { type IdentityContextVerifyOptions } from "./identity-context.js";
-import { type TriggerChannelMessageEvent, type TriggerChannelResume } from "./types.js";
+import { type TriggerChannelMessageEvent, type TriggerChannelUserPromptResponseEvent, type TriggerChannelResume, type TriggerChannelRuntimeStatus } from "./types.js";
+import type { ChannelActor } from "../actor.js";
 export { TRIGGER_SERVICE_KEY_HEADER } from "./types.js";
 export declare const ASSISTANT_ID_ENV = "MDA_ASSISTANT_ID";
 type StartAgent = (input: {
@@ -16,6 +20,11 @@ type StartAgent = (input: {
     sourceProvider: string;
     sourceThreadKey: string;
     userId: string;
+    /** Other state keys to start with. */
+    state?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    webhook?: string;
+    multitaskStrategy?: MultitaskStrategy;
 }) => Promise<StartedIngressRun>;
 type ObserveAgent = (input: {
     threadId: string;
@@ -40,6 +49,53 @@ type ThreadInterrupts = (input: {
     sourceThreadKey: string;
     userId: string;
 }) => Promise<PendingInterrupt[]>;
+type NewerRun = (input: {
+    threadId: string;
+    runId: string;
+    sourceProvider: string;
+    sourceThreadKey: string;
+    userId: string;
+}) => Promise<boolean>;
+type ThreadExists = (input: {
+    threadId: string;
+    sourceProvider: string;
+    sourceThreadKey: string;
+    userId: string;
+}) => Promise<boolean>;
+/** The thread a message event belongs to, before any run exists. */
+export interface TriggerChannelThread {
+    id: string;
+    sourceThreadKey: string;
+}
+/**
+ * What a message event starts: the run input a provider's handler returned
+ * (`input`), no run (`skipped`), or nothing because the handler failed
+ * (`failed`).
+ */
+export type TriggerMessageDecision = {
+    type: "input";
+    input: NormalizedRunInput;
+} | {
+    type: "skipped";
+} | {
+    type: "failed";
+};
+/**
+ * What a provider decides a message starts: at once, or `background` for a
+ * decision that may take longer than Trigger Server waits, such as an event
+ * endpoint's. Trigger Server then gets its answer first, and a failure is
+ * only logged.
+ */
+export type TriggerMessageRoute = TriggerMessageDecision | {
+    type: "background";
+    decide: () => Promise<TriggerMessageDecision>;
+};
+type CancelThreadRuns = (input: {
+    threadId: string;
+    sourceProvider: string;
+    sourceThreadKey: string;
+    userId: string;
+}) => Promise<number>;
 export interface TriggerChannelHttpOptions {
     sourceProvider: string;
     channelName: string;
@@ -49,15 +105,70 @@ export interface TriggerChannelHttpOptions {
     startAgent?: StartAgent;
     resumeAgent?: ResumeAgent;
     threadInterrupts?: ThreadInterrupts;
+    threadExists?: ThreadExists;
+    /** Whether a newer run replaced a run on its thread; for tests. */
+    newerRun?: NewerRun;
     observeAgent?: ObserveAgent;
+    cancelRuns?: CancelThreadRuns;
     triggerClient?: TriggerClientLike;
     /** How to react to the message that starts a run. Defaults to `eyes`. */
     reactions?: ReactionChoice;
+    /**
+     * The status a run's `run.started` shows in place of Trigger Server's
+     * working phrases, and how.
+     */
+    startedStatus?: TriggerChannelRuntimeStatus;
     /** Provider hook for a message event's run input; defaults to `input.messages`. */
     messageInput?: (event: TriggerChannelMessageEvent) => Record<string, unknown>[];
+    /**
+     * Decide what a message event starts, before its run; `undefined` starts
+     * it with `messageInput`'s messages. Interrupt resumes never ask.
+     */
+    decideMessage?: (event: TriggerChannelMessageEvent, thread: TriggerChannelThread, 
+    /** Who sent it, when Trigger Server names them. */
+    actor?: ChannelActor) => Promise<TriggerMessageRoute | undefined>;
+    /**
+     * Decide what a prompt response that answers no interrupt starts, as
+     * `decideMessage` does a message; `undefined` starts a run with no new
+     * messages, which reads the response from `runtime.channel.event`.
+     */
+    decideInteraction?: (event: TriggerChannelUserPromptResponseEvent, thread: TriggerChannelThread, 
+    /** Who responded, when Trigger Server names them. */
+    actor?: ChannelActor) => Promise<TriggerMessageRoute | undefined>;
+    /**
+     * Whether a message may only continue a thread the agent already ran on:
+     * then, on a thread no run ever started on, it starts nothing, and
+     * `decideMessage` isn't asked.
+     */
+    onlyContinuesThread?: (event: TriggerChannelMessageEvent) => Promise<boolean>;
+    /**
+     * What a run a message or prompt response starts does to a run already
+     * active on its thread; `enqueue` when unset.
+     */
+    multitaskStrategy?: MultitaskStrategy;
+    /**
+     * A message, or a prompt response that answers no interrupt, is done, as
+     * `channels.http`'s `onFinish` hears it: the run it started ended (`run`), it started none (`skipped`: `ignored` or
+     * `rejected`), its run couldn't start after Trigger Server had its answer
+     * (`failed: start`), or MDA lost track of the run (`failed: observe`). The
+     * delivery's `rawEvent` is the {@link TriggerFinishedEvent}. Called once,
+     * after the reply and lifecycle callbacks, in the background; failures are
+     * logged. A message whose run couldn't start before Trigger Server's answer
+     * gets an error instead, and Trigger Server may deliver it again.
+     */
+    onFinish?: HttpChannelAdapter["onFinish"];
     /** Override identity-context JWKS verify (unit tests). */
     identityContext?: IdentityContextVerifyOptions;
 }
 /** Validate one Trigger message, start its run, and enqueue observation. */
 export declare function handleTriggerChannelEventRequest(request: Request, options: TriggerChannelHttpOptions): Promise<Response>;
+/**
+ * What a finished message's `rawEvent` holds: the Trigger delivery, without
+ * its identity token.
+ */
+export type TriggerFinishedEvent = {
+    delivery: JsonValue;
+    /** Who sent it, as Trigger Server named them. */
+    actor?: ChannelActor;
+};
 //# sourceMappingURL=http.d.ts.map

package/dist/channels/trigger/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/channels/trigger/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/channels/trigger/http.ts"],"names":[],"mappings":"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"}

package/dist/channels/trigger/http.js

@@ -1,18 +1,20 @@
 import { INTERRUPT } from "@langchain/langgraph";
-import { createTriggerTransport } from "./transport.js";
+import { bindingWithMessages } from "../binding.js";
 import { randomUUID } from "node:crypto";
 import { v5 as uuidv5 } from "uuid";
 import { missingWorkspaceConnectionSlug } from "../../agent-auth.js";
-import { extractAssistantText } from "../assistant-text.js";
 import { DEFAULT_REACTION_EMOJI, resolveReactionEmoji, } from "../reactions.js";
 import { logger } from "../../runtime/log.js";
 import { INTERRUPT_CORRELATION_KEY } from "../../run-context.js";
-import { ingressThreadInterrupts, observeIngressAgent, resumeIngressAgent, startIngressAgent, } from "./ingress.js";
+import { cancelIngressThreadRuns, ingressThreadExists, ingressThreadInterrupts, newerIngressRun, observeIngressAgent, resumeIngressAgent, startIngressAgent, } from "./ingress.js";
 import { scheduleIngressWork } from "../../ingress/index.js";
+import { lookupStatus, rejectedAsBusy, } from "../../ingress/runs.js";
+import { runStartOptions } from "../run-input.js";
 import { createTriggerClient, LANGSMITH_MDA_TRIGGER_SERVER_URL_ENV, TriggerClientError, } from "./client.js";
 import { IdentityContextUnavailableError, InvalidIdentityContextError, principalIdFromIdentityContext, } from "./identity-context.js";
 import { resolveTracerSessionId } from "./tracing-project.js";
-import { parseTriggerChannelEvent, triggerChannelBinding, TRIGGER_SERVICE_KEY_HEADER, normalizedUserPromptResponse, } from "./types.js";
+import { parseTriggerChannelEvent, triggerChannelBinding, TRIGGER_SERVICE_KEY_HEADER, normalizedUserPromptResponse, triggerEventActor, } from "./types.js";
+import { isRecord, nonblankString } from "../../values.js";
 export { TRIGGER_SERVICE_KEY_HEADER } from "./types.js";
 export const ASSISTANT_ID_ENV = "MDA_ASSISTANT_ID";
 // Raised when the thread cannot say which interrupt an answer belongs to. An
@@ -67,7 +69,15 @@ export async function handleTriggerChannelEventRequest(request, options) {
         }
         throw error;
     }
+    /**
+     * Who the delivery came from, as Trigger Server names them; never logged.
+     * Only as trusted as the service key, which is checked for presence alone.
+     */
+    const actor = triggerEventActor(event);
     logger.info(`Channel incoming event (type=${event.type}, event_id=${logger.logIdentifier(event.event_id)}, delivery_id=${logger.logIdentifier(event.delivery_id)}, channel_id=${logger.logIdentifier(event.channel_id)})`);
+    if (event.type === "run_cancel") {
+        return await cancelEventRuns(event, userId, options);
+    }
     let client = options.triggerClient;
     if (!client) {
         try {
@@ -91,6 +101,56 @@ export async function handleTriggerChannelEventRequest(request, options) {
         logger.error(`${ASSISTANT_ID_ENV} is not configured`);
         return Response.json({ error: "channel runtime is not configured" }, { status: 500 });
     }
+    const observe = (started) => observeAcceptedRun({
+        event,
+        started,
+        client,
+        observeAgent: options.observeAgent,
+        sourceProvider: options.sourceProvider,
+        sourceThreadKey: event.source_thread_key,
+        userId,
+        reactions: options.reactions ?? DEFAULT_REACTION_EMOJI,
+        ...(options.startedStatus && { startedStatus: options.startedStatus }),
+        multitaskStrategy: options.multitaskStrategy,
+        newerRun: options.newerRun,
+    });
+    const thread = {
+        id: triggerThreadId(event.source_thread_key),
+        sourceThreadKey: event.source_thread_key,
+    };
+    /**
+     * Whether the delivery starts a turn of its own, which finishes: a message,
+     * or a prompt response that answers no interrupt. Resumes don't.
+     */
+    let startsTurn = event.type === "message";
+    /** Tell the provider a turn is done, once; a failure is logged. */
+    const finish = async (finished) => {
+        if (!startsTurn || !options.onFinish)
+            return;
+        const { identity_context: _token, ...message } = event;
+        const raw = {
+            delivery: message,
+            // Strings only, so JSON as the delivery's `rawEvent` is.
+            ...(actor && { actor: { ...actor } }),
+        };
+        try {
+            await options.onFinish(triggerTarget(event), {
+                threadId: thread.id,
+                rawEvent: raw,
+                ...finished,
+            });
+        }
+        catch (error) {
+            logger.error(`channel finish notice failed (${logger.safeErrorLabel(error)})`);
+        }
+    };
+    const finishLater = (finished) => {
+        if (options.onFinish)
+            scheduleIngressWork(() => finish(finished), {
+                label: "Channel finish notice",
+                schedule: options.schedule,
+            });
+    };
     let started;
     try {
         const common = {
@@ -102,13 +162,87 @@ export async function handleTriggerChannelEventRequest(request, options) {
             context: {},
             binding: triggerChannelBinding(event, options.sourceProvider, options.channelName),
         };
+        /**
+         * Start the delivery's run as `route` decides: at once, in the
+         * background, or not at all. The answer for Trigger Server when it has
+         * one already, otherwise the run it started.
+         */
+        const decideAndStart = async (route, undecided) => {
+            /** Start the run; `undefined` when `reject` left the thread to its run. */
+            const startRun = async (input) => {
+                const strategy = options.multitaskStrategy;
+                try {
+                    return await (options.startAgent ?? startIngressAgent)({
+                        ...common,
+                        ...(input
+                            ? decidedRun(input, common.binding)
+                            : { messages: undecided() }),
+                        ...(strategy && { multitaskStrategy: strategy }),
+                    });
+                }
+                catch (error) {
+                    // A run already active on the thread keeps it under `reject`.
+                    if (rejectedAsBusy(strategy, error)) {
+                        logger.info(`channel ${event.type} rejected: its thread is busy (delivery_id=${logger.logIdentifier(event.delivery_id)})`);
+                        return undefined;
+                    }
+                    throw error;
+                }
+            };
+            if (route?.type === "background") {
+                // Trigger Server only waits briefly, so it hears first; a failure
+                // from here on is logged, and nothing redelivers the event.
+                scheduleIngressWork(async () => {
+                    const decided = await route.decide();
+                    if (decided.type !== "input") {
+                        logNoRun(event, decided);
+                        return finish(skipped("ignored"));
+                    }
+                    let run;
+                    try {
+                        run = await startRun(decided.input);
+                    }
+                    catch (error) {
+                        logger.error(`channel run could not be started (${logger.safeErrorLabel(error)})`);
+                        return finish({
+                            type: "failed",
+                            reason: "start",
+                            interrupts: [],
+                        });
+                    }
+                    await finish(run ? await observe(run) : skipped("rejected"));
+                }, { label: "Channel event decision", schedule: options.schedule });
+                return acceptedResponse(event);
+            }
+            if (route?.type === "skipped") {
+                logNoRun(event, route);
+                finishLater(skipped("ignored"));
+                return acceptedResponse(event);
+            }
+            // Trigger Server may deliver it again, which finishes on its own.
+            if (route?.type === "failed")
+                return startFailedResponse();
+            const run = await startRun(route?.input);
+            if (!run) {
+                finishLater(skipped("rejected"));
+                return acceptedResponse(event);
+            }
+            return run;
+        };
         switch (event.type) {
-            case "message":
-                started = await (options.startAgent ?? startIngressAgent)({
-                    ...common,
-                    messages: options.messageInput?.(event) ?? event.input.messages,
-                });
+            case "message": {
+                const message = event;
+                if (!(await mayStartIn(common, message, options))) {
+                    logger.info(`channel message started no run: the agent never ran on its thread (delivery_id=${logger.logIdentifier(message.delivery_id)})`);
+                    finishLater(skipped("ignored"));
+                    return acceptedResponse(message);
+                }
+                const outcome = await decideAndStart(await options.decideMessage?.(message, thread, actor), () => options.messageInput?.(message) ?? message.input.messages);
+                if (outcome instanceof Response)
+                    return outcome;
+                started = outcome;
                 break;
+            }
             case "interrupt_resume":
                 started = await (options.resumeAgent ?? resumeIngressAgent)({
                     ...common,
@@ -125,16 +259,19 @@ export async function handleTriggerChannelEventRequest(request, options) {
                     correlationId: normalized.correlation_id,
                     threadInterrupts: options.threadInterrupts,
                 });
-                started =
-                    interruptId === undefined
-                        ? await (options.startAgent ?? startIngressAgent)({
-                            ...common,
-                            messages: [],
-                        })
-                        : await (options.resumeAgent ?? resumeIngressAgent)({
-                            ...common,
-                            resume: { [interruptId]: normalized },
-                        });
+                if (interruptId !== undefined) {
+                    started = await (options.resumeAgent ?? resumeIngressAgent)({
+                        ...common,
+                        resume: { [interruptId]: normalized },
+                    });
+                    break;
+                }
+                // A fresh turn, which the provider may decide, and which finishes.
+                startsTurn = true;
+                const outcome = await decideAndStart(await options.decideInteraction?.(event, thread, actor), () => []);
+                if (outcome instanceof Response)
+                    return outcome;
+                started = outcome;
                 break;
             }
             default: {
@@ -150,23 +287,82 @@ export async function handleTriggerChannelEventRequest(request, options) {
             return acceptedResponse(event);
         }
         logger.error(`channel run could not be started (${logger.safeErrorLabel(error)})`);
-        return Response.json({ error: "channel run could not be started" }, { status: 500 });
+        return startFailedResponse();
     }
-    scheduleIngressWork(() => observeAcceptedRun({
-        event,
-        started,
-        client,
-        observeAgent: options.observeAgent,
-        sourceProvider: options.sourceProvider,
-        sourceThreadKey: event.source_thread_key,
-        userId,
-        reactions: options.reactions ?? DEFAULT_REACTION_EMOJI,
-    }), {
+    scheduleIngressWork(async () => finish(await observe(started)), {
         label: "Channel run observation",
         schedule: options.schedule,
     });
     return acceptedResponse(event);
 }
+/** Where a delivery's replies go, as the channel binding names it. */
+function triggerTarget(event) {
+    return {
+        channel_id: event.channel_id,
+        address: event.address,
+        source_thread_key: event.source_thread_key,
+    };
+}
+function skipped(reason) {
+    return { type: "skipped", reason, interrupts: [] };
+}
+/** Log an event that started no run; a failed handler logged its own error. */
+function logNoRun(event, decision) {
+    logger.info(`channel ${event.type} started no run (${decision.type === "failed" ? "its handler failed, " : ""}delivery_id=${logger.logIdentifier(event.delivery_id)})`);
+}
+/**
+ * A decided run's start options. Its messages replace the delivery's in the
+ * binding, as the run's own input; its context sits beside the binding.
+ */
+function decidedRun(input, binding) {
+    return {
+        ...runStartOptions(input),
+        binding: bindingWithMessages(binding, input.messages),
+        context: input.context ?? {},
+    };
+}
+function startFailedResponse() {
+    return Response.json({ error: "channel run could not be started" }, { status: 500 });
+}
+/**
+ * Stop the source thread's runs; each run's observer reports `run.cancelled`.
+ *
+ * Runs are cancelled as the thread's channel principal, so the managed owner
+ * filter confines the cancel to this source conversation.
+ */
+async function cancelEventRuns(event, userId, options) {
+    let cancelled;
+    try {
+        cancelled = await (options.cancelRuns ?? cancelIngressThreadRuns)({
+            threadId: triggerThreadId(event.source_thread_key),
+            sourceProvider: options.sourceProvider,
+            sourceThreadKey: event.source_thread_key,
+            userId,
+        });
+    }
+    catch (error) {
+        logger.error(`channel runs could not be cancelled (${logger.safeErrorLabel(error)})`);
+        return Response.json({ error: "channel runs could not be cancelled" }, { status: 500 });
+    }
+    logger.info(`Channel runs cancelled (count=${cancelled}, delivery_id=${logger.logIdentifier(event.delivery_id)})`);
+    return acceptedResponse(event);
+}
+/**
+ * Whether a message may start a run on its thread: always, unless it may only
+ * continue a thread the agent already ran on and none ran there. A failed
+ * lookup is logged and lets it start, as before the check.
+ */
+async function mayStartIn(common, event, options) {
+    if (!(await options.onlyContinuesThread?.(event)))
+        return true;
+    try {
+        return await (options.threadExists ?? ingressThreadExists)(common);
+    }
+    catch (error) {
+        logger.warn(`channel thread lookup failed; the message starts as before (${logger.safeErrorLabel(error)})`);
+        return true;
+    }
+}
 function acceptedResponse(event) {
     return Response.json({ status: "accepted", delivery_id: event.delivery_id }, { status: 202 });
 }
@@ -194,27 +390,63 @@ async function interruptAnsweredBy(input) {
         }
         return undefined;
     }
-    if (pending.length > 1) {
+    // A tool-call review is answered from its own prompt (`interrupt_resume`):
+    // a click on one of the agent's buttons, such as a rating, is no decision.
+    const answerable = pending.filter((candidate) => !isToolCallReview(candidate.value));
+    if (answerable.length > 1) {
         // Interrupt ids carry no ordering, so without a correlation id there is
         // nothing to choose by.
-        throw new AmbiguousInterruptError(`${pending.length} interrupts pending`);
+        throw new AmbiguousInterruptError(`${answerable.length} interrupts pending`);
     }
-    return pending[0]?.id;
+    if (answerable.length === 0 && pending.length > 0) {
+        // Starting a turn here would abandon the review.
+        throw new AmbiguousInterruptError("the thread waits on a tool-call review, which a click doesn't answer");
+    }
+    return answerable[0]?.id;
+}
+/** Whether an interrupt is a tool-call review, as `humanInTheLoopMiddleware` raises one. */
+function isToolCallReview(value) {
+    return isRecord(value) && Array.isArray(value.action_requests);
 }
 function interruptCorrelationId(value) {
     if (!isRecord(value))
         return undefined;
-    const id = value[INTERRUPT_CORRELATION_KEY];
-    return typeof id === "string" && id.trim() ? id : undefined;
+    return nonblankString(value[INTERRUPT_CORRELATION_KEY]);
 }
 async function observeAcceptedRun(input) {
     const { event, started, client } = input;
-    const lifecycle = async (type, interrupts, message) => {
+    const run = {
+        threadId: started.threadId,
+        runId: started.runId,
+        sourceProvider: input.sourceProvider,
+        sourceThreadKey: input.sourceThreadKey,
+        userId: input.userId,
+    };
+    // Only these strategies let a newer message cancel a run.
+    const replaceable = input.multitaskStrategy === "interrupt" ||
+        input.multitaskStrategy === "rollback";
+    /**
+     * A newer message's run took the thread over; it reports to Slack, so this
+     * run says nothing that would stop or fail the thread's status. It ended
+     * `interrupted`, as the HTTP channel reports a replaced run.
+     */
+    const replaced = () => {
+        logger.info(`channel run was replaced by a newer message (delivery_id=${logger.logIdentifier(event.delivery_id)}, run_id=${logger.logIdentifier(started.runId)})`);
+        return {
+            type: "run",
+            run: { id: started.runId, status: "interrupted" },
+            interrupts: [],
+        };
+    };
+    const lifecycle = async (type, message, status) => {
         logger.info(`Channel outgoing event (type=${type}, delivery_id=${logger.logIdentifier(event.delivery_id)}, channel_id=${logger.logIdentifier(event.channel_id)}, run_id=${logger.logIdentifier(started.runId)})`);
-        const request = runtimeEvent(type, event, started, interrupts, message, await resolveTracerSessionId());
+        const request = {
+            ...runtimeEvent(type, event, started, message, await resolveTracerSessionId()),
+            ...status,
+        };
         return bestEffort(client.postRuntimeEvent(event.channel_id, request));
     };
-    await lifecycle("run.started");
+    await lifecycle("run.started", undefined, input.startedStatus);
     // Not awaited here, so the reaction never delays the reply. The `finally`
     // settles it so it cannot outlive this work item.
     const reaction = reactToTriggerMessage({
@@ -226,46 +458,42 @@ async function observeAcceptedRun(input) {
     try {
         let observed;
         try {
-            observed = await (input.observeAgent ?? observeIngressAgent)({
-                threadId: started.threadId,
-                runId: started.runId,
-                sourceProvider: input.sourceProvider,
-                sourceThreadKey: input.sourceThreadKey,
-                userId: input.userId,
-            });
+            observed = await (input.observeAgent ?? observeIngressAgent)(run);
         }
         catch (error) {
-            await lifecycle("run.failed", undefined, missingConnectionFailureMessage(error));
-            return;
+            // `rollback` cancels, then deletes, the run a newer message replaced.
+            if (replaceable && lookupStatus(error) === 404)
+                return replaced();
+            await lifecycle("run.failed", missingConnectionFailureMessage(error));
+            return { type: "failed", reason: "observe", interrupts: [] };
+        }
+        const ended = (interrupts = []) => ({
+            type: "run",
+            run: { id: started.runId, status: observed.status },
+            interrupts: interrupts,
+        });
+        // Stopped from Slack or Studio: the run ended `interrupted`, with nothing
+        // waiting on a decision.
+        if (isCancelledRun(observed)) {
+            if (replaceable && (await wasReplaced(run, input.newerRun)))
+                return replaced();
+            await lifecycle("run.cancelled");
+            return ended();
         }
+        // The run reports its own pause and posts its own answer (../delivery.ts).
         if (isInterruptedRun(observed)) {
-            await lifecycle("run.interrupted", interruptEntries(observed.values).filter((entry) => isRecord(entry) &&
+            const interrupts = interruptEntries(observed.values).filter((entry) => isRecord(entry) &&
                 typeof entry.id === "string" &&
                 entry.id.trim().length > 0 &&
-                "value" in entry));
-            return;
+                "value" in entry);
+            return ended(interrupts);
         }
         if (observed.status !== "success") {
             await lifecycle("run.failed");
-            return;
-        }
-        const text = extractAssistantText(isRecord(observed.values) ? observed.values : {});
-        if (text) {
-            logger.info(`Channel outgoing action (type=post, delivery_id=${logger.logIdentifier(event.delivery_id)}, channel_id=${logger.logIdentifier(event.channel_id)}, run_id=${logger.logIdentifier(started.runId)})`);
-            const action = await bestEffort(createTriggerTransport(client, { actionId: event.event_id }).post({
-                message: { type: "content", content: text },
-                target: {
-                    channel_id: event.channel_id,
-                    address: event.address,
-                    source_thread_key: event.source_thread_key,
-                },
-            }));
-            if (action === undefined) {
-                await lifecycle("run.failed");
-                return;
-            }
+            return ended();
         }
         await lifecycle("run.completed");
+        return ended();
     }
     finally {
         await reaction;
@@ -303,7 +531,7 @@ async function reactToTriggerMessage(input) {
         reaction: { emoji, message_id: id },
     }));
 }
-function runtimeEvent(type, event, started, interrupts, message, tracerSessionId) {
+function runtimeEvent(type, event, started, message, tracerSessionId) {
     return {
         id: randomUUID(),
         type,
@@ -314,7 +542,6 @@ function runtimeEvent(type, event, started, interrupts, message, tracerSessionId
         run_id: started.runId,
         ...(tracerSessionId ? { tracer_session_id: tracerSessionId } : {}),
         ...(message ? { message: { text: message } } : {}),
-        ...(interrupts?.length ? { interrupts } : {}),
     };
 }
 function missingConnectionFailureMessage(error) {
@@ -350,8 +577,20 @@ async function bestEffort(promise) {
         return undefined;
     }
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+/** Whether a newer run replaced a cancelled one; a failed lookup says no. */
+async function wasReplaced(run, newerRun = newerIngressRun) {
+    try {
+        return await newerRun(run);
+    }
+    catch (error) {
+        logger.warn(`channel run lookup failed; the run counts as stopped (${logger.safeErrorLabel(error)})`);
+        return false;
+    }
+}
+function isCancelledRun(observed) {
+    // A cancelled run ends "interrupted" with nothing parked for a person to
+    // answer; reporting it as an interrupt would post an empty approval prompt.
+    return observed.status === "interrupted" && !hasInterrupt(observed.values);
 }
 function isInterruptedRun(observed) {
     // Agent Server can report status "success" after join while values still