@parall/parel-channel 1.40.0 → 1.41.0

package/src/fork.ts

@@ -0,0 +1,432 @@
+import type { ConnectorContext } from '@parel/plugin-sdk';
+import type { AgentEventWithChild, ChildSpawnFailedEvent } from './parel-sdk-compat.js';
+
+/**
+ * Fork-on-busy scheduling (the parall-side half of parel F4, parel-mono #140;
+ * strategy ownership per parel-session-alignment-plan.md §6 — the platform
+ * provides the spawnChildSession primitive, WHEN to fork is connector code).
+ *
+ * Model, mirroring the standard runtimes' fork-on-busy:
+ * - The main session is the single orchestrator. While it is mid-turn, a
+ *   message for a DIFFERENT conversation would head-of-line block behind it.
+ * - Instead, the connector spawns a fork child session (inherits main's
+ *   transcript at the last turn boundary — platform-guaranteed) keyed by an
+ *   opaque childRef, and routes that conversation's follow-ups to the child
+ *   via emitEvent deliverTo.
+ * - The child replies through the normal turn-end deliver (its envelopes
+ *   carry the same replyRoute shape), and its summary flows back to main via
+ *   the platform's async child notification. Same-conversation messages keep
+ *   riding main (steer/inject handles mid-turn arrival there).
+ *
+ * Busy tracking is BEST-EFFORT on the E1 turn stream (turn_started /
+ * turn_completed / turn_failed): a missed event mis-classifies busy vs idle,
+ * which costs a fork too many or a queued message too long — never
+ * correctness (F2 subject grouping guarantees turns don't mix conversations
+ * either way). Stale entries expire by TTL so a lost done event cannot wedge
+ * the classifier.
+ *
+ * Ack discipline: the spawn opening message — and any follow-up routed to
+ * the child before provisioning is confirmed — is NOT acked on emit; spawn
+ * failures come back asynchronously (child_spawn_failed) and an
+ * acked-but-never-processed message would be silently lost. Parked acks ride
+ * the child bookkeeping row and fire (by WorkItem id, re-sent a bounded
+ * number of times) on the child's observed events. On spawn failure the
+ * inbound layer arms an onTimer re-drive (FORK_RETRY_DELAY_MS) so the
+ * messages are re-planned promptly on a healthy long-lived connection —
+ * transient failures re-issue the SAME spawn ref (branch 1a), terminal ones
+ * re-plan from scratch (fresh ref or main).
+ */
+
+/** Main-session turn considered over after this long without a done event. */
+const MAIN_TURN_TTL_MS = 15 * 60 * 1000;
+
+/** A child with no observed activity for this long is considered gone. */
+const CHILD_TTL_MS = 10 * 60 * 1000;
+
+/** After a disabled/unsupported spawn failure, stop trying to fork for a while. */
+const FORK_DISABLED_TTL_MS = 60 * 60 * 1000;
+
+/** Delay before a failed spawn's messages are re-driven through onTimer. */
+export const FORK_RETRY_DELAY_MS = 15_000;
+
+/** Cap on un-acked follow-ups parked on an unconfirmed child. */
+const MAX_PENDING_FOLLOWUPS = 20;
+
+/** Stop re-sending acks after this many settle rounds. */
+const MAX_ACK_ATTEMPTS = 3;
+
+const MAIN_TURN_KEY = 'forkMainTurn';
+export const FORK_RETRY_PREFIX = 'forkRetry:';
+const FORK_DISABLED_KEY = 'forkDisabled';
+const childKey = (subject: string) => `forkChild:${subject}`;
+const childSubjectKey = (childRef: string) => `forkChildSubject:${childRef}`;
+
+interface MainTurnRow {
+  turnId: string;
+  subject?: string;
+  at: number;
+}
+
+export interface PendingAck {
+  dispatchId: string;
+  sourceId: string;
+}
+
+export interface ChildRow {
+  childRef: string;
+  at: number;
+  /**
+   * The opening message's replay identity — set at spawn and NEVER cleared
+   * while the row lives. pendingAcks can be dropped after MAX_ACK_ATTEMPTS,
+   * but a replay of the opening source must still match branch 1a (its input
+   * was a spawn payload, not an envelope — a deliverTo replay would bypass
+   * ingress dedupe and inject the user's first message twice).
+   */
+  openingSourceId?: string;
+  /**
+   * Un-acked WorkItems this child holds: the spawn opening dispatch plus any
+   * follow-ups routed to the child BEFORE its provisioning was confirmed (a
+   * deliverTo into a spawn that then fails terminally is ignored by the host
+   * — acking those up front would lose them). Acked (by WorkItem id) on the
+   * child's observed events; sourceIds double as replay identities (a swept
+   * dispatch whose sourceId appears here is one of these very messages).
+   * pendingAcks[0] is always the opening message.
+   */
+  pendingAcks?: PendingAck[];
+  /** Set on the child's first observed event — provisioning demonstrably done. */
+  confirmed?: boolean;
+  /** Ack re-send counter: acks are re-issued on later events until this hits
+   * MAX_ACK_ATTEMPTS (fetch effects are fire-and-forget; one lost ack must
+   * not orphan the WorkItem forever). */
+  ackAttempts?: number;
+}
+
+export type ForkDecision =
+  | { mode: 'main' }
+  /** trackAck: the child is not yet confirmed — the caller must park the
+   * WorkItem ack on the bookkeeping row instead of acking on emit. */
+  | { mode: 'deliverTo'; childRef: string; trackAck: boolean }
+  | { mode: 'spawn'; childRef: string };
+
+function isLive(at: unknown, ttl: number, now: number): boolean {
+  return typeof at === 'number' && now - at < ttl;
+}
+
+/**
+ * Decide how to route one inbound chat message. Called on the message hot
+ * path — store reads only, never a fetch.
+ *
+ * Concurrency: the decision-then-record sequence is NOT internally locked —
+ * it relies on the parel host executing one connection's hooks serially (the
+ * C3 contract; the same guarantee the turnEnvelope marker's read-then-patch
+ * ordering already leans on). Two same-chat dispatches therefore cannot both
+ * observe "no child" — the second runs after the first's recordSpawn.
+ */
+export async function planForkDecision(
+  ctx: ConnectorContext,
+  subject: string,
+  sourceId: string,
+): Promise<ForkDecision> {
+  const now = ctx.now();
+  const child = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  if (child?.childRef && isLive(child.at, CHILD_TTL_MS, now)) {
+    // 1a. A replay of the fork's own opening message: re-issue the spawn
+    //     with the SAME childRef. The platform spawn is idempotent (same ref
+    //     → same child, duplicate input suppressed, transient
+    //     concurrency_limit failures retry through) — this is both the retry
+    //     path for transient spawn failures and the duplicate-processing
+    //     guard (a deliverTo here would bypass ingress dedupe, the opening
+    //     input never was an envelope). Matched on the row-lifetime
+    //     openingSourceId, not pendingAcks — the acks list can be dropped
+    //     after bounded re-sends while replays must keep matching.
+    if (child.openingSourceId === sourceId) {
+      return { mode: 'spawn', childRef: child.childRef };
+    }
+    // 1b. An existing live child owns its conversation's follow-ups. Until
+    //     the child's first observed event confirms provisioning, follow-up
+    //     acks are parked on the row (a deliverTo into a terminally-failed
+    //     spawn is host-ignored — acking up front would lose the message).
+    return { mode: 'deliverTo', childRef: child.childRef, trackAck: child.confirmed !== true };
+  }
+  // 2. Forking disabled (binding opt-out observed) — everything rides main.
+  const disabled = (await ctx.store?.get(FORK_DISABLED_KEY).catch(() => null)) as {
+    at?: number;
+  } | null;
+  if (disabled && isLive(disabled.at, FORK_DISABLED_TTL_MS, now)) {
+    return { mode: 'main' };
+  }
+  // 3. Main mid-turn on a DIFFERENT conversation → fork. Same conversation
+  //    stays on main (inject-in-flight absorbs it there).
+  const turn = (await ctx.store?.get(MAIN_TURN_KEY).catch(() => null)) as MainTurnRow | null;
+  if (turn?.turnId && isLive(turn.at, MAIN_TURN_TTL_MS, now) && turn.subject !== subject) {
+    // now() suffix: a childRef is burned once its spawn fails terminally
+    // (platform mapping row is three-state), so a re-plan after a terminal
+    // failure must mint a fresh ref; retries of a still-pending spawn go
+    // through branch 1a with the recorded ref instead.
+    return { mode: 'spawn', childRef: `fk-${now.toString(36)}-${subject}` };
+  }
+  return { mode: 'main' };
+}
+
+/** Record a just-issued spawn so follow-ups route to the child. Idempotent
+ * for the 1a replay path: an existing row for the same ref keeps its parked
+ * follow-up acks and confirmation state, only refreshing liveness. */
+export async function recordSpawn(
+  ctx: ConnectorContext,
+  subject: string,
+  childRef: string,
+  opening: PendingAck,
+): Promise<void> {
+  const existing = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  const row: ChildRow =
+    existing?.childRef === childRef
+      ? { ...existing, at: ctx.now() }
+      : { childRef, at: ctx.now(), pendingAcks: [opening], openingSourceId: opening.sourceId };
+  await ctx.store?.set(childKey(subject), row).catch(() => {});
+  await ctx.store?.set(childSubjectKey(childRef), subject).catch(() => {});
+}
+
+/**
+ * Park a follow-up's WorkItem ack on an unconfirmed child. Returns false when
+ * the row is gone or the cap is hit — the caller then acks on emit (the cap
+ * bounds the loss window of a pathological never-confirming child; beyond it
+ * we prefer at-most-once for the tail over unbounded growth).
+ */
+export async function trackFollowUpAck(
+  ctx: ConnectorContext,
+  subject: string,
+  childRef: string,
+  ack: PendingAck,
+): Promise<boolean> {
+  const child = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  if (!child || child.childRef !== childRef) return false;
+  const acks = child.pendingAcks ?? [];
+  if (acks.some((a) => a.dispatchId === ack.dispatchId)) return true; // replay — already parked
+  if (acks.length >= MAX_PENDING_FOLLOWUPS) return false;
+  const row: ChildRow = { ...child, at: ctx.now(), pendingAcks: [...acks, ack] };
+  await ctx.store?.set(childKey(subject), row).catch(() => {});
+  return true;
+}
+
+/** Whether a childRef is still part of live fork bookkeeping. Late child
+ * callbacks after a New Session purge (or after give-up) must NOT recreate
+ * fork ase_ rows via the blind get-or-create — a pre-reset child's delayed
+ * trace/reply would attach a fresh session under the NEW conversation line. */
+export async function childRefKnown(ctx: ConnectorContext, childRef: string): Promise<boolean> {
+  const subject = (await ctx.store?.get(childSubjectKey(childRef)).catch(() => null)) as
+    | string
+    | null;
+  if (!subject) return false;
+  const child = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  return child?.childRef === childRef;
+}
+
+/** Whether a subject's live child has ever produced an observed event. */
+export async function childConfirmed(
+  ctx: ConnectorContext,
+  subject: string,
+  childRef: string,
+): Promise<boolean> {
+  const child = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  return child?.childRef === childRef && child.confirmed === true;
+}
+
+/** Drop one subject's fork routing (give-up path: message re-plans fresh). */
+export async function clearForkSubject(
+  ctx: ConnectorContext,
+  subject: string,
+  childRef: string,
+): Promise<void> {
+  const child = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  if (child?.childRef === childRef) {
+    await ctx.store?.delete(childKey(subject)).catch(() => {});
+  }
+  await ctx.store?.delete(childSubjectKey(childRef)).catch(() => {});
+}
+
+/**
+ * Bump-and-park a fork retry ledger row (also the spawn-verification
+ * coordinate onTimer re-plans). Returns the attempt count INCLUDING this one.
+ */
+export async function bumpForkRetryAttempts(
+  ctx: ConnectorContext,
+  retryKey: string,
+  data: Record<string, unknown>,
+): Promise<number> {
+  const prior = (await ctx.store?.get(retryKey).catch(() => null)) as {
+    attempts?: number;
+  } | null;
+  const attempts = (prior?.attempts ?? 0) + 1;
+  await ctx.store?.set(retryKey, { ...data, attempts }).catch(() => {});
+  return attempts;
+}
+
+/** Give up re-verifying a spawn after this many timer rounds. */
+export const MAX_SPAWN_VERIFY_ATTEMPTS = 3;
+
+/**
+ * Purge ALL fork routing state — called on `agent.new_session`. The binding
+ * reset rotates main's conversation line; stale child routing surviving it
+ * would deliver post-reset messages into pre-reset forks (old context), and
+ * a stale busy marker would fork off a session that no longer exists.
+ * Returns the childRefs that were live so the caller can also invalidate
+ * their cached ase_ rows.
+ */
+export async function clearForkState(ctx: ConnectorContext): Promise<string[]> {
+  const refs: string[] = [];
+  try {
+    // EVERY fork-scoped key deliberately shares the `fork` prefix
+    // (forkChild / forkChildSubject / forkMainTurn / forkDisabled /
+    // forkRetry) so this one list-and-delete purges the whole family — a
+    // surviving disabled latch would suppress F4 for an hour after a reset,
+    // and a surviving retry row would re-drive a pre-reset message into the
+    // fresh session. Keep new fork keys on the prefix.
+    const keys = (await ctx.store?.list('fork').catch(() => [])) ?? [];
+    for (const key of keys) {
+      if (key.startsWith('forkChildSubject:')) {
+        refs.push(key.slice('forkChildSubject:'.length));
+      }
+      await ctx.store?.delete(key).catch(() => {});
+    }
+  } catch {
+    // Best-effort: leftover rows expire by TTL anyway.
+  }
+  return refs;
+}
+
+/**
+ * Track main-session busyness from the E1 turn stream. Child events (they
+ * carry childRef) must NOT feed this — only the main session's turns do.
+ */
+export async function noteMainTurnEvent(
+  ctx: ConnectorContext,
+  event: AgentEventWithChild,
+): Promise<void> {
+  if (event.type === 'turn_started') {
+    const row: MainTurnRow = { turnId: event.turnId, subject: event.subject, at: ctx.now() };
+    await ctx.store?.set(MAIN_TURN_KEY, row).catch(() => {});
+    return;
+  }
+  if (event.type === 'turn_completed' || event.type === 'turn_failed') {
+    const turn = (await ctx.store?.get(MAIN_TURN_KEY).catch(() => null)) as MainTurnRow | null;
+    // Clear only the turn this done event belongs to — a stale done for a
+    // superseded turn must not mark a newer running turn idle.
+    if (!turn || turn.turnId === event.turnId) {
+      await ctx.store?.delete(MAIN_TURN_KEY).catch(() => {});
+    }
+  }
+}
+
+/**
+ * Resolve a child event's bookkeeping row (by its subject mirror) and fire
+ * the pending spawn ack exactly once. Returns the ack request when due.
+ */
+export async function settleChildEvent(
+  ctx: ConnectorContext,
+  event: AgentEventWithChild,
+): Promise<{ subject: string; pendingAcks: PendingAck[] } | null> {
+  const childRef = event.childRef;
+  if (!childRef) return null;
+  const subject =
+    event.subject ||
+    ((await ctx.store?.get(childSubjectKey(childRef)).catch(() => null)) as string | null) ||
+    '';
+  if (!subject) return null;
+  const child = (await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null;
+  if (!child || child.childRef !== childRef) {
+    // Unknown/superseded child — refresh nothing, ack nothing.
+    return { subject, pendingAcks: [] };
+  }
+  // Acks are re-issued on subsequent events (bounded) rather than cleared on
+  // first send: the ack rides a fire-and-forget fetch effect, and clearing
+  // eagerly would let one lost request orphan the WorkItem in `received`
+  // forever (its replay would then re-enter the child as a duplicate).
+  const acks = child.pendingAcks ?? [];
+  const attempts = (child.ackAttempts ?? 0) + 1;
+  const done = attempts >= MAX_ACK_ATTEMPTS;
+  const refreshed: ChildRow = {
+    childRef,
+    at: ctx.now(),
+    confirmed: true,
+    // openingSourceId survives the ack-list drop — replay identity is
+    // row-lifetime (see the field doc).
+    ...(child.openingSourceId ? { openingSourceId: child.openingSourceId } : {}),
+    ...(done ? {} : { pendingAcks: acks, ackAttempts: attempts }),
+  };
+  await ctx.store?.set(childKey(subject), refreshed).catch(() => {});
+  return { subject, pendingAcks: acks };
+}
+
+/**
+ * A spawn failed before the child ran. NEVER acks the opening dispatch — it
+ * stays received and the catch-up sweep re-plans it. Failure codes split
+ * three ways (parel §18.2 three-state mapping semantics):
+ * - `concurrency_limit` is TRANSIENT: the platform keeps the mapping in
+ *   `provisioning` and the same childRef can retry — keep the bookkeeping so
+ *   the sweep's replay re-issues the same spawn key (branch 1a) instead of
+ *   abandoning one provisioning row per attempt.
+ * - `disabled` / `unsupported_routing` are configuration-shaped: clear the
+ *   bookkeeping AND park a no-fork flag so the connector stops re-trying a
+ *   fork the binding will never allow.
+ * - Everything else is terminal for this childRef (the ref is burned): clear
+ *   the bookkeeping so the sweep's re-plan mints a fresh ref.
+ * Returns true when the bookkeeping was cleared (the caller then settles the
+ * orphaned child ase_).
+ */
+export async function handleChildSpawnFailed(
+  ctx: ConnectorContext,
+  event: ChildSpawnFailedEvent,
+): Promise<{ cleared: boolean; subject: string; pendingAcks: PendingAck[] }> {
+  console.error(
+    `[parel-channel] child spawn failed (${event.code}): ${event.error} (ref ${event.childRef})`,
+  );
+  const subject =
+    ((await ctx.store?.get(childSubjectKey(event.childRef)).catch(() => null)) as string | null) ??
+    '';
+  const child = subject
+    ? ((await ctx.store?.get(childKey(subject)).catch(() => null)) as ChildRow | null)
+    : null;
+  const pendingAcks = child?.childRef === event.childRef ? (child.pendingAcks ?? []) : [];
+  if (event.code === 'concurrency_limit') {
+    // Transient: the platform keeps the mapping in `provisioning` and the
+    // SAME childRef can retry — keep the bookkeeping; the caller's retry
+    // timer re-drives the opening message through branch 1a.
+    return { cleared: false, subject, pendingAcks };
+  }
+  if (subject) {
+    if (child?.childRef === event.childRef) {
+      await ctx.store?.delete(childKey(subject)).catch(() => {});
+    }
+    await ctx.store?.delete(childSubjectKey(event.childRef)).catch(() => {});
+  }
+  if (event.code === 'disabled' || event.code === 'unsupported_routing') {
+    await ctx.store?.set(FORK_DISABLED_KEY, { at: ctx.now() }).catch(() => {});
+  }
+  return { cleared: true, subject, pendingAcks };
+}
+
+/**
+ * Scope guard prepended to a fork child's opening input — the behavioral
+ * fallback agent-core applies to every forked dispatch (buildForkScopePrefix
+ * equivalent; the platform already excludes in-flight output from the seed,
+ * this line keeps the child from "finishing" main's visible work).
+ *
+ * The opening turn has no envelope (it starts from the spawn input), so its
+ * turn-end text is NOT auto-delivered anywhere (parel §18.3: outward replies
+ * from a child are the agent's own job) — the prefix therefore spells out
+ * the CLI reply command for THIS message; follow-ups arrive as deliverTo
+ * envelopes whose replies auto-deliver like any chat message.
+ */
+export function buildForkScopePrefix(subject: string, threadRootId?: string): string {
+  // Quoted-heredoc input form (mirrors agent-core's send hint): plain
+  // `--text "…"` lets the sandbox shell expand $, backticks and eat quotes —
+  // and this is the opening turn's ONLY delivery path.
+  const send = threadRootId
+    ? `parall messages send ${subject} --thread-root-id ${threadRootId} --text-file - <<'EOF'`
+    : `parall messages send ${subject} --text-file - <<'EOF'`;
+  return (
+    `[Fork scope: you are a parallel branch of your main session, handling ONE conversation (${subject}) only. ` +
+    `Act only on this conversation's request. Do not continue, complete, or produce output for other work visible in your inherited history — the main session owns it.]\n` +
+    `<system-reminder>Reply to THIS message with your sandbox CLI: \`${send}\` … \`EOF\` — the quoted heredoc keeps \`$\`, backticks and apostrophes literal. For this opening message your plain text output is NOT auto-delivered; later messages in this conversation deliver replies automatically.</system-reminder>\n\n`
+  );
+}

package/src/inbound-channel.ts

@@ -0,0 +1,256 @@
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+import { buildChannelPrompt } from './channel-prompt.js';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import {
+  ackEffect,
+  createChannelInputStep,
+  ensureSession,
+  invalidateSession,
+  markDispatchReceived,
+  patchSession,
+  REQUEST_TIMEOUT_MS,
+  TURN_ENVELOPE_KEY,
+} from './session.js';
+
+/**
+ * External IM inbound (channel_message dispatches — Feishu/Slack via the
+ * platform-mediated channel, external-im-channel-design.md). Split from
+ * inbound.ts as a pure move; the pipeline contract lives there.
+ */
+
+/**
+ * Miss-path lookups here are cosmetic (prompt labeling only), so they get a
+ * tight timeout — same 3s budget as deliver's front-of-reply session lookup —
+ * rather than holding the message's emit/ack behind the full
+ * REQUEST_TIMEOUT_MS. Also reused by inbound.ts's chat-name prefetch.
+ */
+export const PROVIDER_LOOKUP_TIMEOUT_MS = 3_000;
+
+/**
+ * channel_message dispatch → agent (external IM channel,
+ * external-im-channel-design.md). Same pipeline shape as the message path,
+ * with the ChannelConversation (chv_) standing in for the chat as the
+ * routing subject: fetch the durable ChannelMessage + its conversation,
+ * resolve the provider for prompt labeling (cached — the connection→provider
+ * mapping is stable), frame the prompt for the EXTERNAL audience, report
+ * progress against the conversation-keyed session, and ack by source.
+ *
+ * Error contract mirrors the message path (and agent-core's
+ * fetchAndHandleChannelMessage): 404/403 on the source entities is
+ * permanently unusable → ack-and-drop; a transient failure keeps the
+ * dispatch pending for the catch-up sweep.
+ */
+export async function effectsForChannelDispatch(
+  sourceId: string,
+  dispatchId: string,
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  const apiUrl = parallApiUrl(ctx);
+  const orgId = parallOrgId(ctx);
+  const authHeaders = { Authorization: `Bearer ${requireAgk(ctx)}` };
+  const get = (path: string, timeoutMs: number = REQUEST_TIMEOUT_MS) =>
+    fetch(`${apiUrl}/api/v1/orgs/${orgId}${path}`, {
+      headers: authHeaders,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+
+  const m = await get(`/channel-messages/${sourceId}`);
+  if (!m.ok) {
+    if (m.status === 404 || m.status === 403) {
+      // Deleted / inaccessible (also the shape a disabled org feature flag
+      // takes) — permanently unusable, drop it.
+      return [ackEffect(ctx, 'channel_message', sourceId)];
+    }
+    return []; // transient: keep pending, the catch-up sweep retries
+  }
+  const msg = (await m.json().catch(() => null)) as {
+    conversation_id?: string;
+    external_message_id?: string;
+    text?: string;
+    external_user_id?: string;
+    external_user_name?: string;
+    received_at?: string;
+  } | null;
+  const conversationId = msg?.conversation_id ? String(msg.conversation_id) : undefined;
+  const text = msg?.text ?? '';
+  if (!conversationId) {
+    // No conversation → no session key and no reply target: unusable.
+    return [ackEffect(ctx, 'channel_message', sourceId)];
+  }
+  if (!text) {
+    // The ingress adapter only persists mechanically parsed text; a row with
+    // none will never grow any (same reasoning as attachment-only chat
+    // messages) — drop rather than let it pile up in the pending queue.
+    return [ackEffect(ctx, 'channel_message', sourceId)];
+  }
+
+  const c = await get(`/channel-conversations/${conversationId}`);
+  if (!c.ok) {
+    if (c.status === 404 || c.status === 403) {
+      return [ackEffect(ctx, 'channel_message', sourceId)];
+    }
+    return [];
+  }
+  const conv = (await c.json().catch(() => null)) as {
+    connection_id?: string;
+    external_conversation_id?: string;
+    conversation_type?: string;
+  } | null;
+
+  // Provider (= clip alias) for prompt labeling + the reply hint.
+  // Best-effort: an unresolved provider degrades the wording, never blocks.
+  const connectionId = conv?.connection_id ? String(conv.connection_id) : undefined;
+  const provider = connectionId ? await resolveChannelProvider(ctx, connectionId, get) : undefined;
+
+  const senderName = msg?.external_user_name || msg?.external_user_id || 'external user';
+  const externalConversationId = conv?.external_conversation_id
+    ? String(conv.external_conversation_id)
+    : undefined;
+  const externalMessageId = msg?.external_message_id ? String(msg.external_message_id) : undefined;
+
+  // Progress reporting — identical ordering contract to the message path
+  // (see the comments there): received settles before the ack effect is
+  // returned; the turnEnvelope marker goes down before any session write.
+  const receivedSettled = markDispatchReceived(ctx, 'channel_message', sourceId);
+  const envelopeId = dispatchId || `channel_message:${sourceId}`;
+  let sessionId = await ensureSession(ctx);
+  if (sessionId) {
+    await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => {});
+    const report = (sid: string) =>
+      Promise.all([
+        patchSession(ctx, sid, { status: 'active', trigger_message_id: sourceId }),
+        createChannelInputStep(ctx, sid, {
+          conversationId,
+          channelMessageId: sourceId,
+          provider,
+          externalConversationId,
+          senderId: msg?.external_user_id ? String(msg.external_user_id) : 'external',
+          senderName,
+          text,
+          sentAt: msg?.received_at ? String(msg.received_at) : undefined,
+        }),
+      ]);
+    const results = await report(sessionId);
+    if (results.includes('stale')) {
+      await invalidateSession(ctx);
+      const fresh = await ensureSession(ctx);
+      if (fresh && fresh !== sessionId) {
+        await report(fresh);
+        sessionId = fresh;
+      }
+    }
+    // Record the durable chv_ ↔ ase_ mapping (ops drill-down from a
+    // conversation into its session; last-write-wins on the server). Only on
+    // change — the store remembers what was last pushed — and fully
+    // fire-and-forget: pure bookkeeping must never add latency to the
+    // emit/ack path (a lost attempt is retried on the next message because
+    // the store memo only updates on success).
+    void recordConversationSession(ctx, conversationId, sessionId).catch(() => {});
+  }
+  await receivedSettled;
+
+  return [
+    {
+      type: 'emitEvent',
+      event: {
+        id: envelopeId,
+        orgId,
+        connectionId: ctx.connectionId,
+        source: 'parall',
+        // The host's message intake path turns data.text into the user
+        // message — the external-audience framing rides inside it (parel has
+        // no separate prompt channel), so 'message' is the right type here.
+        type: 'message',
+        // main routing sends this to the agent's one session too; subject
+        // still carries the external conversation (chv_) for parel's turn
+        // input grouping (F2) and per-conversation event correlation.
+        subject: conversationId,
+        data: {
+          text: buildChannelPrompt({
+            provider,
+            conversationType: conv?.conversation_type ? String(conv.conversation_type) : undefined,
+            externalConversationId,
+            externalMessageId,
+            senderName,
+            text,
+          }),
+          conversationId,
+          channelMessageId: sourceId,
+          provider,
+          externalConversationId,
+          externalMessageId,
+        },
+        // No chatId on purpose: the reply goes out through the provider clip
+        // (agent-invoked), NOT deliver() — deliver only runs the redundant
+        // session idle for channel routes (see delivery.ts).
+        replyRoute: {
+          kind: 'provider_http',
+          connectionId: ctx.connectionId,
+          data: { conversationId, envelopeId },
+        },
+        // No invocation context: PRLL_CHAT_ID must not point CLI defaults at
+        // a chat that doesn't exist, and the reply targets (external ids)
+        // already ride the prompt verbatim.
+      },
+    },
+    ackEffect(ctx, 'channel_message', sourceId),
+  ];
+}
+
+/**
+ * connection id → provider alias, cached in the durable store (stable
+ * mapping; avoids one connection fetch per inbound message). Cache hits are
+ * a store read; any failure returns undefined — prompt wording degrades to
+ * neutral rather than inventing a clip alias.
+ */
+async function resolveChannelProvider(
+  ctx: ConnectorContext,
+  connectionId: string,
+  get: (path: string, timeoutMs?: number) => Promise<Response>,
+): Promise<string | undefined> {
+  const cacheKey = `channelProvider:${connectionId}`;
+  const cached = await ctx.store?.get(cacheKey).catch(() => null);
+  if (typeof cached === 'string' && cached) return cached;
+  try {
+    const res = await get(`/channel-connections/${connectionId}`, PROVIDER_LOOKUP_TIMEOUT_MS);
+    if (!res.ok) return undefined;
+    const body = (await res.json().catch(() => null)) as { provider?: string } | null;
+    const provider = body?.provider ? String(body.provider) : undefined;
+    if (provider) await ctx.store?.set(cacheKey, provider).catch(() => {});
+    return provider;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Push the chv_ → ase_ pointer when it changed; warn-only on failure. */
+async function recordConversationSession(
+  ctx: ConnectorContext,
+  conversationId: string,
+  sessionId: string,
+): Promise<void> {
+  const mappedKey = `convSession:${conversationId}`;
+  const mapped = await ctx.store?.get(mappedKey).catch(() => null);
+  if (mapped === sessionId) return;
+  try {
+    const res = await fetch(
+      `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/channel-conversations/${conversationId}/session`,
+      {
+        method: 'PATCH',
+        headers: {
+          Authorization: `Bearer ${requireAgk(ctx)}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ agent_session_id: sessionId }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      },
+    );
+    if (!res.ok) {
+      console.warn(`[parel-channel] conversation session mapping failed (${res.status})`);
+      return;
+    }
+    await ctx.store?.set(mappedKey, sessionId).catch(() => {});
+  } catch (err) {
+    console.warn('[parel-channel] conversation session mapping failed', err);
+  }
+}