managed-deepagents 0.9.6-dev.2 → 0.9.6-dev.20

package/dist/channels/trigger/http.js

@@ -1,19 +1,24 @@
 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 { missingWorkspaceConnectionSlug, } from "../../agent-auth.js";
+import { resolveExternalPrincipalId } from "../../connections.js";
 import { DEFAULT_REACTION_EMOJI, resolveReactionEmoji, } from "../reactions.js";
 import { setLogAttributes } from "../../telemetry/otel/index.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, conversationThreadId, ingressThreadExists, ingressResumeTarget, 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 { normalizeUuid } from "./uuid.js";
+import { postReply, resolveChannelUser, } from "../resolve-user.js";
+import { createTriggerTransport } from "./transport.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
@@ -31,6 +36,37 @@ async function resolveEventPrincipal(event, verify) {
     }
     return await principalIdFromIdentityContext(token, verify);
 }
+/**
+ * The delivery's actor when Agent Auth keys it on the signed principal.
+ * Trigger Server does not sign `actor`, so one that does not match is dropped.
+ */
+async function verifiedEventActor(event, principalId, resolvePrincipal) {
+    const actor = triggerEventActor(event);
+    const team = slackInstallTeam(event.source_thread_key);
+    if (actor?.provider !== "slack" || !team)
+        return undefined;
+    try {
+        const resolved = await resolvePrincipal({
+            provider: "slack",
+            issuer: team,
+            subject: actor.id,
+        });
+        if (normalizeUuid(resolved) === principalId)
+            return actor;
+        logger.warn("channel actor does not match identity_context");
+    }
+    catch (error) {
+        logger.warn(`channel actor unverified (${logger.safeErrorLabel(error)})`);
+    }
+    return undefined;
+}
+/** The workspace the Slack app is installed in, which keys its users' principals. */
+function slackInstallTeam(sourceThreadKey) {
+    const [provider, version, , team] = sourceThreadKey.split(":");
+    return provider === "slack" && version === "v1"
+        ? nonblankString(team)
+        : undefined;
+}
 /** Validate one Trigger message, start its run, and enqueue observation. */
 export async function handleTriggerChannelEventRequest(request, options) {
     if (!request.headers.get(TRIGGER_SERVICE_KEY_HEADER)?.trim()) {
@@ -75,6 +111,12 @@ export async function handleTriggerChannelEventRequest(request, options) {
         channel_id: event.channel_id,
     });
     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);
+    }
+    const resolvePrincipal = options.resolvePrincipal ?? resolveExternalPrincipalId;
+    /** Who the delivery came from; never logged. */
+    const actor = await verifiedEventActor(event, userId, resolvePrincipal);
     let client = options.triggerClient;
     if (!client) {
         try {
@@ -98,10 +140,94 @@ 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 });
     }
+    let user;
+    try {
+        user = await resolveChannelUser(options.resolveUser, actor, options.channelName, event.delivery_id, resolvePrincipal);
+    }
+    catch (error) {
+        logger.error(`channel resolveUser failed (${logger.safeErrorLabel(error)})`);
+        return Response.json({ error: "channel user resolution failed" }, { status: 500 });
+    }
+    if (user?.type === "principal")
+        userId = user.id;
+    /** `resolveUser`'s answer when it holds back the run the delivery would start. */
+    const withheld = user?.type === "principal" ? undefined : user;
+    /** Post `resolveUser`'s reply, if any, instead of that run. */
+    const withhold = async () => {
+        if (withheld?.type === "reply")
+            await postReply(withheld.message, {
+                name: options.channelName,
+                provider: options.sourceProvider,
+                target: triggerTarget(event),
+                transport: createTriggerTransport(client, {
+                    actionId: event.delivery_id,
+                }),
+            });
+        logNoRun(event, { type: "skipped" });
+    };
+    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,
+    });
+    let threadId;
+    try {
+        threadId = await (options.conversationThread ?? conversationThreadId)({
+            sourceProvider: options.sourceProvider,
+            sourceThreadKey: event.source_thread_key,
+            userId,
+        });
+    }
+    catch (error) {
+        logger.error(`channel thread could not be found (${logger.safeErrorLabel(error)})`);
+        return Response.json({ error: "channel run could not be started" }, { status: 500 });
+    }
+    const thread = { id: threadId, 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 = {
-            threadId: triggerThreadId(event.source_thread_key),
+            threadId: thread.id,
             assistantId,
             sourceProvider: options.sourceProvider,
             sourceThreadKey: event.source_thread_key,
@@ -109,19 +235,113 @@ 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"));
+                    }
+                    if (withheld) {
+                        await withhold();
+                        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)})`, 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();
+            if (withheld) {
+                await withhold();
+                finishLater(skipped("ignored"));
+                return acceptedResponse(event);
+            }
+            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)({
+            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": {
+                if (withheld) {
+                    await withhold();
+                    return acceptedResponse(event);
+                }
+                // The answer may belong to a paused async subagent.
+                const target = await (options.resumeTarget ?? ingressResumeTarget)({
                     ...common,
-                    messages: options.messageInput?.(event) ?? event.input.messages,
+                    interruptIds: Object.keys(event.interaction.resume),
                 });
-                break;
-            case "interrupt_resume":
                 started = await (options.resumeAgent ?? resumeIngressAgent)({
                     ...common,
+                    ...target,
                     resume: event.interaction.resume,
                 });
                 break;
+            }
             case "user_prompt_response": {
                 const normalized = normalizedUserPromptResponse(event);
                 const interruptId = await interruptAnsweredBy({
@@ -132,16 +352,23 @@ 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) {
+                    if (withheld) {
+                        await withhold();
+                        return acceptedResponse(event);
+                    }
+                    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: {
@@ -157,23 +384,86 @@ export async function handleTriggerChannelEventRequest(request, options) {
             return acceptedResponse(event);
         }
         logger.error(`channel run could not be started (${logger.safeErrorLabel(error)})`, 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: await (options.conversationThread ?? conversationThreadId)({
+                sourceProvider: options.sourceProvider,
+                sourceThreadKey: event.source_thread_key,
+                userId,
+            }),
+            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 });
 }
@@ -201,27 +491,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`);
+    }
+    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 pending[0]?.id;
+    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({
@@ -233,46 +559,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;
@@ -310,7 +632,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,
@@ -321,19 +643,15 @@ 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) {
+export function missingConnectionFailureMessage(error) {
     const slug = missingWorkspaceConnectionSlug(String(error));
     if (slug === undefined) {
         return undefined;
     }
     return `This agent can't respond because the \`${slug}\` connection isn't configured. An agent developer can configure it with \`mda connections create ${slug} --project <project>\`, then try again.`;
 }
-function triggerThreadId(sourceThreadKey) {
-    return uuidv5(sourceThreadKey, uuidv5.URL);
-}
 function resolveAssistantId(override) {
     return override?.trim() || process.env[ASSISTANT_ID_ENV]?.trim() || undefined;
 }
@@ -357,8 +675,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