@parall/parel-channel 1.40.0 → 1.41.0

package/dist/inbound.js

@@ -1,7 +1,47 @@
-import { buildChannelPrompt, buildChatPrompt } from './channel-prompt.js';
-import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
-import { createChannelInputStep, createErrorStep, createInputStep, createTraceStep, ensureSession, invalidateSession, markDispatchReceived, patchSession, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, } from './session.js';
-export async function handleParallFrame(frame, ctx) {
+import { buildChatPrompt } from './channel-prompt.js';
+import { parallApiUrl, parallOrgId, requireAgk, sandboxEnabled } from './connect.js';
+import { effectsForChannelDispatch, PROVIDER_LOOKUP_TIMEOUT_MS } from './inbound-channel.js';
+import { 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 { asChildSpawnFailed, asConnectorEffects, } from './parel-sdk-compat.js';
+import { ackByIdEffect, ackEffect, conversationKey, createErrorStep, fetchMainSessionFresh, createInputStep, createTraceStep, createTypedInputStep, ensureChildSession, ensureSession, invalidateChildSession, invalidateSession, markDispatchReceived, patchSession, reportingEnabled, SESSION_CACHE_KEY, TURN_ENVELOPE_KEY, } from './session.js';
+import { isTypedEventType, planTypedDispatch } from './typed-dispatch.js';
+/**
+ * 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.resolve();
+let chainConnectionId;
+/** Surface a violated isolation assumption as a log line, not silent
+ * mis-serialization (see the chain doc above). */
+export function assertChainConnection(ctx) {
+    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(fn) {
+    const next = hookChain.then(fn, fn);
+    hookChain = next.then(() => undefined, () => undefined);
+    return next;
+}
+export function handleParallFrame(frame, ctx) {
+    assertChainConnection(ctx);
+    return serialized(() => handleParallFrameInner(frame, ctx));
+}
+async function handleParallFrameInner(frame, ctx) {
     let event;
     try {
         const raw = typeof frame.data === 'string' ? frame.data : new TextDecoder().decode(frame.data);
@@ -10,6 +50,23 @@ export async function handleParallFrame(frame, ctx) {
     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 {
@@ -22,21 +79,94 @@ export async function handleParallFrame(frame, ctx) {
         return [];
     }
 }
+/**
+ * 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, ctx) {
+    return serialized(() => handleParallTimerInner(timer, ctx));
+}
+async function handleParallTimerInner(timer, ctx) {
+    if (!timer.key.startsWith(FORK_RETRY_PREFIX))
+        return [];
+    const parked = (await ctx.store?.get(timer.key).catch(() => 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.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) {
+export function catchUpParall(ctx) {
+    return serialized(() => catchUpParallInner(ctx));
+}
+async function catchUpParallInner(ctx) {
+    // 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));
+        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 = [];
     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
@@ -92,11 +222,30 @@ async function effectsForDispatch(data, ctx) {
         // 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) {
@@ -123,22 +272,238 @@ async function effectsForDispatch(data, ctx) {
     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 = (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 = {
+        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',
+        // 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',
+            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 = [];
+        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
@@ -148,6 +513,7 @@ async function effectsForDispatch(data, ctx) {
         // 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(() => { });
@@ -156,8 +522,8 @@ async function effectsForDispatch(data, ctx) {
             createInputStep(ctx, sid, {
                 chatId,
                 messageId: sourceId,
-                senderId: msg?.sender_id ? String(msg.sender_id) : undefined,
-                text,
+                senderId,
+                text: stepText,
             }),
         ]);
         const results = await report(sessionId);
@@ -174,142 +540,50 @@ async function effectsForDispatch(data, ctx) {
         }
     }
     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 = {
-        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 = [
-        {
-            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, dispatchId, ctx) {
-    const apiUrl = parallApiUrl(ctx);
-    const orgId = parallOrgId(ctx);
-    const authHeaders = { Authorization: `Bearer ${requireAgk(ctx)}` };
-    const get = (path, timeoutMs = 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));
-    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)];
-        }
+async function effectsForTypedDispatch(data, ctx) {
+    // 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 [];
-    }
-    const conv = (await c.json().catch(() => 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}`;
+    if (plan.outcome === 'stale')
+        return [ack()];
+    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) => 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);
@@ -321,72 +595,44 @@ async function effectsForChannelDispatch(sourceId, dispatchId, ctx) {
                 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
@@ -445,51 +691,6 @@ async function prefetchChatName(ctx, chatId, cacheKey) {
         // Cosmetic prefetch — the next message from this chat retries.
     }
 }
-async function resolveChannelProvider(ctx, connectionId, get) {
-    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));
-        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, conversationId, sessionId) {
-    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]`).
@@ -507,18 +708,72 @@ async function recordConversationSession(ctx, conversationId, sessionId) {
  * 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(event, ctx) {
+export function handleParallAgentEvent(event, ctx) {
+    return serialized(() => handleParallAgentEventInner(event, ctx));
+}
+async function handleParallAgentEventInner(event, ctx) {
+    // 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 = [];
+        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;
+    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 [];
@@ -558,28 +813,73 @@ export async function handleParallAgentEvent(event, ctx) {
             }
             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, sourceType, sourceId) {
-    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, ctx) {
+    const childRef = event.childRef ?? '';
+    const effects = [];
+    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;
 }