@parall/parel-channel 1.40.0 → 1.42.0

package/dist/fork.js

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

package/dist/inbound-channel.d.ts

@@ -0,0 +1,29 @@
+import type { ConnectorContext, ConnectorEffect } from '@parel/plugin-sdk';
+/**
+ * External IM inbound (channel_message dispatches — Feishu/Slack via the
+ * platform-mediated channel, external-im-channel-design.md). Split from
+ * inbound.ts as a pure move; the pipeline contract lives there.
+ */
+/**
+ * Miss-path lookups here are cosmetic (prompt labeling only), so they get a
+ * tight timeout — same 3s budget as deliver's front-of-reply session lookup —
+ * rather than holding the message's emit/ack behind the full
+ * REQUEST_TIMEOUT_MS. Also reused by inbound.ts's chat-name prefetch.
+ */
+export declare const PROVIDER_LOOKUP_TIMEOUT_MS = 3000;
+/**
+ * channel_message dispatch → agent (external IM channel,
+ * external-im-channel-design.md). Same pipeline shape as the message path,
+ * with the ChannelConversation (chv_) standing in for the chat as the
+ * routing subject: fetch the durable ChannelMessage + its conversation,
+ * resolve the provider for prompt labeling (cached — the connection→provider
+ * mapping is stable), frame the prompt for the EXTERNAL audience, report
+ * progress against the conversation-keyed session, and ack by source.
+ *
+ * Error contract mirrors the message path (and agent-core's
+ * fetchAndHandleChannelMessage): 404/403 on the source entities is
+ * permanently unusable → ack-and-drop; a transient failure keeps the
+ * dispatch pending for the catch-up sweep.
+ */
+export declare function effectsForChannelDispatch(sourceId: string, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+//# sourceMappingURL=inbound-channel.d.ts.map

package/dist/inbound-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-channel.d.ts","sourceRoot":"","sources":["../src/inbound-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAiB3E;;;;GAIG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CA6J5B"}

package/dist/inbound-channel.js

@@ -0,0 +1,219 @@
+import { buildChannelPrompt } from './channel-prompt.js';
+import { parallApiUrl, parallOrgId, requireAgk } from './connect.js';
+import { ackEffect, createChannelInputStep, ensureSession, invalidateSession, markDispatchReceived, nextEnvelopeId, patchSession, readActiveEmit, REQUEST_TIMEOUT_MS, TURN_ENVELOPE_KEY, writeActiveEmit, } from './session.js';
+/**
+ * External IM inbound (channel_message dispatches — Feishu/Slack via the
+ * platform-mediated channel, external-im-channel-design.md). Split from
+ * inbound.ts as a pure move; the pipeline contract lives there.
+ */
+/**
+ * Miss-path lookups here are cosmetic (prompt labeling only), so they get a
+ * tight timeout — same 3s budget as deliver's front-of-reply session lookup —
+ * rather than holding the message's emit/ack behind the full
+ * REQUEST_TIMEOUT_MS. Also reused by inbound.ts's chat-name prefetch.
+ */
+export const PROVIDER_LOOKUP_TIMEOUT_MS = 3_000;
+/**
+ * channel_message dispatch → agent (external IM channel,
+ * external-im-channel-design.md). Same pipeline shape as the message path,
+ * with the ChannelConversation (chv_) standing in for the chat as the
+ * routing subject: fetch the durable ChannelMessage + its conversation,
+ * resolve the provider for prompt labeling (cached — the connection→provider
+ * mapping is stable), frame the prompt for the EXTERNAL audience, report
+ * progress against the conversation-keyed session, and ack by source.
+ *
+ * Error contract mirrors the message path (and agent-core's
+ * fetchAndHandleChannelMessage): 404/403 on the source entities is
+ * permanently unusable → ack-and-drop; a transient failure keeps the
+ * dispatch pending for the catch-up sweep.
+ */
+export async function effectsForChannelDispatch(sourceId, 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)];
+        }
+        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 this function returns;
+    // the turnEnvelope marker goes down before any session write; the row
+    // stays 'received' until the turn event's complete-sources.
+    const receivedSettled = markDispatchReceived(ctx, 'channel_message', sourceId);
+    const priorEmit = await readActiveEmit(ctx, 'channel_message', sourceId);
+    const envelopeId = nextEnvelopeId('channel_message', sourceId, priorEmit);
+    let sessionId = await ensureSession(ctx);
+    if (sessionId) {
+        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,
+            }),
+        ]);
+        const results = await report(sessionId);
+        if (results.includes('stale')) {
+            await invalidateSession(ctx);
+            const fresh = await ensureSession(ctx);
+            if (fresh && fresh !== sessionId) {
+                await report(fresh);
+                sessionId = fresh;
+            }
+        }
+        // Record the durable chv_ ↔ ase_ mapping (ops drill-down from a
+        // conversation into its session; last-write-wins on the server). Only on
+        // change — the store remembers what was last pushed — and fully
+        // fire-and-forget: pure bookkeeping must never add latency to the
+        // emit/ack path (a lost attempt is retried on the next message because
+        // the store memo only updates on success).
+        void recordConversationSession(ctx, conversationId, sessionId).catch(() => { });
+    }
+    await receivedSettled;
+    await writeActiveEmit(ctx, 'channel_message', sourceId, envelopeId);
+    return [
+        {
+            type: 'emitEvent',
+            event: {
+                id: envelopeId,
+                orgId,
+                connectionId: ctx.connectionId,
+                source: 'parall',
+                // The host's message intake path turns data.text into the user
+                // message — the external-audience framing rides inside it (parel has
+                // no separate prompt channel), so 'message' is the right type here.
+                type: 'message',
+                // main routing sends this to the agent's one session too; subject
+                // still carries the external conversation (chv_) for parel's turn
+                // input grouping (F2) and per-conversation event correlation.
+                subject: conversationId,
+                data: {
+                    text: buildChannelPrompt({
+                        provider,
+                        conversationType: conv?.conversation_type ? String(conv.conversation_type) : undefined,
+                        externalConversationId,
+                        externalMessageId,
+                        senderName,
+                        text,
+                    }),
+                    conversationId,
+                    channelMessageId: sourceId,
+                    provider,
+                    externalConversationId,
+                    externalMessageId,
+                },
+                // No chatId on purpose: the reply goes out through the provider clip
+                // (agent-invoked), NOT deliver() — deliver only runs the redundant
+                // session idle for channel routes (see delivery.ts).
+                replyRoute: {
+                    kind: 'provider_http',
+                    connectionId: ctx.connectionId,
+                    data: { conversationId, envelopeId },
+                },
+                // No invocation context: PRLL_CHAT_ID must not point CLI defaults at
+                // a chat that doesn't exist, and the reply targets (external ids)
+                // already ride the prompt verbatim. (So no PRLL_DISPATCH_SOURCE_*
+                // either — the external reply goes out through the provider clip,
+                // and this row's ledger close is the turn event's complete-sources.)
+            },
+        },
+        // No ack effect — see the message path (inbound.ts): the row stays
+        // received until complete-sources closes it.
+    ];
+}
+/**
+ * connection id → provider alias, cached in the durable store (stable
+ * mapping; avoids one connection fetch per inbound message). Cache hits are
+ * a store read; any failure returns undefined — prompt wording degrades to
+ * neutral rather than inventing a clip alias.
+ */
+async function resolveChannelProvider(ctx, 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);
+    }
+}

package/dist/inbound.d.ts

@@ -1,5 +1,19 @@
 import type { AgentEvent, AgentEventEffect, ConnectorContext, ConnectorEffect, WebSocketFrame } from '@parel/plugin-sdk';
+/** Surface a violated isolation assumption as a log line, not silent
+ * mis-serialization (see the chain doc above). */
+export declare function assertChainConnection(ctx: ConnectorContext): void;
+export declare function serialized<T>(fn: () => Promise<T>): Promise<T>;
 export declare function handleParallFrame(frame: WebSocketFrame, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
+/**
+ * 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 declare function handleParallTimer(timer: {
+    key: string;
+}, ctx: ConnectorContext): Promise<ConnectorEffect[]>;
 /**
  * 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

package/dist/inbound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAiD3B,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB5B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAuDrF;AAkdD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyD7B"}
+{"version":3,"file":"inbound.d.ts","sourceRoot":"","sources":["../src/inbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACf,MAAM,mBAAmB,CAAC;AAuH3B;kDACkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CASjE;AACD,wBAAgB,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAO9D;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAwCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EACtB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAE5B;AA8BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAE/E;AAwpBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAE7B"}