@parall/parel-channel 1.40.0 → 1.41.0

package/src/inbound.ts

@@ -5,20 +5,53 @@ import type {
   ConnectorEffect,
   WebSocketFrame,
 } from '@parel/plugin-sdk';
-import { buildChannelPrompt, buildChatPrompt } from './channel-prompt.js';
-import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { buildChatPrompt, type PromptAttachment } from './channel-prompt.js';
+import { parallApiUrl, parallOrgId, requireAgk, sandboxEnabled } from './connect.js';
+import { effectsForChannelDispatch, PROVIDER_LOOKUP_TIMEOUT_MS } from './inbound-channel.js';
 import {
-  createChannelInputStep,
+  buildForkScopePrefix,
+  bumpForkRetryAttempts,
+  childConfirmed,
+  childRefKnown,
+  clearForkState,
+  clearForkSubject,
+  FORK_RETRY_DELAY_MS,
+  FORK_RETRY_PREFIX,
+  handleChildSpawnFailed,
+  MAX_SPAWN_VERIFY_ATTEMPTS,
+  noteMainTurnEvent,
+  planForkDecision,
+  recordSpawn,
+  settleChildEvent,
+  trackFollowUpAck,
+} from './fork.js';
+import {
+  type AgentEventWithChild,
+  asChildSpawnFailed,
+  asConnectorEffects,
+  type ExtendedConnectorEffect,
+} from './parel-sdk-compat.js';
+import {
+  ackByIdEffect,
+  ackEffect,
+  conversationKey,
   createErrorStep,
+  fetchMainSessionFresh,
   createInputStep,
   createTraceStep,
+  createTypedInputStep,
+  ensureChildSession,
   ensureSession,
+  invalidateChildSession,
   invalidateSession,
   markDispatchReceived,
   patchSession,
+  reportingEnabled,
   REQUEST_TIMEOUT_MS,
+  SESSION_CACHE_KEY,
   TURN_ENVELOPE_KEY,
 } from './session.js';
+import { isTypedEventType, planTypedDispatch } from './typed-dispatch.js';
 
 /**
  * Inbound path: Parall dispatches → agent.
@@ -39,21 +72,72 @@ import {
  * conversations) and mirrors it on agent events for per-chat correlation.
  * Ack-on-emit matches channel-slack-socket.
  *
- * Scope: `source_type === "message"` dispatches (DMs and mentions) and
+ * Scope: `source_type === "message"` dispatches (DMs and mentions),
  * `source_type === "channel_message"` dispatches (external IM — Feishu/Slack
- * via the platform-mediated channel, keyed by their ChannelConversation) are
- * emitted. Task/schedule/trigger dispatches stay pending rather than being
- * acked-and-dropped.
+ * via the platform-mediated channel, keyed by their ChannelConversation),
+ * and the typed dispatch family (task_assign / task_update / task_comment /
+ * wiki_comment / schedule.fire / external_trigger / approval_decided — see
+ * typed-dispatch.ts) are all consumed. Unknown future event types stay
+ * pending rather than being acked-and-dropped.
  */
 
 interface DispatchData {
   id?: unknown;
+  event_type?: unknown;
   source_type?: unknown;
   source_id?: unknown;
   chat_id?: unknown;
+  task_id?: unknown;
+  actor_id?: unknown;
+  delivery_reason?: unknown;
+}
+
+/**
+ * Connection-local hook serialization. The parel ConnectorHost dispatches
+ * socket callbacks fire-and-forget (verified against connector-host.ts:
+ * `onMessage: (data) => { this.handleMessage(data).catch(…) }`), so two
+ * frames' async handling can interleave at await points inside one DO
+ * isolate. Every read-then-write protocol here — the turnEnvelope marker,
+ * fork planForkDecision→recordSpawn, pendingAck parking — assumes serial
+ * execution, so ALL hook bodies run through this one promise chain. Same
+ * connection ⇒ same DO isolate ⇒ same module instance, so a module-level
+ * chain is exactly connection-scoped TODAY — if parel ever pools multiple
+ * connections into one isolate, key this chain on ctx.connectionId before
+ * anything else (cross-connection head-of-line blocking would be silent).
+ * Failures don't break the chain.
+ */
+let hookChain: Promise<unknown> = Promise.resolve();
+let chainConnectionId: string | undefined;
+/** Surface a violated isolation assumption as a log line, not silent
+ * mis-serialization (see the chain doc above). */
+export function assertChainConnection(ctx: ConnectorContext): void {
+  if (chainConnectionId === undefined) {
+    chainConnectionId = ctx.connectionId;
+  } else if (chainConnectionId !== ctx.connectionId) {
+    console.warn(
+      `[parel-channel] hook chain saw a second connection (${chainConnectionId} → ${ctx.connectionId}) — the one-connection-per-isolate assumption broke; key the chain on connectionId`,
+    );
+    chainConnectionId = ctx.connectionId;
+  }
+}
+export function serialized<T>(fn: () => Promise<T>): Promise<T> {
+  const next = hookChain.then(fn, fn);
+  hookChain = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  return next;
+}
+
+export function handleParallFrame(
+  frame: WebSocketFrame,
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  assertChainConnection(ctx);
+  return serialized(() => handleParallFrameInner(frame, ctx));
 }
 
-export async function handleParallFrame(
+async function handleParallFrameInner(
   frame: WebSocketFrame,
   ctx: ConnectorContext,
 ): Promise<ConnectorEffect[]> {
@@ -64,6 +148,22 @@ export async function handleParallFrame(
   } catch {
     return [];
   }
+  if (event.type === 'agent.new_session') {
+    // New Session rotated the main conversation line (server-driven binding
+    // reset). Stale fork routing surviving it would deliver post-reset
+    // messages into pre-reset children (old context) or fork off a busy
+    // marker for a session that no longer exists — purge it all, and drop
+    // the cached fork ase_ rows so the next event resolves fresh ones.
+    try {
+      const refs = await clearForkState(ctx);
+      for (const ref of refs) {
+        await invalidateChildSession(ctx, ref);
+      }
+    } catch (err) {
+      console.error('[parel-channel] new-session fork purge failed', err);
+    }
+    return [];
+  }
   if (event.type !== 'dispatch.new' || !event.data) return [];
   try {
     return await effectsForDispatch(event.data, ctx);
@@ -75,21 +175,100 @@ export async function handleParallFrame(
   }
 }
 
+/**
+ * Fork retry timers (armed by child_spawn_failed): re-plan the stranded
+ * message through the normal dispatch pipeline. onTimer returns the FULL
+ * effect union (unlike onAgentEvent), so the re-plan can emit/spawn/ack.
+ * The parked row is cleared first — a re-plan that fails transiently leaves
+ * the WorkItem in `received` for the reconnect sweep, same as any dispatch.
+ */
+export function handleParallTimer(
+  timer: { key: string },
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  return serialized(() => handleParallTimerInner(timer, ctx));
+}
+
+async function handleParallTimerInner(
+  timer: { key: string },
+  ctx: ConnectorContext,
+): Promise<ConnectorEffect[]> {
+  if (!timer.key.startsWith(FORK_RETRY_PREFIX)) return [];
+  const parked = (await ctx.store?.get(timer.key).catch(() => null)) as DispatchData | null;
+  if (!parked?.source_id) return [];
+  // Re-planning is idempotent on every path — an already-acked opening hits
+  // the confirmed branch (ack re-send, harmless), an unconfirmed one bumps
+  // the bounded verification counter, deliverTo replays dedupe on envelope
+  // id — so the timer re-drives unconditionally.
+  try {
+    const effects = await effectsForDispatch(parked, ctx);
+    // The parked row's only live purpose is the attempts counter across
+    // verification rounds — signaled by the re-plan re-arming THIS key. Any
+    // other outcome (confirmed ack / deliverTo / main / give-up) resolved
+    // the message, and the row would otherwise leak forever (no TTL).
+    const rearmed = effects.some(
+      (e) => e.type === 'setTimer' && (e as { key?: string }).key === timer.key,
+    );
+    if (!rearmed) await ctx.store?.delete(timer.key).catch(() => {});
+    return effects;
+  } catch (err) {
+    console.error('[parel-channel] fork retry re-plan failed', err);
+    return [];
+  }
+}
+
 /**
  * Sweep pending dispatches on (re)connect — the live WS push has no replay.
  * Paginates with the server cursor so a long outage's backlog is not silently
  * truncated (bounded to keep a pathological backlog from wedging onOpen; the
  * remainder is picked up on the next reconnect sweep).
  */
-export async function catchUpParall(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
+export function catchUpParall(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
+  return serialized(() => catchUpParallInner(ctx));
+}
+
+async function catchUpParallInner(ctx: ConnectorContext): Promise<ConnectorEffect[]> {
+  // New Session generation check (must run before any dispatch replay): the
+  // `agent.new_session` WS push is not replayed, so a reset that happened
+  // while this connection was down would leave stale fork routing behind —
+  // post-reset messages would land in pre-reset children. The main ase_ IS
+  // the generation: New Session closes it and the next get-or-create mints a
+  // fresh id, so compare the cached id against the server's current one and
+  // purge fork state on rotation. Every missed-event scenario passes through
+  // onOpen (a live socket delivers the event; a dead one reconnects here).
+  // The cached id is never dropped before the fresh (bypass-cache) read
+  // succeeds — it is the only generation token, and losing it to a transient
+  // /sessions failure would silently skip the purge until the fork TTLs
+  // expire.
+  try {
+    const cachedMain = (await ctx.store?.get(SESSION_CACHE_KEY).catch(() => null)) as string | null;
+    if (cachedMain) {
+      const freshMain = await fetchMainSessionFresh(ctx);
+      if (freshMain && freshMain !== cachedMain) {
+        const refs = await clearForkState(ctx);
+        for (const ref of refs) {
+          await invalidateChildSession(ctx, ref);
+        }
+        console.warn('[parel-channel] main session rotated while offline — fork state purged');
+      }
+    }
+    // Capability revalidation: a parked forkDisabled latch reflects the
+    // binding shape at failure time; the fleet sweep converges bindings
+    // without restarting the connection, so a reconnect is the natural
+    // revalidation point. If forking is truly still disabled, the first
+    // spawn attempt re-parks the latch at the cost of one failed effect.
+    await ctx.store?.delete('forkDisabled').catch(() => {});
+  } catch (err) {
+    console.error('[parel-channel] new-session generation check failed', err);
+  }
   const effects: ConnectorEffect[] = [];
   try {
     const apiUrl = parallApiUrl(ctx);
     const agk = requireAgk(ctx);
     const orgId = parallOrgId(ctx);
     let cursor = '';
-    // Page bound is a wedge guard, not a coverage target. Non-message
-    // dispatches stay pending (deliberately — see effectsForDispatch) and the
+    // Page bound is a wedge guard, not a coverage target. Unknown dispatch
+    // types stay pending (deliberately — see effectsForDispatch) and the
     // list is FIFO, so the bound must comfortably exceed any realistic
     // unsupported backlog or old rows could starve newer DMs out of the sweep.
     // 40 pages ≈ 2000 dispatches per sweep; log when we hit the ceiling so a
@@ -151,11 +330,30 @@ async function effectsForDispatch(
     // lives on the provider, not in a Parall chat).
     return effectsForChannelDispatch(sourceId, dispatchId, ctx);
   }
-  // Non-message dispatches (task_assign, schedule.fire, …) stay PENDING on
-  // purpose: they are meaningful work a future connector version will handle,
-  // and acking would silently drop it. Message dispatches that can NEVER
-  // become processable are acked-and-dropped below instead, so the pending
-  // queue (and the reconnect catch-up sweep) is bounded by real future work.
+  const eventType = String(data.event_type ?? '');
+  if (sourceId && isTypedEventType(eventType)) {
+    // Legacy configs without parallAgentId predate the whole reporting
+    // surface AND the typed handlers' stale guards (planTask compares the
+    // assignee against it) — emitting there would deliver reassigned tasks
+    // and record nothing. Keep typed work pending until the connection is
+    // redeployed on the current shape (same posture as unknown types).
+    if (!reportingEnabled(ctx)) {
+      return [];
+    }
+    // Conversational-only deployments (no sandbox → no `parall` CLI) cannot
+    // act on CLI-only typed work — emitting AND acking it would silently
+    // consume real work. Keep it pending (same posture as unknown types);
+    // approval_decided is exempt (it lives in a chat, replies auto-deliver).
+    if (!sandboxEnabled(ctx) && eventType !== 'approval_decided') {
+      return [];
+    }
+    return effectsForTypedDispatch(data, ctx);
+  }
+  // Unknown non-message dispatches stay PENDING on purpose: they are
+  // meaningful work a future connector version will handle, and acking would
+  // silently drop it. Message dispatches that can NEVER become processable
+  // are acked-and-dropped below instead, so the pending queue (and the
+  // reconnect catch-up sweep) is bounded by real future work.
   if (sourceType !== 'message' || !sourceId) return [];
   if (!chatId) {
     // A message dispatch with no chat can never be routed or replied to.
@@ -183,27 +381,252 @@ async function effectsForDispatch(
     content?: { text?: string };
     thread_root_id?: string;
     sender_id?: string;
+    attachments?: Array<{
+      id?: string;
+      file_name?: string;
+      file_size?: number;
+      mime_type?: string;
+    }>;
   } | null;
   const text = msg?.content?.text ?? '';
   // A thread reply anchors the agent's answer to the same thread.
   const threadRootId = msg?.thread_root_id || undefined;
-  if (!text) {
-    // Attachment-only / empty-text messages never grow text — MVP has no
-    // attachment path, so ack-and-drop rather than let them pile up in the
-    // pending queue forever.
+  // Attachments render as reference lines — the agent knows they exist and
+  // pulls the bytes itself via its sandbox CLI (standard-runtime contract).
+  const attachments: PromptAttachment[] = (msg?.attachments ?? [])
+    .filter((a) => typeof a?.id === 'string' && a.id)
+    .map((a) => ({
+      id: String(a.id),
+      fileName: String(a.file_name ?? ''),
+      fileSize: typeof a.file_size === 'number' ? a.file_size : 0,
+      mimeType: String(a.mime_type ?? ''),
+    }));
+  if (!text && attachments.length === 0) {
+    // Truly empty messages never grow content — ack-and-drop rather than let
+    // them pile up in the pending queue forever. (Attachment-only messages
+    // used to take this path; they now ride the attachment lines instead.)
     return [ackEffect(ctx, sourceType, sourceId)];
   }
 
-  // Progress reporting (best-effort, parall-runtime-indicator-plan.md §3):
-  // received lights the pending ring, the active+trigger patch arms the done
-  // signal, the input step flips the ring to processing. received MUST settle
-  // before this function returns — the ack effect below moves the dispatch
-  // row out of 'pending', and MarkReceived only transitions pending rows.
-  // It is deliberately NOT gated on the session resolving: it only touches
-  // the dispatch row, and a transient session failure must not also cost the
-  // pending ring (a later successful turn's idle clears agent-level pendings).
-  const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
+  // Frame the message with its chat of origin: all chats share the agent's
+  // one main session, so the model must see WHERE each message comes from or
+  // it answers chat B inside chat A's train of thought. The name is cosmetic
+  // garnish and must never block the emit/ack hot path (the catch-up sweep is
+  // fully serialized — one slow lookup would stall the whole backlog): only
+  // the cached name is used, and a miss kicks off a fire-and-forget prefetch
+  // so the NEXT message from this chat gets the name. The id alone already
+  // marks the context switch.
+  const chatName = await cachedChatName(ctx, chatId);
+  const senderId = msg?.sender_id ? String(msg.sender_id) : undefined;
+  const framedText = buildChatPrompt({
+    chatId,
+    chatName,
+    senderId,
+    threadRootId,
+    text,
+    attachments,
+  });
   const envelopeId = dispatchId || `${sourceType}:${sourceId}`;
+  // Input-step summary must never be empty (attachment-only messages).
+  const stepText = text || `[${attachments.length} attachment(s)]`;
+  // Thread-aware conversation identity: F2 grouping / F3 injection / fork
+  // routing all key on the subject, and a turn carries ONE reply route — a
+  // thread must never be absorbed into its sibling's turn (session.ts
+  // conversationKey doc).
+  const subject = conversationKey(chatId, threadRootId);
+
+  // Fork-on-busy scheduling (fork.ts): a live child owns its conversation;
+  // main mid-turn on ANOTHER conversation forks a new child; everything else
+  // rides main. Typed and channel_message dispatches always ride main.
+  const decision = await planForkDecision(ctx, subject, sourceId);
+
+  // Per-turn invocation context: parel snapshots this at turn start and
+  // consume-gated plugins receive it — sandbox-e2b flattens it into per-exec
+  // env, so `parall` CLI calls inside the sandbox land on the right chat.
+  const invocationContext: Record<string, string> = {
+    PRLL_CHAT_ID: chatId,
+    PRLL_TRIGGER_MESSAGE_ID: sourceId,
+    ...(threadRootId ? { PRLL_THREAD_ROOT_ID: threadRootId } : {}),
+  };
+
+  const envelope = {
+    id: envelopeId,
+    orgId,
+    connectionId: ctx.connectionId,
+    source: 'parall',
+    type: 'message' as const,
+    // The binding's `main` routing sends every envelope to the agent's
+    // one session; subject still carries the conversation (chat, or
+    // chat~thread) so parel's turn input grouping (F2) and mid-turn
+    // injection (F3) never mix conversations in one turn, and agent
+    // events mirror it back for per-conversation correlation.
+    subject,
+    data: { text: framedText, chatId, messageId: sourceId, threadRootId },
+    // chat id + thread anchor ride replyRoute.data so deliver() knows
+    // where to post back (same shape channel-slack-socket uses for its
+    // channel id).
+    replyRoute: {
+      kind: 'provider_http' as const,
+      connectionId: ctx.connectionId,
+      // envelopeId lets deliver() run the same staleness guard as
+      // onAgentEvent against the shared turnEnvelope marker.
+      data: { chatId, messageId: sourceId, threadRootId, envelopeId },
+    },
+    context: invocationContext,
+  };
+
+  if (decision.mode === 'deliverTo') {
+    // Follow-up for a conversation a live child owns: the envelope rides the
+    // full ingress contract but session resolution goes to the child (§18.2).
+    // Progress reporting lands on the CHILD's ase_ — its turn does the work,
+    // and the replyRoute carries childRef so deliver() links the reply to the
+    // child session (and idles IT, not main).
+    const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
+    const childAse = await ensureChildSession(ctx, decision.childRef);
+    if (childAse) {
+      const results = await Promise.all([
+        patchSession(ctx, childAse, { status: 'active', trigger_message_id: sourceId }),
+        createInputStep(ctx, childAse, {
+          chatId,
+          messageId: sourceId,
+          senderId,
+          text: stepText,
+        }),
+      ]);
+      // A closed child ase_ (New Session closed the whole family) just drops
+      // the cache; the next event rebuilds it.
+      if (results.includes('stale')) await invalidateChildSession(ctx, decision.childRef);
+    }
+    await receivedSettled;
+    const childEnvelope = {
+      ...envelope,
+      replyRoute: {
+        ...envelope.replyRoute,
+        data: { ...envelope.replyRoute.data, childRef: decision.childRef },
+      },
+    };
+    // Until the child's first observed event confirms provisioning, a
+    // deliverTo can still land in a spawn that fails terminally (the host
+    // ignores its queued events) — park the WorkItem ack on the bookkeeping
+    // row instead of consuming it on emit. Ingress dedupe (same envelope id)
+    // makes the eventual replay safe. A full parking list (cap) does NOT
+    // degrade to ack-on-emit — that would trade bounded storage for message
+    // loss; the overflow stays pending un-emitted and a later replay finds
+    // either a confirmed child (normal ack-on-emit) or a fresh decision.
+    if (decision.trackAck && dispatchId) {
+      const parked = await trackFollowUpAck(ctx, subject, decision.childRef, {
+        dispatchId,
+        sourceId,
+      });
+      if (!parked) {
+        // Parking cap hit: stay pending, but arm a local retry — a healthy
+        // long-lived socket never re-runs the reconnect sweep, so without a
+        // timer the overflow follow-up would strand until the next
+        // disconnect. By the retry the child is usually confirmed (normal
+        // ack-on-emit) or gone (fresh decision).
+        const retryKey = `${FORK_RETRY_PREFIX}${dispatchId}`;
+        await bumpForkRetryAttempts(ctx, retryKey, {
+          id: dispatchId,
+          source_type: sourceType,
+          source_id: sourceId,
+          chat_id: chatId,
+        });
+        return asConnectorEffects([
+          { type: 'setTimer', key: retryKey, at: ctx.now() + FORK_RETRY_DELAY_MS },
+        ]);
+      }
+      return asConnectorEffects([
+        { type: 'emitEvent', event: childEnvelope, deliverTo: { childRef: decision.childRef } },
+      ]);
+    }
+    return asConnectorEffects([
+      { type: 'emitEvent', event: childEnvelope, deliverTo: { childRef: decision.childRef } },
+      ackEffect(ctx, sourceType, sourceId),
+    ]);
+  }
+
+  if (decision.mode === 'spawn') {
+    // Main is mid-turn on another conversation — fork. The opening message
+    // IS the spawn input (one turn, no idle warm-up); its dispatch is NOT
+    // acked here: the pending ack (by WorkItem id) rides the fork bookkeeping
+    // and fires on the child's first observed event, so a spawn failure
+    // leaves the message recoverable instead of silently lost. A REPLAY of
+    // this same message re-enters here with the recorded childRef (fork.ts
+    // branch 1a): the platform spawn is idempotent on the ref, so re-issuing
+    // is both the transient-failure retry and the duplicate-processing guard.
+    // If the child is already CONFIRMED (events observed) the replay means
+    // only the ACK went missing — a re-spawn is a silent no-op that emits no
+    // new event, so ack directly instead of waiting for one.
+    const replayed = await childConfirmed(ctx, subject, decision.childRef);
+    if (replayed && dispatchId) {
+      return [ackByIdEffect(ctx, dispatchId)];
+    }
+    // Verification-cap check FIRST, before any side effect: onAgentEvent is
+    // best-effort — if every child event is lost, a replayed spawn is a
+    // silent idempotent no-op that never produces a new event, so each spawn
+    // pass bumps a bounded counter and re-arms a timer. Once the cap is
+    // exceeded the ref is a black hole: clear the fork bookkeeping and FALL
+    // THROUGH to the main path in THIS pass (emitting yet another spawn
+    // would leave the message stranded with no timer and no bookkeeping
+    // until a reconnect).
+    let spawnBlackHoled = false;
+    const timerEffects: ExtendedConnectorEffect[] = [];
+    if (dispatchId) {
+      const retryKey = `${FORK_RETRY_PREFIX}${dispatchId}`;
+      const attempts = await bumpForkRetryAttempts(ctx, retryKey, {
+        id: dispatchId,
+        source_type: sourceType,
+        source_id: sourceId,
+        chat_id: chatId,
+      });
+      if (attempts <= MAX_SPAWN_VERIFY_ATTEMPTS) {
+        timerEffects.push({ type: 'setTimer', key: retryKey, at: ctx.now() + FORK_RETRY_DELAY_MS });
+      } else {
+        spawnBlackHoled = true;
+        await clearForkSubject(ctx, subject, decision.childRef);
+        await ctx.store?.delete(retryKey).catch(() => {});
+      }
+    }
+    if (!spawnBlackHoled) {
+      const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
+      const childAse = await ensureChildSession(ctx, decision.childRef);
+      if (childAse) {
+        const results = await Promise.all([
+          patchSession(ctx, childAse, { status: 'active', trigger_message_id: sourceId }),
+          createInputStep(ctx, childAse, {
+            chatId,
+            messageId: sourceId,
+            senderId,
+            text: stepText,
+          }),
+        ]);
+        if (results.includes('stale')) await invalidateChildSession(ctx, decision.childRef);
+      }
+      await recordSpawn(ctx, subject, decision.childRef, { dispatchId, sourceId });
+      await receivedSettled;
+      return asConnectorEffects([
+        {
+          type: 'spawnChildSession',
+          childRef: decision.childRef,
+          input: buildForkScopePrefix(chatId, threadRootId) + framedText,
+          subject,
+        },
+        ...timerEffects,
+      ]);
+    }
+    // fall through: black-holed spawn rides main below.
+  }
+
+  // Main path. Progress reporting (best-effort,
+  // parall-runtime-indicator-plan.md §3): received lights the pending ring,
+  // the active+trigger patch arms the done signal, the input step flips the
+  // ring to processing. received MUST settle before this function returns —
+  // the ack effect below moves the dispatch row out of 'pending', and
+  // MarkReceived only transitions pending rows. It is deliberately NOT gated
+  // on the session resolving: it only touches the dispatch row, and a
+  // transient session failure must not also cost the pending ring (a later
+  // successful turn's idle clears agent-level pendings).
+  const receivedSettled = markDispatchReceived(ctx, sourceType, sourceId);
   let sessionId = await ensureSession(ctx);
   if (sessionId) {
     // The guard marker goes down BEFORE any session write: a stale
@@ -213,6 +636,7 @@ async function effectsForDispatch(
     // envelope id and idle the session out from under this message. The
     // marker is agent-global: chats share the one main session, so a chat-A
     // done signal must not idle it while this (later) message is pending.
+    // Child turns never touch it — only main-bound envelopes arm it.
     // (Residual read-then-patch overlap is zero when the host runs a
     // connection's hooks serially, per the C3 contract / C3b confirm item.)
     await ctx.store?.set(TURN_ENVELOPE_KEY, envelopeId).catch(() => {});
@@ -222,8 +646,8 @@ async function effectsForDispatch(
         createInputStep(ctx, sid, {
           chatId,
           messageId: sourceId,
-          senderId: msg?.sender_id ? String(msg.sender_id) : undefined,
-          text,
+          senderId,
+          text: stepText,
         }),
       ]);
     const results = await report(sessionId);
@@ -241,167 +665,55 @@ async function effectsForDispatch(
   }
   await receivedSettled;
 
-  // Per-turn invocation context: parel snapshots this at turn start and
-  // consume-gated plugins receive it — sandbox-e2b flattens it into per-exec
-  // env, so `parall` CLI calls inside the sandbox land on the right chat.
-  const invocationContext: Record<string, string> = {
-    PRLL_CHAT_ID: chatId,
-    PRLL_TRIGGER_MESSAGE_ID: sourceId,
-    ...(threadRootId ? { PRLL_THREAD_ROOT_ID: threadRootId } : {}),
-  };
-
-  // Frame the message with its chat of origin: all chats share the agent's
-  // one main session, so the model must see WHERE each message comes from or
-  // it answers chat B inside chat A's train of thought. The name is cosmetic
-  // garnish and must never block the emit/ack hot path (the catch-up sweep is
-  // fully serialized — one slow lookup would stall the whole backlog): only
-  // the cached name is used, and a miss kicks off a fire-and-forget prefetch
-  // so the NEXT message from this chat gets the name. The id alone already
-  // marks the context switch.
-  const chatName = await cachedChatName(ctx, chatId);
-  const framedText = buildChatPrompt({
-    chatId,
-    chatName,
-    senderId: msg?.sender_id ? String(msg.sender_id) : undefined,
-    threadRootId,
-    text,
-  });
-
-  const effects: ConnectorEffect[] = [
-    {
-      type: 'emitEvent',
-      event: {
-        id: envelopeId,
-        orgId,
-        connectionId: ctx.connectionId,
-        source: 'parall',
-        type: 'message',
-        // The binding's `main` routing sends every envelope to the agent's
-        // one session; subject still carries the chat so parel's turn input
-        // grouping (F2) never mixes conversations in one turn and agent
-        // events mirror it back for per-chat correlation.
-        subject: chatId,
-        data: { text: framedText, chatId, messageId: sourceId, threadRootId },
-        // chat id + thread anchor ride replyRoute.data so deliver() knows
-        // where to post back (same shape channel-slack-socket uses for its
-        // channel id).
-        replyRoute: {
-          kind: 'provider_http',
-          connectionId: ctx.connectionId,
-          // envelopeId lets deliver() run the same staleness guard as
-          // onAgentEvent against the shared turnEnvelope marker.
-          data: { chatId, messageId: sourceId, threadRootId, envelopeId },
-        },
-        context: invocationContext,
-      },
-    },
-    ackEffect(ctx, sourceType, sourceId),
-  ];
-  return effects;
+  return [{ type: 'emitEvent', event: envelope }, ackEffect(ctx, sourceType, sourceId)];
 }
 
 /**
- * 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.
+ * Typed (non-message) dispatch → main-session envelope. The heavy lifting
+ * (entity fetch + event-body rendering + stale/pending classification) lives
+ * in typed-dispatch.ts; this function owns the shared emit pipeline: session
+ * bookkeeping, the turnEnvelope marker, the envelope, and the ack.
  *
- * 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.
+ * Typed events always ride MAIN (never fork): nobody is watching a chat
+ * indicator for them, so head-of-line latency costs nothing, and keeping
+ * them on the orchestrator preserves task/schedule context continuity.
  */
-async function effectsForChannelDispatch(
-  sourceId: string,
-  dispatchId: string,
+async function effectsForTypedDispatch(
+  data: DispatchData,
   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;
+  // No markDispatchReceived here ON PURPOSE: typed dispatches have no
+  // message-level activity indicator (DispatchResolvedData: "typed
+  // dispatches have no indicator"), so there is no pending ring to light —
+  // the typed input step below is the session panel's timeline entry.
+  const sourceType = String(data.source_type ?? '');
+  const sourceId = String(data.source_id ?? '');
+  const dispatchId = String(data.id ?? '');
+  // Typed WorkItems ack by id, never by source: sibling rows (a task
+  // mutation's task_assign + task_update) share (source_type, source_id),
+  // and the source ack would terminally resolve work that was never emitted.
+  const ack = () =>
+    dispatchId ? ackByIdEffect(ctx, dispatchId) : ackEffect(ctx, sourceType, sourceId);
+  const plan = await planTypedDispatch(data, ctx);
+  if (plan.outcome === 'pending') return [];
+  if (plan.outcome === 'stale') return [ack()];
 
-  // 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}`;
+  const envelopeId = dispatchId || `${sourceType}:${sourceId}`;
   let sessionId = await ensureSession(ctx);
   if (sessionId) {
+    // Same marker contract as the message path: a typed envelope is now the
+    // agent's latest emitted input, so older turns' done signals must not
+    // idle the session out from under it.
     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,
+        patchSession(ctx, sid, { status: 'active' }),
+        createTypedInputStep(ctx, sid, {
+          target: plan.stepTarget,
+          triggerType: plan.triggerType,
+          dispatchId,
+          sourceId,
+          summary: plan.summary,
         }),
       ]);
     const results = await report(sessionId);
@@ -413,75 +725,46 @@ async function effectsForChannelDispatch(
         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,
+        orgId: parallOrgId(ctx),
         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).
+        // Subject = the source entity (task/schedule/trigger/…): F2 groups
+        // consecutive events for one entity into one turn and never mixes
+        // them with chat conversations.
+        subject: plan.subject,
+        data: { text: plan.body, sourceType, sourceId },
         replyRoute: {
           kind: 'provider_http',
           connectionId: ctx.connectionId,
-          data: { conversationId, envelopeId },
+          // approval_decided replies deliver to its chat; every other typed
+          // event has no delivery target (deliver() only runs the redundant
+          // idle off envelopeId) — the agent acts via its sandbox CLI.
+          data: plan.chatId
+            ? { chatId: plan.chatId, messageId: sourceId, envelopeId }
+            : { 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.
+        ...(plan.chatId
+          ? {
+              context: {
+                PRLL_CHAT_ID: plan.chatId,
+                PRLL_TRIGGER_MESSAGE_ID: sourceId,
+              },
+            }
+          : {}),
       },
     },
-    ackEffect(ctx, 'channel_message', sourceId),
+    ack(),
   ];
 }
 
-/**
- * connection id → provider alias, cached in the durable store (stable
- * mapping; avoids one connection fetch per inbound message). Cache hits are
- * a store read; the miss-path fetch is cosmetic (prompt labeling only), so
- * it gets 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. Any failure returns undefined — prompt wording
- * degrades to neutral rather than inventing a clip alias.
- */
-const PROVIDER_LOOKUP_TIMEOUT_MS = 3_000;
-
 /**
  * How long a cached chat name is served without revalidation. Chat renames
  * are rare and the frame is the model's cross-chat context anchor, so serve
@@ -550,58 +833,6 @@ async function prefetchChatName(
   }
 }
 
-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);
-  }
-}
-
 /**
  * Agent execution events (parel E1+E2, plugin-sdk 0.9.0, opt-in via the
  * channel declaration's `observe: [turn, steps]`).
@@ -619,20 +850,76 @@ async function recordConversationSession(
  * done event just means the ring clears on the next turn's trigger change; a
  * missed trace step is a gap in the panel, nothing more.
  */
-export async function handleParallAgentEvent(
+export function handleParallAgentEvent(
   event: AgentEvent,
   ctx: ConnectorContext,
 ): Promise<AgentEventEffect[]> {
+  return serialized(() => handleParallAgentEventInner(event, ctx));
+}
+
+async function handleParallAgentEventInner(
+  event: AgentEvent,
+  ctx: ConnectorContext,
+): Promise<AgentEventEffect[]> {
+  // spawnChildSession's asynchronous error channel — not turn-scoped, pushed
+  // regardless of observe scopes, and shaped outside the published AgentEvent
+  // union (see parel-sdk-compat). Handle it before anything subject-gated.
+  const spawnFailed = asChildSpawnFailed(event);
+  if (spawnFailed) {
+    const effects: AgentEventEffect[] = [];
+    try {
+      const outcome = await handleChildSpawnFailed(ctx, spawnFailed);
+      if (outcome.cleared) {
+        // The spawn's ase_ was already created active with an input step; no
+        // child turn will ever emit a terminal event for it — settle it here
+        // or the session (and its processing indicator) stays active forever.
+        const orphanAse = await ensureChildSession(ctx, spawnFailed.childRef);
+        if (orphanAse) await patchSession(ctx, orphanAse, { status: 'idle' });
+        await invalidateChildSession(ctx, spawnFailed.childRef);
+      }
+      // Re-drive the stranded messages WITHOUT waiting for a reconnect sweep
+      // (a healthy long-lived socket never re-runs onOpen): park their
+      // coordinates and arm a timer — onTimer re-plans them through the
+      // normal dispatch pipeline (transient failures re-enter branch 1a with
+      // the same ref; terminal ones re-plan from scratch).
+      if (outcome.subject && outcome.pendingAcks.length > 0) {
+        const chatId = outcome.subject.split('~')[0];
+        for (const ack of outcome.pendingAcks) {
+          const key = `${FORK_RETRY_PREFIX}${ack.dispatchId}`;
+          await bumpForkRetryAttempts(ctx, key, {
+            id: ack.dispatchId,
+            source_type: 'message',
+            source_id: ack.sourceId,
+            chat_id: chatId,
+          });
+          effects.push({ type: 'setTimer', key, at: ctx.now() + FORK_RETRY_DELAY_MS });
+        }
+      }
+    } catch (err) {
+      console.error('[parel-channel] child spawn failure handling failed', err);
+    }
+    return effects;
+  }
+  const withChild = event as AgentEventWithChild;
+  if (withChild.childRef) {
+    return handleChildAgentEvent(withChild, ctx);
+  }
   const chatId = event.subject;
-  if (!chatId) return [];
   try {
+    // Best-effort busy classifier for fork-on-busy: only MAIN turns feed it
+    // (child events took the branch above).
+    await noteMainTurnEvent(ctx, withChild).catch(() => {});
+    if (!chatId) return [];
     if (event.type === 'turn_completed' || event.type === 'turn_failed') {
       // Staleness guard: only idle if this event's turn covers the AGENT'S
       // latest emitted envelope (the marker is agent-global — all chats share
       // the one main session, so a done signal for chat A's turn must not
       // clear the indicator while a later chat-B message is queued/running).
-      // A late/retried event for a superseded turn is dropped. Fail-open
-      // when the marker is unavailable (a stuck ring is worse than a blink).
+      // With injectInFlight (parel F3), an absorbed envelope has no turn of
+      // its own — its id is appended to the absorbing turn's envelopeIds, so
+      // this membership check settles it naturally. A late/retried event for
+      // a superseded turn is dropped. Fail-open when the marker is
+      // unavailable (a stuck ring is worse than a blink).
       const current = await ctx.store?.get(TURN_ENVELOPE_KEY).catch(() => null);
       if (typeof current === 'string' && current && !event.envelopeIds.includes(current)) {
         return [];
@@ -672,28 +959,72 @@ export async function handleParallAgentEvent(
       }
       return [];
     }
-    // turn_started (processing is input-step-driven) and execution_paused
-    // (E3 — no resolve loop wired yet, HITL deliberately deferred) are
-    // ignored; observe only requests [turn, steps].
+    // turn_started feeds only the busy classifier above (processing is
+    // input-step-driven); execution_paused (E3 — no resolve loop wired yet,
+    // HITL deliberately deferred) is ignored.
   } catch (err) {
     console.error('[parel-channel] agent event handling failed', err);
   }
   return [];
 }
 
-/** Ack a dispatch by source so it leaves the pending queue (idempotent). */
-function ackEffect(ctx: ConnectorContext, sourceType: string, sourceId: string): ConnectorEffect {
-  return {
-    type: 'fetch',
-    request: {
-      url: `${parallApiUrl(ctx)}/api/v1/orgs/${parallOrgId(ctx)}/dispatch/ack`,
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${requireAgk(ctx)}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ source_type: sourceType, source_id: sourceId }),
-    },
-    idempotencyKey: `ack:${sourceType}:${sourceId}`,
-  };
+/**
+ * Agent events from a connector-spawned fork child (they carry childRef).
+ * Mirrors the main-session handling against the CHILD's ase_ instead:
+ * turn done → idle the child session (its indicator/panel), turn_failed →
+ * error step first, E2 → trace steps. Additionally settles the fork's
+ * pending spawn ack: the opening dispatch is acked on the child's first
+ * observed event (a spawn that never produces one leaves it pending for the
+ * catch-up sweep — see fork.ts). Child turns never touch the main session's
+ * turnEnvelope marker or the busy classifier.
+ */
+async function handleChildAgentEvent(
+  event: AgentEventWithChild,
+  ctx: ConnectorContext,
+): Promise<AgentEventEffect[]> {
+  const childRef = event.childRef ?? '';
+  const effects: AgentEventEffect[] = [];
+  try {
+    const settled = await settleChildEvent(ctx, event).catch(() => null);
+    for (const ack of settled?.pendingAcks ?? []) {
+      // Ack the fork's parked WorkItems (by id) — the child demonstrably
+      // exists and holds them. Re-sent on later events (bounded) because the
+      // fetch effect is fire-and-forget; the ack endpoint is idempotent.
+      effects.push(ackByIdEffect(ctx, ack.dispatchId));
+    }
+    const subject = event.subject || settled?.subject || '';
+    if (!subject) return effects;
+    // A childRef outside live bookkeeping is a LATE callback (post-reset or
+    // post-give-up): resolving a session here would blind-recreate a fork
+    // ase_ under the new conversation line — drop the event instead.
+    if (!(await childRefKnown(ctx, childRef))) return effects;
+    const sessionId = await ensureChildSession(ctx, childRef);
+    if (!sessionId) return effects;
+    if (event.type === 'turn_completed' || event.type === 'turn_failed') {
+      let stale = false;
+      if (event.type === 'turn_failed') {
+        const stepResult = await createErrorStep(ctx, sessionId, {
+          subject,
+          turnId: event.turnId,
+          error: event.error,
+        });
+        stale = stepResult === 'stale';
+      }
+      const result = await patchSession(ctx, sessionId, { status: 'idle' });
+      if (stale || result === 'stale') await invalidateChildSession(ctx, childRef);
+      return effects;
+    }
+    if (
+      event.type === 'model_reasoning' ||
+      event.type === 'tool_call' ||
+      event.type === 'tool_result'
+    ) {
+      const result = await createTraceStep(ctx, sessionId, subject, event);
+      if (result === 'stale') await invalidateChildSession(ctx, childRef);
+      return effects;
+    }
+  } catch (err) {
+    console.error('[parel-channel] child agent event handling failed', err);
+  }
+  return effects;
 }